Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

minor: configure model routing and fallback effort (#2055)

Ali Khokharbe4d425b1693
diff --git a/README.md b/README.md
index 849c7618..551a1523 100644
--- a/README.md
+++ b/README.md
@@ -338,19 +338,25 @@ Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL`
`MODEL` is the fallback for every request. Select a model for `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override an individual Claude Code tier. Select **None** to use `MODEL`.
+In **Admin UI → Model Config**, add **Fallback Models** in the order FCC should try them if the selected model fails. Each fallback has its own reasoning effort: **Inherit**, **Off**, **From client**, **Low**, **Medium**, **High**, **X-High**, or **Max**.
+
+Choose a model and effort in the bottom row, then click **+**. Edit either dropdown in place, drag the handle to change the order, or click the red trash button to remove a fallback.
+
+**Inherit** keeps the original request's resolved reasoning setting. **From client** uses the effort or token budget sent by your coding agent, bypassing the global or tier setting. A fallback matching the selected provider/model is skipped.
+
</details>
<details>
<summary><strong>Reasoning control</strong></summary>
-Open **Admin UI → Model Config → Reasoning** and select the behavior you want.
+Open **Admin UI → Model Config → Model Routing** and choose an effort beside each model. **Default Effort** starts at **From client**. Fable, Opus, Sonnet, and Haiku start at **Inherit**.
| Selection | Behavior |
| --- | --- |
-| **From client** (default) | Use the effort sent by your coding agent. If none is sent, keep the provider default. |
+| **From client** | Use the effort sent by your coding agent. If none is sent, keep the provider default. |
| **Off** | Request reasoning to be disabled. |
| **Low**, **Medium**, **High**, **X-High**, or **Max** | Override the client with the selected reasoning level. |
-| **Inherit** (Fable, Opus, Sonnet, and Haiku only) | Use the root Reasoning selection. |
+| **Inherit** | Tier overrides use Default Effort. Fallbacks keep the original request's resolved effort. |
Providers that do not support a selected control retain their own behavior.
diff --git a/e2e/test_admin_models.py b/e2e/test_admin_models.py
index 54c24729..ca67c8a0 100644
--- a/e2e/test_admin_models.py
+++ b/e2e/test_admin_models.py
@@ -1,7 +1,9 @@
"""Rendered model-fallback controls for the local Admin UI."""
+import json
+
import pytest
-from playwright.sync_api import Page, expect
+from playwright.sync_api import Locator, Page, expect
from e2e.provider_support import close_provider, open_provider
@@ -23,6 +25,117 @@ def _refresh_openrouter_models(page: Page) -> None:
page.get_by_role("button", name="Model Config", exact=True).click()
+def _fallbacks(editor: Locator) -> list[dict[str, str]]:
+ value = editor.locator("#field-MODEL_FALLBACKS").input_value()
+ return json.loads(value) if value else []
+
+
+def test_model_routing_pairs_five_models_with_effort_and_defaults(
+ page: Page, admin_base_url: str
+) -> None:
+ page.set_viewport_size({"width": 1280, "height": 900})
+ _open_models(page, admin_base_url)
+ expect(page.locator("#section-reasoning")).to_have_count(0)
+ routes = ("Default", "Fable", "Opus", "Sonnet", "Haiku")
+ previous_bottom = 0.0
+ for route in routes:
+ group = page.get_by_role("group", name=f"{route} model and effort", exact=True)
+ model_key = "MODEL" if route == "Default" else f"MODEL_{route.upper()}"
+ effort_key = (
+ "REASONING_POLICY" if route == "Default" else f"REASONING_{route.upper()}"
+ )
+ model = group.locator(f"#field-{model_key}")
+ effort = group.locator(f"#field-{effort_key}")
+ expect(model).to_be_visible()
+ expect(effort).to_have_value("client" if route == "Default" else "inherit")
+ if route != "Default":
+ expect(model).to_have_value("None")
+ expect(effort).to_be_enabled()
+ model_box, effort_box = model.bounding_box(), effort.bounding_box()
+ assert model_box is not None and effort_box is not None
+ assert abs(model_box["width"] - effort_box["width"]) <= 1
+ assert abs(model_box["height"] - effort_box["height"]) <= 1
+ assert abs(model_box["y"] - effort_box["y"]) <= 1
+ assert model_box["x"] < effort_box["x"]
+ assert model_box["y"] > previous_bottom
+ previous_bottom = model_box["y"] + model_box["height"]
+ expect(page.locator("#field-REASONING_POLICY option[value=inherit]")).to_have_count(
+ 0
+ )
+ fallback_box = page.locator('.field[data-key="MODEL_FALLBACKS"]').bounding_box()
+ assert fallback_box is not None and fallback_box["y"] > previous_bottom
+
+
+def test_model_routing_saves_independent_model_and_effort_choices(
+ page: Page, admin_base_url: str
+) -> None:
+ _open_models(page, admin_base_url)
+ page.locator("#field-REASONING_POLICY").select_option("medium")
+ opus = page.get_by_role("group", name="Opus model and effort", exact=True)
+ expect(opus.locator("#field-MODEL_OPUS")).to_have_value("None")
+ opus.locator("#field-REASONING_OPUS").select_option("high")
+ sonnet = page.get_by_role("group", name="Sonnet model and effort", exact=True)
+ sonnet.locator("#field-MODEL_SONNET").fill("open_router/vendor/model-b")
+ sonnet.locator("#field-REASONING_SONNET").select_option("low")
+ fallback = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ fallback.locator("#field-MODEL_FALLBACKS-add").fill("open_router/vendor/model-a")
+ fallback.get_by_label("Fallback reasoning effort", exact=True).select_option("off")
+ fallback.get_by_role("button", name="Add fallback", exact=True).click()
+ with page.expect_response("**/admin/api/config/apply") as saved:
+ page.locator("#applyButton").click()
+ assert saved.value.json()["applied"] is True
+ payload = saved.value.request.post_data_json
+ assert isinstance(payload, dict)
+ values = payload["values"]
+ assert values["REASONING_POLICY"] == "medium"
+ assert values["REASONING_OPUS"] == "high"
+ assert "MODEL_OPUS" not in values
+ assert values["MODEL_SONNET"] == "open_router/vendor/model-b"
+ assert values["REASONING_SONNET"] == "low"
+ assert json.loads(values["MODEL_FALLBACKS"]) == [
+ {"model": "open_router/vendor/model-a", "reasoning": "off"}
+ ]
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ page.reload()
+ expect(page.locator("#messageArea")).to_have_text("")
+ expect(page.locator("#field-REASONING_POLICY")).to_have_value("medium")
+ expect(opus.locator("#field-MODEL_OPUS")).to_have_value("None")
+ expect(opus.locator("#field-REASONING_OPUS")).to_have_value("high")
+ expect(sonnet.locator("#field-MODEL_SONNET")).to_have_value(
+ "open_router/vendor/model-b"
+ )
+ expect(sonnet.locator("#field-REASONING_SONNET")).to_have_value("low")
+ assert _fallbacks(fallback) == [
+ {"model": "open_router/vendor/model-a", "reasoning": "off"}
+ ]
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+
+
+ "admin_base_url",
+ [
+ {
+ "MODEL_OPUS": "groq/locked-model",
+ "REASONING_SONNET": "off",
+ "REASONING_POLICY": "client",
+ }
+ ],
+ indirect=True,
+)
+def test_process_owned_route_controls_lock_independently(
+ page: Page, admin_base_url: str
+) -> None:
+ _open_models(page, admin_base_url)
+ expect(page.locator("#field-REASONING_POLICY")).to_have_value("client")
+ expect(page.locator("#field-REASONING_POLICY")).to_be_disabled()
+ opus = page.get_by_role("group", name="Opus model and effort", exact=True)
+ expect(opus.locator("#field-MODEL_OPUS")).to_be_disabled()
+ expect(opus.locator("#field-REASONING_OPUS")).to_be_enabled()
+ sonnet = page.get_by_role("group", name="Sonnet model and effort", exact=True)
+ expect(sonnet.locator("#field-MODEL_SONNET")).to_be_enabled()
+ expect(sonnet.locator("#field-REASONING_SONNET")).to_be_disabled()
+
+
def test_fallback_editor_adds_filters_reorders_and_removes_models(
page: Page,
admin_base_url: str,
@@ -33,10 +146,9 @@ def test_fallback_editor_adds_filters_reorders_and_removes_models(
editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
add_input = editor.locator("#field-MODEL_FALLBACKS-add")
+ add_effort = editor.get_by_label("Fallback reasoning effort", exact=True)
stored_value = editor.locator("#field-MODEL_FALLBACKS")
- expect(editor.locator(".model-list-empty")).to_have_text(
- "No fallback models configured."
- )
+ expect(editor.locator(".model-list-row")).to_have_count(0)
add_input.fill("model-b")
expect(
@@ -45,32 +157,44 @@ def test_fallback_editor_adds_filters_reorders_and_removes_models(
add_input.press("ArrowDown")
add_input.press("Enter")
expect(add_input).to_have_value("open_router/vendor/model-b")
- editor.get_by_role("button", name="Add", exact=True).click()
+ add_effort.select_option("low")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ expect(add_effort).to_have_value("inherit")
+ expect(add_input).to_have_value("")
add_input.fill("groq/custom-model")
- editor.get_by_role("button", name="Add", exact=True).click()
- expect(stored_value).to_have_value("open_router/vendor/model-b,groq/custom-model")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ assert _fallbacks(editor) == [
+ {"model": "open_router/vendor/model-b", "reasoning": "low"},
+ {"model": "groq/custom-model", "reasoning": "inherit"},
+ ]
expect(page.locator("#dirtyState")).to_have_text("1 unsaved change")
expect(page.locator("#applyButton")).to_be_enabled()
- editor.get_by_role("button", name="Move groq/custom-model up", exact=True).click()
- expect(stored_value).to_have_value("groq/custom-model,open_router/vendor/model-b")
- expect(
- editor.get_by_role("button", name="Move groq/custom-model up", exact=True)
- ).to_be_disabled()
- expect(
- editor.get_by_role(
- "button", name="Move open_router/vendor/model-b down", exact=True
- )
- ).to_be_disabled()
-
+ rows = editor.locator(".model-list-row")
+ expect(rows.locator('input[role="combobox"]')).to_have_count(2)
+ last_model_box = editor.get_by_role(
+ "combobox", name="Fallback model 2", exact=True
+ ).bounding_box()
+ add_model_box = add_input.bounding_box()
+ assert last_model_box is not None and add_model_box is not None
+ assert add_model_box["y"] > last_model_box["y"]
+ editor.get_by_role("button", name="Move groq/custom-model", exact=True).drag_to(
+ rows.nth(0), target_position={"x": 10, "y": 5}
+ )
+ assert _fallbacks(editor) == [
+ {"model": "groq/custom-model", "reasoning": "inherit"},
+ {"model": "open_router/vendor/model-b", "reasoning": "low"},
+ ]
editor.get_by_role("button", name="Remove groq/custom-model", exact=True).click()
- expect(stored_value).to_have_value("open_router/vendor/model-b")
+ assert _fallbacks(editor) == [
+ {"model": "open_router/vendor/model-b", "reasoning": "low"}
+ ]
editor.get_by_role(
"button", name="Remove open_router/vendor/model-b", exact=True
).click()
expect(stored_value).to_have_value("")
- expect(editor.locator(".model-list-empty")).to_be_visible()
+ expect(editor.locator(".model-list-row")).to_have_count(0)
expect(page.locator("#dirtyState")).to_have_text("No changes")
expect(page.locator("#applyButton")).to_be_disabled()
@@ -84,13 +208,14 @@ def test_fallback_editor_rejects_blank_and_duplicate_rows(
editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
add_input = editor.locator("#field-MODEL_FALLBACKS-add")
- add_button = editor.get_by_role("button", name="Add", exact=True)
+ add_button = editor.get_by_role("button", name="Add fallback", exact=True)
add_button.click()
expect(page.locator("#messageArea")).to_have_text(
"Enter a full provider/model fallback."
)
add_input.fill("groq/custom-model")
+ editor.get_by_label("Fallback reasoning effort", exact=True).select_option("high")
add_button.click()
add_input.fill("groq/custom-model")
add_button.click()
@@ -114,10 +239,307 @@ def test_process_owned_fallback_list_locks_every_mutation(
editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
expect(editor.locator("#field-MODEL_FALLBACKS-add")).to_be_disabled()
- expect(editor.get_by_role("button", name="Add", exact=True)).to_be_disabled()
- expect(editor.locator(".model-list-action")).to_have_count(6)
+ expect(
+ editor.get_by_label("Fallback reasoning effort", exact=True)
+ ).to_be_disabled()
+ expect(
+ editor.get_by_role("button", name="Add fallback", exact=True)
+ ).to_be_disabled()
+ expect(editor.locator(".model-list-row .model-list-action")).to_have_count(4)
for button in editor.locator(".model-list-action").all():
expect(button).to_be_disabled()
+ for effort in editor.locator(".model-list-row select").all():
+ expect(effort).to_be_disabled()
+ for model in editor.locator(".model-list-row input").all():
+ expect(model).to_be_disabled()
+ for handle in editor.locator(".model-list-drag").all():
+ expect(handle).to_have_attribute("draggable", "false")
+
+
+def test_fallback_editor_pairs_match_existing_controls_and_save_effort(
+ page: Page, admin_base_url: str
+) -> None:
+ page.set_viewport_size({"width": 1280, "height": 900})
+ _open_models(page, admin_base_url)
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ model = editor.locator("#field-MODEL_FALLBACKS-add")
+ effort = editor.get_by_label("Fallback reasoning effort", exact=True)
+ expect(effort.locator("option")).to_have_text(
+ ["Inherit", "Off", "From client", "Low", "Medium", "High", "X-High", "Max"]
+ )
+ bounds = [
+ control.bounding_box()
+ for control in (
+ model,
+ effort,
+ editor.get_by_role("button", name="Add fallback", exact=True),
+ )
+ ]
+ assert all(box is not None for box in bounds)
+ model_box, effort_box, add_box = bounds
+ assert model_box is not None and effort_box is not None and add_box is not None
+ assert abs(model_box["width"] - effort_box["width"]) <= 1
+ assert abs(model_box["height"] - effort_box["height"]) <= 1
+ assert model_box["x"] < effort_box["x"] < add_box["x"]
+ assert abs(model_box["y"] - effort_box["y"]) <= 1
+ style = "el => { const s = getComputedStyle(el); return [s.fontSize, s.borderRadius, s.borderWidth, s.backgroundSize]; }"
+ assert effort.evaluate(style) == page.locator("#field-REASONING_POLICY").evaluate(
+ style
+ )
+
+ # A fallback can match Default today, even with a different effort.
+ model.fill("open_router/e2e-default")
+ effort.select_option("off")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ row_model = editor.get_by_role("combobox", name="Fallback model 1", exact=True)
+ row_model.fill("model-b")
+ editor.get_by_role("option", name="open_router/vendor/model-b", exact=True).click()
+ expect(row_model).to_have_value("open_router/vendor/model-b")
+ row_effort = editor.get_by_label(
+ "Reasoning effort for open_router/vendor/model-b", exact=True
+ )
+ expect(row_effort).to_have_value("off")
+ row_model_box, row_effort_box = row_model.bounding_box(), row_effort.bounding_box()
+ assert row_model_box is not None and row_effort_box is not None
+ assert abs(row_model_box["width"] - model_box["width"]) <= 1
+ assert abs(row_effort_box["width"] - effort_box["width"]) <= 1
+ assert row_model.evaluate(style) == model.evaluate(style)
+ row_effort.select_option("max")
+ with page.expect_response("**/admin/api/config/apply") as saved:
+ page.locator("#applyButton").click()
+ assert saved.value.json()["applied"] is True
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ page.reload()
+ page.get_by_role("button", name="Model Config", exact=True).click()
+ expect(
+ editor.get_by_label(
+ "Reasoning effort for open_router/vendor/model-b", exact=True
+ )
+ ).to_have_value("max")
+ assert _fallbacks(editor) == [
+ {"model": "open_router/vendor/model-b", "reasoning": "max"}
+ ]
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+
+
+def test_fallback_drag_and_keyboard_reordering_save_model_effort_pairs(
+ page: Page, admin_base_url: str
+) -> None:
+ page.set_viewport_size({"width": 1280, "height": 1100})
+ _open_models(page, admin_base_url)
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ entries = [
+ {"model": "groq/model-a", "reasoning": "low"},
+ {"model": "groq/model-b", "reasoning": "client"},
+ {"model": "groq/model-c", "reasoning": "max"},
+ {"model": "groq/model-d", "reasoning": "high"},
+ ]
+ for entry in entries:
+ editor.locator("#field-MODEL_FALLBACKS-add").fill(entry["model"])
+ editor.get_by_label("Fallback reasoning effort", exact=True).select_option(
+ entry["reasoning"]
+ )
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ rows = editor.locator(".model-list-row")
+ target_box = rows.nth(3).bounding_box()
+ assert target_box is not None
+ editor.get_by_role("button", name="Move groq/model-a", exact=True).drag_to(
+ rows.nth(3), target_position={"x": 10, "y": target_box["height"] - 5}
+ )
+ assert _fallbacks(editor) == [entries[1], entries[2], entries[3], entries[0]]
+ handle = editor.get_by_role("button", name="Move groq/model-a", exact=True)
+ handle.focus()
+ handle.press("ArrowUp")
+ expect(handle).to_be_focused()
+ assert _fallbacks(editor) == [entries[1], entries[2], entries[0], entries[3]]
+ handle.press("ArrowDown")
+ handle.press("ArrowDown") # The last row stays in place.
+ assert _fallbacks(editor) == [entries[1], entries[2], entries[3], entries[0]]
+ expect(page.locator("#field-MODEL_SONNET")).to_have_value("None")
+ with page.expect_response("**/admin/api/config/apply") as saved:
+ page.locator("#applyButton").click()
+ assert saved.value.json()["applied"] is True
+ page.reload()
+ expect(page.locator("#messageArea")).to_have_text("")
+ assert _fallbacks(editor) == [entries[1], entries[2], entries[3], entries[0]]
+ expect(
+ editor.get_by_role("combobox", name="Fallback model 1", exact=True)
+ ).to_have_value("groq/model-b")
+
+
+def test_fallback_plus_and_trash_have_matching_shape_and_centered_icons(
+ page: Page, admin_base_url: str
+) -> None:
+ _open_models(page, admin_base_url)
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ editor.locator("#field-MODEL_FALLBACKS-add").fill("groq/model-a")
+ plus = editor.get_by_role("button", name="Add fallback", exact=True)
+ plus.click()
+ trash = editor.get_by_role("button", name="Remove groq/model-a", exact=True)
+ shape = "el => { const s = getComputedStyle(el); return [s.width, s.height, s.borderRadius]; }"
+ assert plus.evaluate(shape) == trash.evaluate(shape)
+ for button in (plus, trash):
+ icon = button.locator("svg")
+ expect(icon).to_be_visible()
+ button_box, icon_box = button.bounding_box(), icon.bounding_box()
+ assert button_box is not None and icon_box is not None
+ for axis, size in (("x", "width"), ("y", "height")):
+ button_center = button_box[axis] + button_box[size] / 2
+ icon_center = icon_box[axis] + icon_box[size] / 2
+ assert abs(button_center - icon_center) <= 0.5
+
+
+def test_fallback_drag_indicators_only_offer_unique_positions_that_change_order(
+ page: Page, admin_base_url: str
+) -> None:
+ page.set_viewport_size({"width": 1280, "height": 1100})
+ _open_models(page, admin_base_url)
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ for suffix in ("a", "b", "c", "d"):
+ editor.locator("#field-MODEL_FALLBACKS-add").fill(f"groq/model-{suffix}")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ editor.scroll_into_view_if_needed()
+ original = _fallbacks(editor)
+ rows = editor.locator(".model-list-row")
+ handle = editor.get_by_role("button", name="Move groq/model-b", exact=True)
+ handle_box = handle.bounding_box()
+ assert handle_box is not None
+ x = handle_box["x"] + handle_box["width"] / 2
+ y = handle_box["y"] + handle_box["height"] / 2
+ page.mouse.move(x, y)
+ page.mouse.down()
+ page.mouse.move(x + 8, y + 8, steps=5)
+ expect(editor.locator(".model-list-row.dragging")).to_have_count(1)
+ indicators = editor.locator(".model-list-row[data-drop-position]")
+ try:
+ # Both halves of the source and the two neighboring insertion points
+ # retain the current order, so they should show no placement line.
+ for index, after in ((1, False), (1, True), (0, True), (2, False)):
+ bounds = rows.nth(index).bounding_box()
+ assert bounds is not None
+ page.mouse.move(
+ bounds["x"] + 10,
+ bounds["y"] + (bounds["height"] - 2 if after else 2),
+ steps=5,
+ )
+ expect(indicators).to_have_count(0)
+ assert _fallbacks(editor) == original
+ for index, position in ((3, "after"), (0, "before")):
+ bounds = rows.nth(index).bounding_box()
+ assert bounds is not None
+ page.mouse.move(
+ bounds["x"] + 10,
+ bounds["y"] + (bounds["height"] - 2 if position == "after" else 2),
+ steps=5,
+ )
+ expect(indicators).to_have_count(1)
+ expect(rows.nth(index)).to_have_attribute("data-drop-position", position)
+ line_y = None
+ for index, after in ((2, True), (3, False)):
+ bounds = rows.nth(index).bounding_box()
+ assert bounds is not None
+ page.mouse.move(
+ bounds["x"] + 10,
+ bounds["y"] + (bounds["height"] - 2 if after else 2),
+ steps=5,
+ )
+ expect(indicators).to_have_count(1)
+ current_y = indicators.evaluate(
+ "el => { const r = el.getBoundingClientRect(); return el.dataset.dropPosition === 'before' ? r.top : r.bottom; }"
+ )
+ if line_y is None:
+ line_y = current_y
+ else:
+ assert current_y == line_y
+ upper, lower = rows.nth(2).bounding_box(), rows.nth(3).bounding_box()
+ assert upper is not None and lower is not None
+ page.mouse.move(
+ upper["x"] + 10,
+ (upper["y"] + upper["height"] + lower["y"]) / 2,
+ steps=5,
+ )
+ expect(indicators).to_have_count(1)
+ assert (
+ indicators.evaluate(
+ "el => { const r = el.getBoundingClientRect(); return el.dataset.dropPosition === 'before' ? r.top : r.bottom; }"
+ )
+ == line_y
+ )
+ finally:
+ page.mouse.up()
+ assert _fallbacks(editor) == [original[0], original[2], original[1], original[3]]
+ expect(indicators).to_have_count(0)
+
+
[email protected]("invalid_model", ["", "groq/model-b"])
+def test_fallback_model_edits_validate_without_losing_saved_configuration(
+ page: Page, admin_base_url: str, invalid_model: str
+) -> None:
+ _open_models(page, admin_base_url)
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ for model in ("groq/model-a", "groq/model-b"):
+ editor.locator("#field-MODEL_FALLBACKS-add").fill(model)
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ with page.expect_response("**/admin/api/config/apply") as saved:
+ page.locator("#applyButton").click()
+ assert saved.value.json()["applied"] is True
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ original = _fallbacks(editor)
+ model = editor.get_by_role("combobox", name="Fallback model 1", exact=True)
+ model.fill(invalid_model)
+ expect(page.locator("#dirtyState")).to_have_text("1 unsaved change")
+ model.press("Tab")
+ with page.expect_response("**/admin/api/config/apply") as rejected:
+ page.locator("#applyButton").click()
+ assert rejected.value.json()["applied"] is False
+ expect(model).to_have_value(invalid_model)
+ fields = page.request.get(f"{admin_base_url}/admin/api/config").json()["fields"]
+ persisted = next(field for field in fields if field["key"] == "MODEL_FALLBACKS")
+ assert json.loads(persisted["value"]) == original
+
+
+def test_editable_fallbacks_keep_focus_and_live_model_suggestions(
+ page: Page, admin_base_url: str
+) -> None:
+ _open_models(page, admin_base_url)
+ page.wait_for_function("!state.startupRequest && !state.startupTimer")
+ editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
+ editor.locator("#field-MODEL_FALLBACKS-add").fill("groq/custom")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ model = editor.get_by_role("combobox", name="Fallback model 1", exact=True)
+ model.fill("open_router/new-model")
+ expect(model).to_be_focused()
+ assert _fallbacks(editor) == [
+ {"model": "open_router/new-model", "reasoning": "inherit"}
+ ]
+ for effort in ("low", "high", "client"):
+ editor.get_by_label(
+ "Reasoning effort for open_router/new-model", exact=True
+ ).select_option(effort)
+ model.fill("new-model")
+ page.route(
+ "**/admin/api/models",
+ lambda route: route.fulfill(
+ json={"models": ["open_router/new-model"], "failed_providers": []}
+ ),
+ )
+ # Refresh the catalog without closing the currently edited model dropdown.
+ with page.expect_response("**/admin/api/models"):
+ page.evaluate("void hydrateModelOptions()")
+ expect(
+ editor.get_by_role("option", name="open_router/new-model", exact=True)
+ ).to_be_visible()
+ expect(model).to_have_value("new-model")
+ editor.get_by_role("option", name="open_router/new-model", exact=True).click()
+ assert _fallbacks(editor) == [
+ {"model": "open_router/new-model", "reasoning": "client"}
+ ]
+ registered = page.evaluate("state.modelComboboxes.size")
+ for _ in range(3):
+ editor.locator("#field-MODEL_FALLBACKS-add").fill("groq/discarded")
+ editor.get_by_role("button", name="Add fallback", exact=True).click()
+ editor.get_by_role("button", name="Remove groq/discarded", exact=True).click()
+ assert page.evaluate("state.modelComboboxes.size") == registered
def test_fallback_editor_remains_usable_at_narrow_viewport(
@@ -130,7 +552,9 @@ def test_fallback_editor_remains_usable_at_narrow_viewport(
editor = page.locator('.field[data-key="MODEL_FALLBACKS"]')
editor.scroll_into_view_if_needed()
expect(editor.locator("#field-MODEL_FALLBACKS-add")).to_be_visible()
- expect(editor.get_by_role("button", name="Add", exact=True)).to_be_visible()
+ expect(
+ editor.get_by_role("button", name="Add fallback", exact=True)
+ ).to_be_visible()
assert page.evaluate(
"document.documentElement.scrollWidth <= document.documentElement.clientWidth"
)
diff --git a/e2e/test_code_sessions.py b/e2e/test_code_sessions.py
index d31296ae..02fd34f5 100644
--- a/e2e/test_code_sessions.py
+++ b/e2e/test_code_sessions.py
@@ -1925,7 +1925,7 @@ def test_first_http_sync_failure_recovers_without_reloading(
page.goto(f"{admin_base_url}/admin/code")
expect(
page.get_by_role("button", name="New code session", exact=True)
- ).to_be_enabled()
+ ).to_be_enabled(timeout=10_000)
assert page.evaluate("window.failedCodeLoad")
expect(page.locator("#codeNotice")).to_be_hidden()
diff --git a/e2e/test_integration_notices.py b/e2e/test_integration_notices.py
index 56290e2c..1077c493 100644
--- a/e2e/test_integration_notices.py
+++ b/e2e/test_integration_notices.py
@@ -43,7 +43,8 @@ def notice(page, admin_base_url, request):
page.goto(f"{admin_base_url}/admin/integrations")
button = page.locator(f"#{button_id}")
message = page.locator(f"#{message_id}")
- expect(button).to_have_text("Disconnect")
+ # Initial page readiness can exceed five seconds on shared Windows runners.
+ expect(button).to_have_text("Disconnect", timeout=10_000)
def observe(phase, changed=False, instance="first"):
progress.update(
diff --git a/src/free_claude_code/api/admin_static/admin.css b/src/free_claude_code/api/admin_static/admin.css
index a0b5852f..8f2e1b26 100644
--- a/src/free_claude_code/api/admin_static/admin.css
+++ b/src/free_claude_code/api/admin_static/admin.css
@@ -530,6 +530,15 @@ button.startup-busy::before,
gap: 20px;
}
+.model-route-row {
+ display: grid;
+ grid-column: 1 / -1;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 20px;
+}
+
+.model-route-row > .field { min-width: 0; }
+
/* Field Grouping */
.field {
display: flex;
@@ -684,49 +693,45 @@ button.startup-busy::before,
gap: 8px;
}
-.model-list-add {
+.model-list-add,
+.model-list-row {
display: grid;
- grid-template-columns: minmax(0, 1fr) auto;
+ grid-template-columns: 20px repeat(2, minmax(0, 1fr)) 40px;
gap: 8px;
- align-items: start;
+ align-items: center;
}
-.model-list-row {
+.model-list-add > .model-combobox { grid-column: 2; }
+.model-list-add > select { grid-column: 3; }
+.model-list-add > button { grid-column: 4; }
+
+.model-list-editor .model-list-action {
+ width: 40px;
+ height: 40px;
+ padding: 0;
+ border-radius: var(--radius-sm);
display: grid;
- grid-template-columns: minmax(0, 1fr) auto auto auto;
- gap: 4px;
- align-items: center;
- min-height: 44px;
- padding: 6px 8px 6px 12px;
- border: 1px solid var(--line);
- border-radius: var(--radius-md);
- background: var(--panel-strong);
+ place-items: center;
}
-.model-list-value {
- min-width: 0;
- overflow-wrap: anywhere;
- color: var(--text-strong);
- font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
- font-size: 13px;
-}
+.model-list-action svg { width: 18px; height: 18px; }
-.model-list-action {
- min-height: 32px;
- padding: 4px 8px;
+.model-list-editor .model-list-drag {
+ width: 20px;
+ font-size: 22px;
+ cursor: grab;
}
+.model-list-drag:active { cursor: grabbing; }
+.model-list-row.dragging { opacity: 0.5; }
+.model-list-row[data-drop-position="before"] { box-shadow: 0 -2px var(--accent); }
+.model-list-row[data-drop-position="after"] { box-shadow: 0 2px var(--accent); }
+
.model-list-editor button:disabled {
cursor: not-allowed;
opacity: 0.45;
}
-.model-list-empty {
- padding: 8px 2px;
- color: var(--muted);
- font-size: 13px;
-}
-
.field input:focus,
.field select:focus,
.field textarea:focus {
@@ -947,14 +952,6 @@ button.startup-busy::before,
grid-template-columns: 1fr;
}
- .model-list-add {
- grid-template-columns: 1fr;
- }
-
- .model-list-row {
- grid-template-columns: 1fr repeat(3, auto);
- }
-
.action-meta {
flex-direction: column;
align-items: stretch;
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index e04758e4..b75bf4e0 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -37,7 +37,7 @@ const VIEW_GROUPS = [
id: "model_config",
label: "Model Config",
title: "Model Config",
- sections: ["models", "reasoning", "web_tools"],
+ sections: ["models", "web_tools"],
containerId: "modelConfigSections",
},
{
@@ -849,9 +849,11 @@ function renderSections(sections, fields) {
const grid = document.createElement("div");
grid.className = "field-grid";
- sectionFields.forEach((field) => {
- grid.appendChild(renderField(field));
- });
+ if (section.id === "models") {
+ renderModelRoutes(grid, sectionFields);
+ } else {
+ sectionFields.forEach((field) => grid.appendChild(renderField(field)));
+ }
sectionEl.appendChild(grid);
if (sectionFields.some((field) => field.advanced)) {
@@ -871,6 +873,28 @@ function renderSections(sections, fields) {
});
}
+function renderModelRoutes(grid, fields) {
+ const fieldsByKey = new Map(fields.map((field) => [field.key, field]));
+ const routes = [
+ ["Default", "MODEL", "REASONING_POLICY"],
+ ["Fable", "MODEL_FABLE", "REASONING_FABLE"],
+ ["Opus", "MODEL_OPUS", "REASONING_OPUS"],
+ ["Sonnet", "MODEL_SONNET", "REASONING_SONNET"],
+ ["Haiku", "MODEL_HAIKU", "REASONING_HAIKU"],
+ ];
+ for (const [name, modelKey, effortKey] of routes) {
+ const row = document.createElement("div");
+ row.className = "model-route-row";
+ row.setAttribute("role", "group");
+ row.setAttribute("aria-label", `${name} model and effort`);
+ row.append(renderField(fieldsByKey.get(modelKey)), renderField(fieldsByKey.get(effortKey)));
+ grid.appendChild(row);
+ fieldsByKey.delete(modelKey);
+ fieldsByKey.delete(effortKey);
+ }
+ fieldsByKey.forEach((field) => grid.appendChild(renderField(field)));
+}
+
function renderField(field) {
const wrapper = document.createElement("div");
wrapper.className = `field${field.advanced ? " advanced-field" : ""}`;
@@ -1026,40 +1050,54 @@ class ModelListEditor {
constructor(input, field) {
this.input = input;
this.field = field;
- this.values = input.value
- ? input.value.split(",").map((value) => value.trim()).filter(Boolean)
- : [];
+ this.values = input.value ? JSON.parse(input.value) : [];
this.inputId = `field-${field.key}-add`;
+ this.rowComboboxes = [];
+ this.draggedEntry = null;
this.element = document.createElement("div");
this.element.className = "model-list-editor";
const addRow = document.createElement("div");
addRow.className = "model-list-add";
- this.addInput = window.FccFormControls.configure(document.createElement("input"));
- this.addInput.id = this.inputId;
- this.addInput.type = "text";
- this.addInput.autocomplete = "off";
- this.addInput.placeholder = "provider/model";
- this.addInput.disabled = field.locked;
- const addCombobox = createModelCombobox(this.addInput, {
- ...field,
- key: `${field.key}-add`,
- label: "fallback model",
- type: "model",
- });
+ const addCombobox = this.modelCombobox("", "add", "New fallback model");
+ this.addInput = addCombobox.input;
+ this.addEffort = this.effortSelect("inherit", "Fallback reasoning effort");
+ this.addEffort.id = `field-${field.key}-effort`;
- this.addButton = document.createElement("button");
- this.addButton.type = "button";
- this.addButton.className = "secondary-button";
- this.addButton.textContent = "Add";
- this.addButton.disabled = field.locked;
- this.addButton.addEventListener("click", () => this.add());
- addRow.append(addCombobox.element, this.addButton);
+ this.addButton = this.actionButton("", "Add fallback", () => this.add());
+ this.addButton.className = "secondary-button model-list-action";
+ this.addButton.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><path d="M12 6v12M6 12h12" stroke-linecap="round"/></svg>';
+ addRow.append(addCombobox.element, this.addEffort, this.addButton);
this.rows = document.createElement("div");
this.rows.className = "model-list-rows";
- this.element.append(input, addRow, this.rows);
+ this.rows.addEventListener("dragover", (event) => {
+ if (!this.draggedEntry || this.field.locked) return;
+ event.preventDefault();
+ this.clearDropIndicators();
+ const insertion = this.dropInsertion(event);
+ if (this.dropDestination(insertion) === this.values.indexOf(this.draggedEntry)) {
+ event.dataTransfer.dropEffect = "none";
+ return;
+ }
+ event.dataTransfer.dropEffect = "move";
+ const next = this.rows.children[insertion];
+ const marker = next || this.rows.lastElementChild;
+ marker.dataset.dropPosition = next ? "before" : "after";
+ });
+ this.rows.addEventListener("dragleave", (event) => {
+ if (!this.rows.contains(event.relatedTarget)) this.clearDropIndicators();
+ });
+ this.rows.addEventListener("drop", (event) => {
+ if (!this.draggedEntry || this.field.locked) return;
+ event.preventDefault();
+ const moved = this.draggedEntry;
+ const destination = this.dropDestination(this.dropInsertion(event));
+ this.clearDrag();
+ this.move(moved, destination);
+ });
+ this.element.append(input, this.rows, addRow);
this.renderRows();
}
@@ -1069,81 +1107,148 @@ class ModelListEditor {
showMessage("Enter a full provider/model fallback.", "error");
return;
}
- if (this.values.includes(value)) {
+ if (this.values.some((entry) => entry.model === value)) {
showMessage("That fallback model is already in the list.", "error");
return;
}
- this.values.push(value);
+ this.values.push({ model: value, reasoning: this.addEffort.value });
this.addInput.value = "";
+ this.addEffort.value = "inherit";
showMessage("");
this.sync();
+ this.renderRows();
}
- move(index, offset) {
- const destination = index + offset;
- if (destination < 0 || destination >= this.values.length) return;
- [this.values[index], this.values[destination]] = [
- this.values[destination],
- this.values[index],
- ];
+ move(entry, destination) {
+ const index = this.values.indexOf(entry);
+ if (this.field.locked || destination < 0 || destination >= this.values.length || index === destination) return;
+ this.values.splice(index, 1);
+ this.values.splice(destination, 0, entry);
this.sync();
+ this.renderRows();
}
remove(index) {
this.values.splice(index, 1);
this.sync();
+ this.renderRows();
}
sync() {
- this.input.value = this.values.join(",");
+ this.input.value = this.values.length ? JSON.stringify(this.values) : "";
this.input.dataset.remove = "false";
this.input.dispatchEvent(new Event("input", { bubbles: true }));
- this.renderRows();
}
renderRows() {
- this.rows.innerHTML = "";
- if (this.values.length === 0) {
- const empty = document.createElement("div");
- empty.className = "model-list-empty";
- empty.textContent = "No fallback models configured.";
- this.rows.appendChild(empty);
- return;
- }
+ this.rowComboboxes.forEach((combobox) => {
+ combobox.close();
+ state.modelComboboxes.delete(combobox);
+ });
+ this.rowComboboxes = [];
+ this.rows.replaceChildren();
- this.values.forEach((value, index) => {
+ this.values.forEach((entry, index) => {
const row = document.createElement("div");
row.className = "model-list-row";
- const model = document.createElement("span");
- model.className = "model-list-value";
- model.textContent = value;
-
- const up = this.actionButton("Move up", `Move ${value} up`, () =>
- this.move(index, -1),
- );
- up.disabled = this.field.locked || index === 0;
- const down = this.actionButton("Move down", `Move ${value} down`, () =>
- this.move(index, 1),
- );
- down.disabled = this.field.locked || index === this.values.length - 1;
- const remove = this.actionButton("Remove", `Remove ${value}`, () =>
- this.remove(index),
- );
- remove.disabled = this.field.locked;
+ const combobox = this.modelCombobox(entry.model, `row-${index}`, `Fallback model ${index + 1}`);
+ this.rowComboboxes.push(combobox);
+ const effort = this.effortSelect(entry.reasoning, `Reasoning effort for ${entry.model}`);
+ effort.addEventListener("change", () => {
+ entry.reasoning = effort.value;
+ this.sync();
+ });
- row.append(model, up, down, remove);
+ const handle = this.actionButton("⠿", `Move ${entry.model}`);
+ handle.classList.add("model-list-drag");
+ handle.draggable = !this.field.locked;
+ handle.title = "Drag to reorder, or use the up and down arrow keys.";
+ handle.addEventListener("keydown", (event) => {
+ if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+ event.preventDefault();
+ this.move(entry, this.values.indexOf(entry) + (event.key === "ArrowUp" ? -1 : 1));
+ this.rows.children[this.values.indexOf(entry)].querySelector(".model-list-drag").focus();
+ });
+ handle.addEventListener("dragstart", (event) => {
+ this.draggedEntry = entry;
+ event.dataTransfer.effectAllowed = "move";
+ event.dataTransfer.setData("text/plain", entry.model);
+ row.classList.add("dragging");
+ });
+ handle.addEventListener("dragend", () => this.clearDrag());
+
+ const remove = this.actionButton("", `Remove ${entry.model}`, () => this.remove(index));
+ remove.className = "danger-button model-list-action";
+ remove.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><path d="M3 6h18M9 6V4h6v2M5 6l1 14h12l1-14M10 10v6M14 10v6" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+ const updateModel = () => {
+ entry.model = combobox.input.value.trim();
+ effort.setAttribute("aria-label", `Reasoning effort for ${entry.model}`);
+ handle.setAttribute("aria-label", `Move ${entry.model}`);
+ remove.setAttribute("aria-label", `Remove ${entry.model}`);
+ this.sync();
+ };
+ combobox.input.addEventListener("input", updateModel);
+ combobox.input.addEventListener("change", updateModel);
+
+ row.append(handle, combobox.element, effort, remove);
this.rows.appendChild(row);
});
}
- actionButton(text, label, action) {
+ modelCombobox(value, suffix, label) {
+ const input = window.FccFormControls.configure(document.createElement("input"));
+ input.id = `field-${this.field.key}-${suffix}`;
+ input.type = "text";
+ input.autocomplete = "off";
+ input.placeholder = "provider/model";
+ input.disabled = this.field.locked;
+ input.value = value;
+ input.setAttribute("aria-label", label);
+ return createModelCombobox(input, { ...this.field, key: `${this.field.key}-${suffix}`, label, type: "model" });
+ }
+
+ dropInsertion(event) {
+ const index = Array.from(this.rows.children).findIndex((row) => {
+ const bounds = row.getBoundingClientRect();
+ return event.clientY < bounds.top + bounds.height / 2;
+ });
+ return index === -1 ? this.values.length : index;
+ }
+
+ dropDestination(insertion) {
+ const source = this.values.indexOf(this.draggedEntry);
+ return insertion - (source < insertion ? 1 : 0);
+ }
+
+ clearDropIndicators() {
+ this.rows.querySelectorAll("[data-drop-position]").forEach((row) => delete row.dataset.dropPosition);
+ }
+
+ clearDrag() {
+ this.draggedEntry = null;
+ this.clearDropIndicators();
+ this.rows.querySelectorAll(".dragging").forEach((row) => row.classList.remove("dragging"));
+ }
+
+ effortSelect(value, label) {
+ const select = window.FccFormControls.configure(document.createElement("select"));
+ this.field.options.forEach((item) => select.appendChild(option(item.value, item.label)));
+ select.value = value;
+ select.disabled = this.field.locked;
+ select.setAttribute("aria-label", label);
+ return select;
+ }
+
+ actionButton(text, label, action = null) {
const button = document.createElement("button");
button.type = "button";
button.className = "ghost-button model-list-action";
button.textContent = text;
button.setAttribute("aria-label", label);
- button.addEventListener("click", action);
+ button.title = label;
+ button.disabled = this.field.locked;
+ if (action) button.addEventListener("click", action);
return button;
}
}
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index cccb2a74..27c00983 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -10,6 +10,7 @@ from typing import Literal
from loguru import logger
+from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.core.anthropic import (
anthropic_request_snapshot,
get_token_count,
@@ -35,7 +36,14 @@ from free_claude_code.core.trace import (
)
from .ports import ModelInfoLookup, ProviderResolver
+from .reasoning import (
+ client_reasoning_policy,
+ client_responses_reasoning_policy,
+ prepare_fallback_request,
+ resolve_fallback_reasoning,
+)
from .routing import (
+ ProviderModelCandidate,
ProviderModelTarget,
ResolvedModelRoute,
RoutedMessagesRequest,
@@ -46,7 +54,8 @@ from .routing import (
ResponsesTokenCounter = Callable[[OpenAIResponsesRequest], int]
WireApi = Literal["messages", "responses"]
CandidateStreamOpener = Callable[
- [int, ProviderModelTarget, ContinuationSeed | None], Awaitable[AsyncIterator[str]]
+ [int, ProviderModelCandidate, ContinuationSeed | None],
+ Awaitable[AsyncIterator[str]],
]
@@ -174,17 +183,30 @@ class ProviderExecutor:
*,
request_id: str,
) -> AsyncIterator[str]:
+ native_reasoning = ReasoningPolicy.provider_default()
+
async def open_candidate(
index: int,
- target: ProviderModelTarget,
+ candidate: ProviderModelCandidate,
continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
+ target = candidate.target
provider = await self._provider_resolver(target.provider_id)
return provider.stream_native_messages(
routed.request.with_model(target.provider_model),
request_id=request_id,
response_model=routed.resolved.original_model,
request_headers=self._request_headers,
+ reasoning_override=(
+ None
+ if candidate.reasoning_preference
+ in {ReasoningPreference.INHERIT, ReasoningPreference.CLIENT}
+ else resolve_fallback_reasoning(
+ native_reasoning,
+ candidate.reasoning_preference,
+ client=native_reasoning,
+ )
+ ),
continuation=continuation,
)
@@ -192,7 +214,7 @@ class ProviderExecutor:
assert isinstance(messages, list)
return self._stream_candidates(
resolved=routed.resolved,
- reasoning=ReasoningPolicy.provider_default(),
+ reasoning=native_reasoning,
wire_api="messages",
raw_log_label="FULL_NATIVE_MESSAGES_PAYLOAD",
raw_log_payload=lambda: routed.request.body,
@@ -217,6 +239,7 @@ class ProviderExecutor:
"""Execute one Anthropic Messages request."""
primary_request = routed.request.model_copy(deep=True)
+ client_reasoning = client_reasoning_policy(routed.request)
input_tokens = self._token_counter(
routed.request.messages,
routed.request.system,
@@ -225,16 +248,18 @@ class ProviderExecutor:
async def open_candidate(
index: int,
- target: ProviderModelTarget,
+ candidate: ProviderModelCandidate,
continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
+ target = candidate.target
provider = await self._provider_resolver(target.provider_id)
request = (
primary_request
if index == 0
- else routed.request.model_copy(
- update={"model": target.provider_model},
- deep=True,
+ else prepare_fallback_request(
+ routed.request,
+ model=target.provider_model,
+ preference=candidate.reasoning_preference,
)
)
return provider.stream_messages(
@@ -242,7 +267,11 @@ class ProviderExecutor:
input_tokens=input_tokens,
request_id=request_id,
response_model=routed.resolved.original_model,
- reasoning=routed.reasoning,
+ reasoning=resolve_fallback_reasoning(
+ routed.reasoning,
+ candidate.reasoning_preference,
+ client=client_reasoning,
+ ),
model_info=self._model_info_lookup(
target.provider_id, target.provider_model
),
@@ -273,20 +302,23 @@ class ProviderExecutor:
"""Execute one native OpenAI Responses request."""
primary_request = routed.request.model_copy(deep=True)
+ client_reasoning = client_responses_reasoning_policy(routed.request)
input_tokens = self._responses_token_counter(routed.request)
async def open_candidate(
index: int,
- target: ProviderModelTarget,
+ candidate: ProviderModelCandidate,
continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
+ target = candidate.target
provider = await self._provider_resolver(target.provider_id)
request = (
primary_request
if index == 0
- else routed.request.model_copy(
- update={"model": target.provider_model},
- deep=True,
+ else prepare_fallback_request(
+ routed.request,
+ model=target.provider_model,
+ preference=candidate.reasoning_preference,
)
)
return provider.stream_responses(
@@ -294,7 +326,11 @@ class ProviderExecutor:
input_tokens=input_tokens,
request_id=request_id,
response_model=routed.resolved.original_model,
- reasoning=routed.reasoning,
+ reasoning=resolve_fallback_reasoning(
+ routed.reasoning,
+ candidate.reasoning_preference,
+ client=client_reasoning,
+ ),
request_headers=self._request_headers,
continuation=continuation,
model_info=self._model_info_lookup(
@@ -342,7 +378,7 @@ class ProviderExecutor:
"""Start and consume candidates through one protocol-blind lifecycle."""
primary = resolved.primary
- candidates = (primary, *resolved.fallbacks)
+ candidates = (ProviderModelCandidate(primary), *resolved.fallbacks)
gateway_model = resolved.original_model
route_trace: dict[str, object] = {
"stage": "routing",
@@ -392,7 +428,8 @@ class ProviderExecutor:
progress_deadline = loop.time() + self._progress_timeout_seconds
delivery = current_stream_delivery()
continuation: ContinuationSeed | None = None
- for index, target in enumerate(candidates):
+ for index, candidate in enumerate(candidates):
+ target = candidate.target
record_request_route(target.provider_id, target.provider_model)
provider_stream: AsyncIterator[str] | None = None
candidate_committed = False
@@ -401,7 +438,7 @@ class ProviderExecutor:
opening_started = monotonic()
try:
provider_stream = await open_candidate(
- index, target, continuation
+ index, candidate, continuation
)
except ExecutionFailure as failure:
candidate_failure = failure
@@ -510,7 +547,7 @@ class ProviderExecutor:
raise candidate_failure
if delivery is not None and continuation is not None:
delivery.begin_continuation()
- next_target = candidates[index + 1]
+ next_target = candidates[index + 1].target
self._trace_fallback_started(
request_id=request_id,
wire_api=wire_api,
diff --git a/src/free_claude_code/application/ports.py b/src/free_claude_code/application/ports.py
index 4b68ac4a..1cba6e3f 100644
--- a/src/free_claude_code/application/ports.py
+++ b/src/free_claude_code/application/ports.py
@@ -25,6 +25,7 @@ class ProviderPort(Protocol):
request_id: str,
response_model: str,
request_headers: Mapping[str, str] | None = None,
+ reasoning_override: ReasoningPolicy | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]: ...
diff --git a/src/free_claude_code/application/reasoning.py b/src/free_claude_code/application/reasoning.py
index aa3f7851..32c76928 100644
--- a/src/free_claude_code/application/reasoning.py
+++ b/src/free_claude_code/application/reasoning.py
@@ -39,6 +39,44 @@ def resolve_responses_reasoning_policy(
)
+def resolve_fallback_reasoning(
+ original: ReasoningPolicy,
+ preference: ReasoningPreference,
+ *,
+ client: ReasoningPolicy,
+) -> ReasoningPolicy:
+ """Resolve a candidate from original intent, never a previous fallback."""
+
+ if preference is ReasoningPreference.INHERIT:
+ return original
+ if preference is ReasoningPreference.CLIENT:
+ return client
+ return _apply_reasoning_preference(original, preference)
+
+
+def prepare_fallback_request[T: MessagesRequest | OpenAIResponsesRequest](
+ original: T, *, model: str, preference: ReasoningPreference
+) -> T:
+ """Copy a candidate and remove computation controls replaced by its policy."""
+
+ request = original.model_copy(update={"model": model}, deep=True)
+ if preference in {ReasoningPreference.INHERIT, ReasoningPreference.CLIENT}:
+ return request
+ if isinstance(request, MessagesRequest):
+ if request.thinking is not None:
+ thinking = request.thinking.model_dump(exclude_unset=True)
+ for key in ("type", "enabled", "budget_tokens"):
+ thinking.pop(key, None)
+ request.thinking = (
+ ThinkingConfig.model_validate(thinking) if thinking else None
+ )
+ if request.output_config is not None:
+ request.output_config.pop("effort", None)
+ elif request.reasoning is not None:
+ request.reasoning.pop("effort", None)
+ return request
+
+
def _apply_reasoning_preference(
client_policy: ReasoningPolicy,
preference: ReasoningPreference,
diff --git a/src/free_claude_code/application/routing.py b/src/free_claude_code/application/routing.py
index 61b4fc38..63991185 100644
--- a/src/free_claude_code/application/routing.py
+++ b/src/free_claude_code/application/routing.py
@@ -50,13 +50,21 @@ class ProviderModelTarget:
provider_model_ref: str
+@dataclass(frozen=True, slots=True)
+class ProviderModelCandidate:
+ """One execution target with a candidate-local reasoning preference."""
+
+ target: ProviderModelTarget
+ reasoning_preference: ReasoningPreference = ReasoningPreference.INHERIT
+
+
@dataclass(frozen=True, slots=True)
class ResolvedModelRoute:
"""One public model resolved to a primary and ordered fallbacks."""
original_model: str
primary: ProviderModelTarget
- fallbacks: tuple[ProviderModelTarget, ...]
+ fallbacks: tuple[ProviderModelCandidate, ...]
reasoning_preference: ReasoningPreference
@@ -156,12 +164,14 @@ class ModelRouter:
def _fallback_targets(
self, primary: ProviderModelTarget
- ) -> tuple[ProviderModelTarget, ...]:
+ ) -> tuple[ProviderModelCandidate, ...]:
configured = tuple(
- self._target_from_ref(model_ref)
- for model_ref in self._settings.model_fallbacks or ()
+ ProviderModelCandidate(self._target_from_ref(entry.model), entry.reasoning)
+ for entry in self._settings.model_fallbacks or ()
+ )
+ return tuple(
+ candidate for candidate in configured if candidate.target != primary
)
- return tuple(target for target in configured if target != primary)
def _validate_provider_id(self, provider_id: str) -> None:
if provider_id not in self._settings.provider_ids:
@@ -254,9 +264,9 @@ class ModelRouter:
resolved: ResolvedModelRoute,
) -> RoutedNativeMessagesRequest:
eligible = tuple(
- target
- for target in resolved.fallbacks
- if supports_native_messages(target.provider_id)
+ candidate
+ for candidate in resolved.fallbacks
+ if supports_native_messages(candidate.target.provider_id)
)
trace_event(
stage="routing",
@@ -264,9 +274,9 @@ class ModelRouter:
source="application",
contract="native",
excluded_fallbacks=tuple(
- target.provider_model_ref
- for target in resolved.fallbacks
- if target not in eligible
+ candidate.target.provider_model_ref
+ for candidate in resolved.fallbacks
+ if candidate not in eligible
),
)
return RoutedNativeMessagesRequest(
diff --git a/src/free_claude_code/config/admin/custom_providers.py b/src/free_claude_code/config/admin/custom_providers.py
index b2f31990..4486cdef 100644
--- a/src/free_claude_code/config/admin/custom_providers.py
+++ b/src/free_claude_code/config/admin/custom_providers.py
@@ -11,6 +11,7 @@ from free_claude_code.config.custom_providers import (
encode_custom_providers,
)
from free_claude_code.config.loader import ConfigSource, ManagedConfigSnapshot
+from free_claude_code.config.model_refs import decode_model_fallbacks
from free_claude_code.core.json_types import JsonObject
@@ -43,21 +44,23 @@ def merge_custom_provider(
if mutation.action == "delete":
if mutation.values:
raise ValueError("Removal does not accept field edits")
- references = [
- key
- for key in (
- "MODEL",
- "MODEL_FABLE",
- "MODEL_OPUS",
- "MODEL_SONNET",
- "MODEL_HAIKU",
- "MODEL_FALLBACKS",
+ references = []
+ for key in (
+ "MODEL",
+ "MODEL_FABLE",
+ "MODEL_OPUS",
+ "MODEL_SONNET",
+ "MODEL_HAIKU",
+ "MODEL_FALLBACKS",
+ ):
+ value = snapshot.process.get(key, target.get(key, ""))
+ refs = (
+ tuple(entry.model for entry in decode_model_fallbacks(value) or ())
+ if key == "MODEL_FALLBACKS"
+ else (value,)
)
- if any(
- ref.strip().startswith(provider_id + "/")
- for ref in snapshot.process.get(key, target.get(key, "")).split(",")
- )
- ]
+ if any(ref.strip().startswith(provider_id + "/") for ref in refs):
+ references.append(key)
if references:
raise ValueError(
"Change these Model Config settings before removing the provider: "
diff --git a/src/free_claude_code/config/admin/manifest.py b/src/free_claude_code/config/admin/manifest.py
index 3bdfde5a..2a49e058 100644
--- a/src/free_claude_code/config/admin/manifest.py
+++ b/src/free_claude_code/config/admin/manifest.py
@@ -4,6 +4,7 @@ from collections.abc import Iterable
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.reasoning import (
+ FALLBACK_REASONING_PREFERENCES,
ROOT_REASONING_PREFERENCES,
ROUTE_REASONING_PREFERENCES,
ReasoningPreference,
@@ -42,12 +43,7 @@ SECTIONS: tuple[ConfigSectionSpec, ...] = (
ConfigSectionSpec(
"models",
"Model Routing",
- "Search discovered provider models or enter a provider/model slug.",
- ),
- ConfigSectionSpec(
- "reasoning",
- "Reasoning",
- "Client reasoning policy and route-specific overrides.",
+ "Choose a model and effort together. Tier overrides can inherit the defaults.",
),
ConfigSectionSpec(
"runtime",
@@ -131,6 +127,7 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"models",
"model_list",
settings_attr="model_fallbacks",
+ options=_reasoning_options(FALLBACK_REASONING_PREFERENCES),
description=(
"Tried in order when the selected provider/model fails before output "
"starts. Applies to every client. One request may reach multiple "
@@ -140,45 +137,45 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
),
ConfigFieldSpec(
"REASONING_POLICY",
- "Reasoning Policy",
- "reasoning",
+ "Default Effort",
+ "models",
"select",
settings_attr="reasoning_policy",
options=_reasoning_options(ROOT_REASONING_PREFERENCES),
description=(
- "From client preserves CLI effort. Providers translate only the controls "
- "their API supports. Native Anthropic Messages requests always use the "
- "client thinking controls."
+ "Used by inherited routes and direct provider/model requests. From client "
+ "preserves CLI effort. Native Anthropic primary requests use client "
+ "thinking controls."
),
),
ConfigFieldSpec(
"REASONING_FABLE",
- "Fable Reasoning",
- "reasoning",
+ "Fable Effort",
+ "models",
"select",
settings_attr="reasoning_fable",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
"REASONING_OPUS",
- "Opus Reasoning",
- "reasoning",
+ "Opus Effort",
+ "models",
"select",
settings_attr="reasoning_opus",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
"REASONING_SONNET",
- "Sonnet Reasoning",
- "reasoning",
+ "Sonnet Effort",
+ "models",
"select",
settings_attr="reasoning_sonnet",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
"REASONING_HAIKU",
- "Haiku Reasoning",
- "reasoning",
+ "Haiku Effort",
+ "models",
"select",
settings_attr="reasoning_haiku",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
diff --git a/src/free_claude_code/config/admin/persistence.py b/src/free_claude_code/config/admin/persistence.py
index 877be501..d582cf9c 100644
--- a/src/free_claude_code/config/admin/persistence.py
+++ b/src/free_claude_code/config/admin/persistence.py
@@ -98,7 +98,7 @@ def target_values_with_updates(
or (isinstance(submitted, str) and not submitted.strip())
):
continue
- value = normalize_for_env(submitted)
+ value = normalize_for_env(submitted, key=key)
if value is None or (field.nullable and not value):
values.pop(key, None)
else:
@@ -161,7 +161,7 @@ def prepare_admin_update(
for key, submitted in updates.items()
if key in FIELD_BY_KEY
and not is_locked_source(state[key].source)
- and (value := normalize_for_env(submitted))
+ and (value := normalize_for_env(submitted, key=key))
and value != MASKED_SECRET
and value != state[key].value
and key in target_values
diff --git a/src/free_claude_code/config/admin/values.py b/src/free_claude_code/config/admin/values.py
index 37f537fe..dfe91fa2 100644
--- a/src/free_claude_code/config/admin/values.py
+++ b/src/free_claude_code/config/admin/values.py
@@ -1,9 +1,11 @@
"""Admin config value state and API response assembly."""
+import json
from enum import Enum
from free_claude_code.config.custom_providers import REASONING_FORMATS
from free_claude_code.config.loader import ConfigSource, ManagedConfigSnapshot
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.core.json_types import JsonObject
from .manifest import FIELDS, SECTIONS
@@ -14,11 +16,26 @@ from .status import provider_config_status
MASKED_SECRET = "********"
-def normalize_for_env(value: object) -> str | None:
+def normalize_for_env(value: object, *, key: str | None = None) -> str | None:
"""Normalize a submitted Admin value for sparse dotenv persistence."""
if value is None:
return None
+ if key == "MODEL_FALLBACKS" and isinstance(value, list | tuple):
+ return (
+ json.dumps(
+ [
+ item.model_dump(mode="json")
+ if isinstance(item, ModelFallback)
+ else item
+ for item in value
+ ],
+ ensure_ascii=False,
+ separators=(",", ":"),
+ )
+ if value
+ else None
+ )
if isinstance(value, bool):
return "true" if value else "false"
if isinstance(value, Enum):
@@ -49,7 +66,9 @@ def load_value_state(snapshot: ManagedConfigSnapshot) -> ValueState:
state: ValueState = {}
for field in FIELDS:
if field.settings_attr is not None:
- value = normalize_for_env(getattr(snapshot.settings, field.settings_attr))
+ value = normalize_for_env(
+ getattr(snapshot.settings, field.settings_attr), key=field.key
+ )
source = snapshot.sources[field.settings_attr].value
elif field.key in snapshot.process:
value = snapshot.process[field.key].strip() or None
diff --git a/src/free_claude_code/config/model_refs.py b/src/free_claude_code/config/model_refs.py
index 2491caa2..313da77d 100644
--- a/src/free_claude_code/config/model_refs.py
+++ b/src/free_claude_code/config/model_refs.py
@@ -1,14 +1,40 @@
"""Provider-prefixed model reference helpers."""
+import json
from collections.abc import Mapping
from dataclasses import dataclass
-from typing import Protocol
+from typing import Annotated, Protocol
+
+from pydantic import (
+ BaseModel,
+ BeforeValidator,
+ ConfigDict,
+ StringConstraints,
+ TypeAdapter,
+ field_validator,
+)
from .constants import DEFAULT_MODEL
+from .reasoning import ReasoningPreference
RETIRED_PROVIDER_IDS = frozenset({"github_models"})
+class ModelFallback(BaseModel):
+ """One ordered fallback's model and reasoning preference."""
+
+ model_config = ConfigDict(frozen=True, extra="forbid", hide_input_in_errors=True)
+
+ model: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+ reasoning: ReasoningPreference = ReasoningPreference.INHERIT
+
+ @field_validator("model")
+ @classmethod
+ def validate_model(cls, value: str) -> str:
+ split_provider_model_ref(value)
+ return value
+
+
def is_retired_model_ref(model_ref: str) -> bool:
"""Recognize complete references owned by a retired provider."""
@@ -22,12 +48,41 @@ def parse_model_fallbacks(value: object) -> object:
if isinstance(value, str):
if not value.strip():
return None
- return tuple(part.strip() for part in value.split(","))
- if isinstance(value, list | tuple) and not value:
- return None
+ if value.lstrip().startswith("["):
+ try:
+ value = json.loads(value)
+ except ValueError:
+ raise ValueError(
+ "MODEL_FALLBACKS must contain a valid JSON array."
+ ) from None
+ else:
+ value = value.split(",")
+ if isinstance(value, list | tuple):
+ return (
+ tuple({"model": item} if isinstance(item, str) else item for item in value)
+ or None
+ )
return value
+type ModelFallbacks = Annotated[
+ tuple[ModelFallback, ...] | None, BeforeValidator(parse_model_fallbacks)
+]
+_FALLBACKS = TypeAdapter(ModelFallbacks)
+
+
+def decode_model_fallbacks(value: object) -> tuple[ModelFallback, ...] | None:
+ return _FALLBACKS.validate_python(value)
+
+
+def encode_model_fallbacks(value: tuple[ModelFallback, ...]) -> str:
+ return json.dumps(
+ [entry.model_dump(mode="json") for entry in value],
+ ensure_ascii=False,
+ separators=(",", ":"),
+ )
+
+
def normalize_retired_model_settings(
values: Mapping[str, str], *, preserve_empty_overrides: bool
) -> dict[str, str]:
@@ -40,14 +95,20 @@ def normalize_retired_model_settings(
normalized[key] = DEFAULT_MODEL if key == "MODEL" else ""
else:
normalized.pop(key)
- fallbacks = parse_model_fallbacks(normalized.get("MODEL_FALLBACKS"))
- if isinstance(fallbacks, tuple) and all(fallbacks):
- retained = tuple(ref for ref in fallbacks if not is_retired_model_ref(ref))
- if retained != fallbacks:
- if retained or preserve_empty_overrides:
- normalized["MODEL_FALLBACKS"] = ",".join(retained)
- else:
- normalized.pop("MODEL_FALLBACKS")
+ try:
+ fallbacks = decode_model_fallbacks(normalized.get("MODEL_FALLBACKS"))
+ except ValueError:
+ return normalized # Settings reports the original validation error.
+ if fallbacks:
+ retained = tuple(
+ entry for entry in fallbacks if not is_retired_model_ref(entry.model)
+ )
+ if retained:
+ normalized["MODEL_FALLBACKS"] = encode_model_fallbacks(retained)
+ elif preserve_empty_overrides:
+ normalized["MODEL_FALLBACKS"] = ""
+ else:
+ normalized.pop("MODEL_FALLBACKS", None)
return normalized
@@ -66,7 +127,7 @@ class ChatModelConfig(Protocol):
model_opus: str | None
model_sonnet: str | None
model_haiku: str | None
- model_fallbacks: tuple[str, ...] | None
+ model_fallbacks: tuple[ModelFallback, ...] | None
def split_provider_model_ref(model_ref: str) -> tuple[str, str]:
@@ -103,7 +164,7 @@ def configured_chat_model_refs(
settings.model_opus,
settings.model_sonnet,
settings.model_haiku,
- *(settings.model_fallbacks or ()),
+ *(entry.model for entry in settings.model_fallbacks or ()),
)
if model_ref is not None
)
diff --git a/src/free_claude_code/config/reasoning.py b/src/free_claude_code/config/reasoning.py
index 9957c165..b4ad271c 100644
--- a/src/free_claude_code/config/reasoning.py
+++ b/src/free_claude_code/config/reasoning.py
@@ -22,3 +22,4 @@ ROOT_REASONING_PREFERENCES = tuple(
if preference is not ReasoningPreference.INHERIT
)
ROUTE_REASONING_PREFERENCES = tuple(ReasoningPreference)
+FALLBACK_REASONING_PREFERENCES = tuple(ReasoningPreference)
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index 65d34889..76ec3436 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -14,7 +14,7 @@ from pydantic import (
from .constants import DEFAULT_MODEL, HTTP_CONNECT_TIMEOUT_DEFAULT
from .custom_providers import CustomProviderDefinition, decode_custom_providers
-from .model_refs import parse_model_fallbacks
+from .model_refs import ModelFallback, ModelFallbacks
from .nim import NimSettings
from .provider_catalog import (
BEDROCK_DEFAULT_BASE,
@@ -37,10 +37,6 @@ OptionalNonEmptyString = Annotated[
NonEmptyString | None,
BeforeValidator(_empty_to_none),
]
-OptionalModelFallbacks = Annotated[
- tuple[NonEmptyString, ...] | None,
- BeforeValidator(parse_model_fallbacks),
-]
def _validate_model_ref(value: str) -> str:
@@ -100,7 +96,8 @@ class Settings(BaseModel):
value = getattr(self, field)
refs = value if isinstance(value, tuple) else (value,) if value else ()
for ref in refs:
- if ref.partition("/")[0] not in self.provider_ids:
+ model_ref = ref.model if isinstance(ref, ModelFallback) else ref
+ if model_ref.partition("/")[0] not in self.provider_ids:
raise ValueError(
f"{field.upper()}: Invalid provider in model reference"
)
@@ -450,7 +447,7 @@ class Settings(BaseModel):
model_haiku: OptionalNonEmptyString = Field(
default=None, validation_alias="MODEL_HAIKU"
)
- model_fallbacks: OptionalModelFallbacks = Field(
+ model_fallbacks: ModelFallbacks = Field(
default=None,
validation_alias="MODEL_FALLBACKS",
)
@@ -890,14 +887,14 @@ class Settings(BaseModel):
@field_validator("model_fallbacks")
@classmethod
def validate_model_fallbacks(
- cls, value: tuple[str, ...] | None
- ) -> tuple[str, ...] | None:
+ cls, value: tuple[ModelFallback, ...] | None
+ ) -> tuple[ModelFallback, ...] | None:
if value is None:
return None
- validated = tuple(_validate_model_ref(model_ref) for model_ref in value)
- if len(validated) != len(set(validated)):
+ refs = tuple(entry.model for entry in value)
+ if len(refs) != len(set(refs)):
raise ValueError("MODEL_FALLBACKS must not contain duplicate model refs.")
- return validated
+ return value
@model_validator(mode="after")
def check_nvidia_nim_api_key(self) -> Settings:
diff --git a/src/free_claude_code/core/openai_responses/native.py b/src/free_claude_code/core/openai_responses/native.py
index 58c48181..cb7a0905 100644
--- a/src/free_claude_code/core/openai_responses/native.py
+++ b/src/free_claude_code/core/openai_responses/native.py
@@ -51,7 +51,14 @@ def build_native_responses_request(
body["store"] = False
body.pop("previous_response_id", None)
if reasoning != responses_reasoning_policy(request.reasoning):
- if reasoning_config := responses_reasoning_config(reasoning):
+ raw_reasoning = body.get("reasoning")
+ reasoning_config = (
+ dict(raw_reasoning) if isinstance(raw_reasoning, dict) else {}
+ )
+ reasoning_config.pop("effort", None)
+ for key, value in responses_reasoning_config(reasoning).items():
+ reasoning_config.setdefault(key, value)
+ if reasoning_config:
body["reasoning"] = reasoning_config
else:
body.pop("reasoning", None)
diff --git a/src/free_claude_code/providers/anthropic/provider.py b/src/free_claude_code/providers/anthropic/provider.py
index 535506e5..288d4d20 100644
--- a/src/free_claude_code/providers/anthropic/provider.py
+++ b/src/free_claude_code/providers/anthropic/provider.py
@@ -10,7 +10,7 @@ import httpx
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.model_metadata import ProviderModelInfo
-from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.models import MessagesRequest, ThinkingConfig
from free_claude_code.core.anthropic.native import NativeMessagesError
from free_claude_code.core.anthropic.passthrough import (
NativeMessagesRequest,
@@ -31,6 +31,7 @@ from free_claude_code.providers.anthropic_messages.passthrough import (
)
from free_claude_code.providers.anthropic_messages.request_policy import (
MessagesModelCapabilities,
+ resolve_messages_options,
)
from free_claude_code.providers.anthropic_messages.transport import (
AnthropicMessagesTransport,
@@ -50,6 +51,53 @@ async def _omit_cookies(request: httpx.Request) -> None:
request.headers.pop("cookie", None)
+def _apply_native_reasoning(
+ body: JsonObject,
+ *,
+ model: str,
+ reasoning: ReasoningPolicy,
+ capabilities: MessagesModelCapabilities,
+) -> None:
+ """Replace computation controls while retaining native request extensions."""
+
+ raw_thinking = body.get("thinking")
+ raw_output = body.get("output_config")
+ if raw_thinking is not None and not isinstance(raw_thinking, dict):
+ raise NativeMessagesError("Messages thinking must be an object.")
+ if raw_output is not None and not isinstance(raw_output, dict):
+ raise NativeMessagesError("Messages output_config must be an object.")
+ max_tokens = body.get("max_tokens")
+ if max_tokens is not None and not isinstance(max_tokens, int):
+ raise NativeMessagesError("Messages max_tokens must be a positive integer.")
+ display = raw_thinking.get("display") if raw_thinking is not None else None
+ options = resolve_messages_options(
+ model=model,
+ max_tokens=max_tokens,
+ reasoning=reasoning,
+ capabilities=capabilities,
+ thinking=ThinkingConfig.model_validate({"display": display})
+ if display in ("summarized", "omitted", "updates")
+ else None,
+ )
+ body["max_tokens"] = options.max_tokens
+ thinking = dict(raw_thinking or {})
+ for key in ("type", "enabled", "budget_tokens", "display"):
+ thinking.pop(key, None)
+ thinking.update(options.thinking or {})
+ if thinking:
+ body["thinking"] = thinking
+ else:
+ body.pop("thinking", None)
+ output = dict(raw_output or {})
+ output.pop("effort", None)
+ if options.output_effort is not None:
+ output["effort"] = options.output_effort
+ if output:
+ body["output_config"] = output
+ else:
+ body.pop("output_config", None)
+
+
class AnthropicProvider(BaseProvider):
def __init__(
self,
@@ -155,6 +203,7 @@ class AnthropicProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
request_headers: Mapping[str, str] | None = None,
+ reasoning_override: ReasoningPolicy | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
body, headers = native_request(request.body, request_headers)
@@ -167,18 +216,43 @@ class AnthropicProvider(BaseProvider):
)
except (NativeMessagesError, HistoryReplayError) as error:
raise InvalidRequestError(str(error)) from error
- return stream_native_messages(
- self._http,
- self._admission,
- base_url=self._snapshot.base_url,
- headers={**self._snapshot.headers, **headers},
- body=body,
- public_model=response_model or request.model,
- provider_name="anthropic",
- read_timeout_s=self._config.http_read_timeout,
- request_id=request_id,
- continuation=continuation,
- )
+
+ def open_stream() -> AsyncIterator[str]:
+ return stream_native_messages(
+ self._http,
+ self._admission,
+ base_url=self._snapshot.base_url,
+ headers={**self._snapshot.headers, **headers},
+ body=body,
+ public_model=response_model or request.model,
+ provider_name="anthropic",
+ read_timeout_s=self._config.http_read_timeout,
+ request_id=request_id,
+ continuation=continuation,
+ )
+
+ if reasoning_override is None:
+ return open_stream()
+
+ async def stream_with_reasoning() -> AsyncIterator[str]:
+ record = await self.model_record(request.model)
+ try:
+ _apply_native_reasoning(
+ body,
+ model=request.model,
+ reasoning=reasoning_override,
+ capabilities=record.messages,
+ )
+ except NativeMessagesError as error:
+ raise InvalidRequestError(str(error)) from error
+ stream = open_stream()
+ try:
+ async for event in stream:
+ yield event
+ finally:
+ await maybe_await_aclose(stream)
+
+ return stream_with_reasoning()
async def stream_messages(
self,
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 28790155..ea0a2b91 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -52,6 +52,7 @@ class BaseProvider(ABC):
request_id: str | None = None,
response_model: str | None = None,
request_headers: Mapping[str, str] | None = None,
+ reasoning_override: ReasoningPolicy | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise InvalidRequestError(
diff --git a/src/free_claude_code/runtime/diagnostics.py b/src/free_claude_code/runtime/diagnostics.py
index 37256025..bcfe216d 100644
--- a/src/free_claude_code/runtime/diagnostics.py
+++ b/src/free_claude_code/runtime/diagnostics.py
@@ -199,7 +199,7 @@ def settings_report(settings: Settings, accounts: dict[str, str]) -> dict[str, A
return {
"providers": providers,
"runtime": runtime,
- "model_routing": {name: getattr(settings, name) for name in ROUTING_FIELDS},
+ "model_routing": settings.model_dump(mode="json", include=set(ROUTING_FIELDS)),
"reasoning": {name: getattr(settings, name) for name in REASONING_FIELDS},
"web_tools": {name: getattr(settings, name) for name in WEB_FIELDS},
}
diff --git a/tests/api/model_fallback_support.py b/tests/api/model_fallback_support.py
index b02b1c93..55521373 100644
--- a/tests/api/model_fallback_support.py
+++ b/tests/api/model_fallback_support.py
@@ -9,6 +9,7 @@ from fastapi.testclient import TestClient
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.anthropic.streaming import format_sse_event
@@ -200,6 +201,8 @@ class ControlledFallbackProvider:
self._validation_error = validation_error
self.stream_models: list[str] = []
self.response_models: list[str] = []
+ self.requests: list[MessagesRequest | OpenAIResponsesRequest] = []
+ self.reasoning_policies: list[ReasoningPolicy] = []
self.close_calls = 0
async def stream_messages(
@@ -214,10 +217,12 @@ class ControlledFallbackProvider:
model_info: ProviderModelInfo | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
- del input_tokens, request_id, reasoning
+ del input_tokens, request_id
if self._validation_error is not None:
raise self._validation_error
self.stream_models.append(request.model)
+ self.requests.append(request.model_copy(deep=True))
+ self.reasoning_policies.append(reasoning)
public_model = response_model or request.model
self.response_models.append(public_model)
try:
@@ -243,10 +248,12 @@ class ControlledFallbackProvider:
model_info: ProviderModelInfo | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
- del input_tokens, request_id, reasoning
+ del input_tokens, request_id
if self._validation_error is not None:
raise self._validation_error
self.stream_models.append(request.model)
+ self.requests.append(request.model_copy(deep=True))
+ self.reasoning_policies.append(reasoning)
public_model = response_model or request.model
self.response_models.append(public_model)
try:
@@ -268,11 +275,15 @@ class ControlledFallbackProvider:
def fallback_client(
primary: ControlledFallbackProvider,
fallback: ControlledFallbackProvider,
+ *,
+ settings: Settings | None = None,
+ extra_providers: Mapping[str, ControlledFallbackProvider] | None = None,
) -> Iterator[TestClient]:
app = create_test_app(
- Settings(
+ settings
+ or Settings(
model="nvidia_nim/primary-model",
- model_fallbacks=("groq/fallback-model",),
+ model_fallbacks=(ModelFallback(model="groq/fallback-model"),),
)
)
@@ -282,7 +293,9 @@ def fallback_client(
lease: object,
) -> ControlledFallbackProvider:
del lease
- return {"nvidia_nim": primary, "groq": fallback}[provider_id]
+ return {"nvidia_nim": primary, "groq": fallback, **(extra_providers or {})}[
+ provider_id
+ ]
with (
patch(
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index a39333f5..26666b5b 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -17,6 +17,8 @@ from free_claude_code.application.model_metadata import (
ProviderModelRefreshResult,
)
from free_claude_code.config.admin.values import MASKED_SECRET
+from free_claude_code.config.env_files import dotenv_values_from_file
+from free_claude_code.config.model_refs import ModelFallback, decode_model_fallbacks
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.server_urls import local_admin_url
from free_claude_code.config.settings import Settings
@@ -87,7 +89,9 @@ def test_admin_retirement_preview_apply_and_runtime_agree(monkeypatch, tmp_path)
assert "MODEL=groq/default" in text
assert "MODEL_SONNET" not in text
assert "MODEL_OPUS=groq/managed" in text
- assert "MODEL_FALLBACKS=groq/a,deepseek/b" in text
+ assert decode_model_fallbacks(
+ dotenv_values_from_file(env_file)["MODEL_FALLBACKS"]
+ ) == (ModelFallback(model="groq/a"), ModelFallback(model="deepseek/b"))
assert "preserve-secret" in text and "http://user:[email protected]" in text
assert "preserve-secret" not in body["env_preview"]
assert "http://user:[email protected]" not in body["env_preview"]
@@ -95,7 +99,10 @@ def test_admin_retirement_preview_apply_and_runtime_agree(monkeypatch, tmp_path)
effective = provider_manager_for_app(app).current_settings()
assert effective.model == "groq/default"
assert effective.model_opus is None and effective.model_sonnet is None
- assert effective.model_fallbacks == ("groq/a", "deepseek/b")
+ assert effective.model_fallbacks == (
+ ModelFallback(model="groq/a"),
+ ModelFallback(model="deepseek/b"),
+ )
@pytest.fixture(autouse=True)
@@ -636,7 +643,7 @@ def test_admin_static_places_reasoning_fields_in_model_config():
encoding="utf-8"
)
- assert 'sections: ["models", "reasoning", "web_tools"]' in script
+ assert 'sections: ["models", "web_tools"]' in script
assert 'sections: ["models", "thinking", "web_tools"]' not in script
@@ -794,7 +801,7 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
reasoning_policy = next(
field for field in body["fields"] if field["key"] == "REASONING_POLICY"
)
- assert reasoning_policy["section"] == "reasoning"
+ assert reasoning_policy["section"] == "models"
assert reasoning_policy["type"] == "select"
assert reasoning_policy["value"] == "client"
assert reasoning_policy["options"] == [
@@ -813,6 +820,12 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
{"value": "inherit", "label": "Inherit"},
*reasoning_policy["options"],
]
+ assert all(
+ field["section"] == "models"
+ for field in body["fields"]
+ if field["key"].startswith("REASONING_")
+ )
+ assert "reasoning" not in {section["id"] for section in body["sections"]}
restart_required = {
field["key"] for field in body["fields"] if field["restart_required"] is True
}
@@ -988,15 +1001,21 @@ def test_admin_apply_hot_publishes_ordered_model_fallbacks(monkeypatch, tmp_path
assert body["applied"] is True
assert body["restart"]["required"] is False
assert provider_manager_for_app(app).current_settings().model_fallbacks == (
- "open_router/vendor/model-a",
- "groq/vendor/model-b",
+ ModelFallback(model="open_router/vendor/model-a"),
+ ModelFallback(model="groq/vendor/model-b"),
)
managed_env = tmp_path / ".fcc" / ".env"
- assert f"MODEL_FALLBACKS={value}" in managed_env.read_text(encoding="utf-8")
+ assert (
+ decode_model_fallbacks(dotenv_values_from_file(managed_env)["MODEL_FALLBACKS"])
+ == provider_manager_for_app(app).current_settings().model_fallbacks
+ )
loaded = _local_client(app).get("/admin/api/config").json()
field = next(item for item in loaded["fields"] if item["key"] == "MODEL_FALLBACKS")
- assert field["value"] == value
+ assert (
+ decode_model_fallbacks(field["value"])
+ == provider_manager_for_app(app).current_settings().model_fallbacks
+ )
assert field["source"] == "managed_env"
diff --git a/tests/api/test_midstream_model_fallback.py b/tests/api/test_midstream_model_fallback.py
index d96f4a09..302eb591 100644
--- a/tests/api/test_midstream_model_fallback.py
+++ b/tests/api/test_midstream_model_fallback.py
@@ -38,12 +38,12 @@ def release_provider_events(monkeypatch):
async def delivered_candidates(senders, wire, *, tools=None, progress_timeout=10):
history = [{"role": "user", "content": "greet"}]
- async def open_candidate(index, target, continuation=None):
+ async def open_candidate(index, candidate, continuation=None):
return senders[index](
wire,
history,
tools=tools,
- model=target.provider_model,
+ model=candidate.target.provider_model,
continuation=continuation,
)
diff --git a/tests/api/test_model_fallback_clients.py b/tests/api/test_model_fallback_clients.py
index 660996ee..5c7bbf81 100644
--- a/tests/api/test_model_fallback_clients.py
+++ b/tests/api/test_model_fallback_clients.py
@@ -8,6 +8,7 @@ import pytest
from fastapi.testclient import TestClient
from openai import AsyncOpenAI
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
@@ -62,7 +63,10 @@ def test_native_fallback_closes_source_preserves_options_and_filters_candidates(
app = create_test_app(
Settings(
MODEL="anthropic/primary",
- MODEL_FALLBACKS=["nvidia_nim/excluded", "anthropic/backup"],
+ MODEL_FALLBACKS=[
+ ModelFallback(model="nvidia_nim/excluded"),
+ ModelFallback(model="anthropic/backup"),
+ ],
),
providers={"anthropic": provider(reply, max_attempts=1)},
)
diff --git a/tests/api/test_model_fallback_reasoning.py b/tests/api/test_model_fallback_reasoning.py
new file mode 100644
index 00000000..66ce6a27
--- /dev/null
+++ b/tests/api/test_model_fallback_reasoning.py
@@ -0,0 +1,215 @@
+"""Each fallback resolves controls from the original request's reasoning intent."""
+
+import pytest
+
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import (
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningPolicy,
+)
+from tests.api.model_fallback_support import (
+ ControlledFallbackProvider,
+ execution_failure,
+ fallback_client,
+ messages_payload,
+ responses_payload,
+)
+
+
[email protected]("wire_api", ["messages", "responses"])
[email protected]("client_effort", [None, "high"])
+def test_from_client_default_reaches_primary_and_inherited_fallback(
+ wire_api, client_effort
+):
+ primary = ControlledFallbackProvider(failure=execution_failure("primary failed"))
+ fallback = ControlledFallbackProvider(text="fallback worked")
+ settings = Settings(
+ MODEL="nvidia_nim/primary-model",
+ MODEL_FALLBACKS=[{"model": "groq/fallback-model"}],
+ )
+ payload = (
+ messages_payload(stream=True) if wire_api == "messages" else responses_payload()
+ )
+ if client_effort is not None:
+ payload["output_config" if wire_api == "messages" else "reasoning"] = {
+ "effort": client_effort
+ }
+ with fallback_client(primary, fallback, settings=settings) as client:
+ response = client.post(f"/v1/{wire_api}", json=payload)
+ assert response.status_code == 200 and "fallback worked" in response.text
+ expected = ReasoningPolicy(
+ effort=ReasoningEffort(client_effort) if client_effort is not None else None
+ )
+ assert primary.reasoning_policies == [expected]
+ assert fallback.reasoning_policies == [expected]
+
+
[email protected]("wire_api", ["messages", "responses"])
[email protected]("root_effort", ["high", "off"])
[email protected]("fallback_effort", ["inherit", "client"])
+def test_from_client_bypasses_fcc_policy_while_inherit_keeps_it(
+ wire_api, root_effort, fallback_effort
+):
+ primary = ControlledFallbackProvider(failure=execution_failure("primary failed"))
+ fallback = ControlledFallbackProvider(text="fallback worked")
+ settings = Settings(
+ MODEL="nvidia_nim/primary-model",
+ REASONING_POLICY=root_effort,
+ MODEL_FALLBACKS=[
+ {"model": "groq/fallback-model", "reasoning": fallback_effort}
+ ],
+ )
+ if wire_api == "messages":
+ payload = messages_payload(stream=True) | {
+ "thinking": {"type": "enabled", "budget_tokens": 6000},
+ "output_config": {"effort": "low"},
+ }
+ client_policy = ReasoningPolicy.on(
+ effort=ReasoningEffort.LOW, budget_tokens=6000
+ )
+ else:
+ payload = responses_payload() | {
+ "reasoning": {"effort": "low", "summary": "detailed"}
+ }
+ client_policy = ReasoningPolicy(
+ control=ReasoningControl.DEFAULT, effort=ReasoningEffort.LOW
+ )
+ configured = (
+ ReasoningPolicy.off()
+ if root_effort == "off"
+ else ReasoningPolicy.on(effort=ReasoningEffort.HIGH)
+ )
+ with fallback_client(primary, fallback, settings=settings) as client:
+ response = client.post(f"/v1/{wire_api}", json=payload)
+ assert response.status_code == 200 and "fallback worked" in response.text
+ assert primary.reasoning_policies == [configured]
+ assert fallback.reasoning_policies == [
+ client_policy if fallback_effort == "client" else configured
+ ]
+ first, second = primary.requests[0], fallback.requests[0]
+ if isinstance(first, MessagesRequest):
+ assert isinstance(second, MessagesRequest)
+ assert (
+ second.thinking == first.thinking
+ and second.output_config == first.output_config
+ )
+ else:
+ assert (
+ isinstance(second, OpenAIResponsesRequest)
+ and second.reasoning == first.reasoning
+ )
+
+
[email protected]("wire_api", ["messages", "responses"])
+ "effort", ["inherit", "off", "low", "medium", "high", "xhigh", "max"]
+)
+def test_fallback_has_its_own_policy_and_replaces_client_controls(wire_api, effort):
+ primary = ControlledFallbackProvider(failure=execution_failure("primary failed"))
+ fallback = ControlledFallbackProvider(text="fallback worked")
+ settings = Settings(
+ MODEL="nvidia_nim/primary-model",
+ MODEL_FALLBACKS=[{"model": "groq/fallback-model", "reasoning": effort}],
+ )
+ if wire_api == "messages":
+ payload = messages_payload(stream=True) | {
+ "thinking": {
+ "type": "enabled",
+ "budget_tokens": 6000,
+ "display": "omitted",
+ },
+ "output_config": {
+ "effort": "high",
+ "format": {"type": "json_schema", "schema": {"type": "object"}},
+ },
+ }
+ original = ReasoningPolicy.on(effort=ReasoningEffort.HIGH, budget_tokens=6000)
+ else:
+ payload = responses_payload() | {
+ "reasoning": {
+ "effort": "high",
+ "summary": "detailed",
+ "context": "all_turns",
+ }
+ }
+ original = ReasoningPolicy(
+ control=ReasoningControl.DEFAULT, effort=ReasoningEffort.HIGH
+ )
+ with fallback_client(primary, fallback, settings=settings) as client:
+ response = client.post(f"/v1/{wire_api}", json=payload)
+ assert response.status_code == 200 and "fallback worked" in response.text
+ assert primary.reasoning_policies == [original]
+ expected = (
+ original
+ if effort == "inherit"
+ else ReasoningPolicy.off()
+ if effort == "off"
+ else ReasoningPolicy.on(effort=ReasoningEffort(effort))
+ )
+ assert fallback.reasoning_policies == [expected]
+ first, second = primary.requests[0], fallback.requests[0]
+ assert first is not second and second.model == "fallback-model"
+ if isinstance(first, MessagesRequest):
+ assert isinstance(second, MessagesRequest)
+ assert first.thinking is not None and first.thinking.budget_tokens == 6000
+ assert (
+ first.output_config is not None and first.output_config["effort"] == "high"
+ )
+ assert second.messages == first.messages and second.output_config is not None
+ assert second.output_config["format"] == first.output_config["format"]
+ if effort == "inherit":
+ assert (
+ second.thinking == first.thinking
+ and second.output_config == first.output_config
+ )
+ else:
+ assert second.thinking is not None and second.thinking.budget_tokens is None
+ assert second.thinking.type is None and second.thinking.display == "omitted"
+ assert "effort" not in second.output_config
+ else:
+ assert isinstance(second, OpenAIResponsesRequest)
+ assert first.reasoning == payload["reasoning"]
+ assert second.input == first.input
+ assert (
+ second.reasoning == first.reasoning
+ if effort == "inherit"
+ else second.reasoning == {"summary": "detailed", "context": "all_turns"}
+ )
+
+
[email protected]("wire_api", ["messages", "responses"])
+def test_later_inherit_returns_to_original_policy_after_overridden_fallback(wire_api):
+ primary = ControlledFallbackProvider(failure=execution_failure("primary failed"))
+ low = ControlledFallbackProvider(failure=execution_failure("low failed"))
+ inherited = ControlledFallbackProvider(text="original intent restored")
+ settings = Settings(
+ MODEL="nvidia_nim/primary-model",
+ MODEL_FALLBACKS=[
+ {"model": "groq/fallback-model", "reasoning": "low"},
+ {"model": "open_router/later", "reasoning": "inherit"},
+ ],
+ )
+ payload = (
+ messages_payload(stream=True)
+ | {
+ "thinking": {"type": "enabled", "budget_tokens": 6000},
+ "output_config": {"effort": "high"},
+ }
+ if wire_api == "messages"
+ else responses_payload() | {"reasoning": {"effort": "high"}}
+ )
+ with fallback_client(
+ primary, low, settings=settings, extra_providers={"open_router": inherited}
+ ) as client:
+ response = client.post(f"/v1/{wire_api}", json=payload)
+ assert response.status_code == 200 and "original intent restored" in response.text
+ assert low.reasoning_policies == [ReasoningPolicy.on(effort=ReasoningEffort.LOW)]
+ assert inherited.reasoning_policies == primary.reasoning_policies
+ last = inherited.requests[0]
+ if isinstance(last, MessagesRequest):
+ assert last.thinking is not None and last.thinking.budget_tokens == 6000
+ else:
+ assert last.reasoning == {"effort": "high"}
diff --git a/tests/api/test_model_fallback_wire_controls.py b/tests/api/test_model_fallback_wire_controls.py
new file mode 100644
index 00000000..81e3810e
--- /dev/null
+++ b/tests/api/test_model_fallback_wire_controls.py
@@ -0,0 +1,224 @@
+"""Fallback efforts reach real provider encoders and their HTTP wire bodies."""
+
+import json
+from unittest.mock import AsyncMock
+
+import httpx2
+import pytest
+
+from free_claude_code.application.execution import ProviderExecutor
+from free_claude_code.application.routing import ModelRouter
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.providers.custom import CustomProvider
+from free_claude_code.providers.runtime.config import build_custom_provider_config
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.model_fallback_support import (
+ ControlledFallbackProvider,
+ execution_failure,
+)
+from tests.api.test_delivered_stream_recovery import (
+ assert_completed,
+ public_text,
+ text_events,
+)
+from tests.api.test_hidden_stream_retries import delivered
+from tests.providers.support import immediate_admission
+from tests.providers.test_custom_provider import completion, definition, provider
+
+
[email protected]("wire_api", ["messages", "responses"])
[email protected]("egress", ["openai_chat", "openai_responses"])
[email protected]("effort", ["off", "low", "high", "max"])
+async def test_fallback_effort_replaces_budget_and_preserves_wire_options(
+ wire_api, egress, effort
+):
+ captured = []
+
+ def reply(request):
+ captured.append(json.loads(request.content))
+ response = completion(egress)
+ if egress == "openai_chat":
+ delta = {
+ "id": "reasoning",
+ "object": "chat.completion.chunk",
+ "created": 0,
+ "model": "backup",
+ "choices": [
+ {
+ "index": 0,
+ "delta": {"reasoning_content": "Candidate reasoning"},
+ "finish_reason": None,
+ }
+ ],
+ }
+ response = f"data: {json.dumps(delta)}\n\n" + response
+ return httpx2.Response(
+ 200, text=response, headers={"content-type": "text/event-stream"}
+ )
+
+ configuration = definition(
+ api_format=egress,
+ reasoning_format="openai_effort"
+ if egress == "openai_chat"
+ else "native_responses",
+ )
+ fallback = provider(configuration, openai_handler=reply)
+ primary = ControlledFallbackProvider(failure=execution_failure("primary failed"))
+ settings = Settings(
+ MODEL="nvidia_nim/primary",
+ custom_providers=(configuration,),
+ MODEL_FALLBACKS=[
+ {"model": f"{configuration.provider_id}/backup", "reasoning": effort}
+ ],
+ )
+ executor = ProviderExecutor(
+ AsyncMock(
+ side_effect=lambda provider_id: (
+ primary if provider_id == "nvidia_nim" else fallback
+ )
+ ),
+ progress_timeout_seconds=10,
+ )
+ router = ModelRouter(settings)
+ if wire_api == "messages":
+ request = MessagesRequest.model_validate(
+ {
+ "model": "client-alias",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "max_tokens": 8192,
+ "thinking": {"type": "enabled", "budget_tokens": 6000},
+ "output_config": {"effort": "high"},
+ }
+ )
+ routed = router.resolve_messages_request(request)
+ else:
+ request = OpenAIResponsesRequest(
+ model="client-alias",
+ input="Hello",
+ reasoning={"effort": "high", "summary": "detailed", "context": "all_turns"},
+ metadata={"keep": True},
+ )
+ routed = router.resolve_responses_request(request)
+ before = request.model_dump()
+ try:
+ output = "".join(
+ [
+ event
+ async for event in getattr(executor, f"stream_{wire_api}")(
+ routed, raw_log_payload=dict, request_id="fallback-wire"
+ )
+ ]
+ )
+ assert "Hello" in output and request.model_dump() == before
+ assert len(captured) == 1 and captured[0]["model"] == "backup"
+ body = captured[0]
+ expected = (
+ "none"
+ if effort == "off"
+ else "xhigh"
+ if effort == "max" and egress == "openai_chat"
+ else effort
+ )
+ if egress == "openai_chat":
+ assert body["reasoning_effort"] == expected
+ assert ("Candidate reasoning" in output) is (effort != "off")
+ else:
+ assert body["reasoning"]["effort"] == expected
+ if wire_api == "responses":
+ assert body["reasoning"]["summary"] == "detailed"
+ assert body["reasoning"]["context"] == "all_turns"
+ assert body["metadata"] == {"keep": True}
+ finally:
+ await fallback.cleanup()
+
+
[email protected]("wire_api", ["messages", "responses"])
+async def test_candidate_efforts_survive_retry_and_continuation(monkeypatch, wire_api):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+ bodies = []
+ attempts = {"primary": 0, "low": 0, "inherited": 0}
+
+ def reply(request):
+ body = json.loads(request.content)
+ bodies.append(body)
+ model = body["model"]
+ attempts[model] += 1
+ text = (
+ ["Hello ", "there. "][attempts[model] - 1]
+ if model == "primary"
+ else ["Low ", "work. "][attempts[model] - 1]
+ if model == "low"
+ else "Hello there. Low work. Finished."
+ )
+ events = text_events("responses", text, complete=model == "inherited")
+ raw = "".join(
+ f"event: {event['type']}\ndata: {json.dumps(event)}\n\n" for event in events
+ )
+ return httpx2.Response(
+ 200, text=raw, headers={"content-type": "text/event-stream"}
+ )
+
+ configuration = definition(
+ api_format="openai_responses", reasoning_format="native_responses"
+ )
+ settings = Settings(
+ MODEL=f"{configuration.provider_id}/primary",
+ custom_providers=(configuration,),
+ REASONING_POLICY="high",
+ MODEL_FALLBACKS=[
+ {"model": f"{configuration.provider_id}/low", "reasoning": "low"},
+ {"model": f"{configuration.provider_id}/inherited", "reasoning": "inherit"},
+ ],
+ )
+ instance = CustomProvider(
+ build_custom_provider_config(configuration, settings),
+ definition=configuration,
+ admission=immediate_admission(max_attempts=2),
+ openai_transport=httpx2.MockTransport(reply),
+ )
+ executor = ProviderExecutor(
+ AsyncMock(return_value=instance), progress_timeout_seconds=10
+ )
+ router = ModelRouter(settings)
+ if wire_api == "messages":
+ routed = router.resolve_messages_request(
+ MessagesRequest.model_validate(
+ {
+ "model": "client-alias",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "output_config": {"effort": "medium"},
+ }
+ )
+ )
+ else:
+ routed = router.resolve_responses_request(
+ OpenAIResponsesRequest(
+ model="client-alias", input="Hello", reasoning={"effort": "medium"}
+ )
+ )
+ try:
+ stream = getattr(executor, f"stream_{wire_api}")(
+ routed, raw_log_payload=dict, request_id="fallback-continuation"
+ )
+ events = parse_sse_text(await delivered(stream, wire_api))
+ assert_completed(events, wire_api)
+ assert public_text(events, wire_api) == "Hello there. Low work. Finished."
+ assert [(body["model"], body["reasoning"]["effort"]) for body in bodies] == [
+ ("primary", "high"),
+ ("primary", "high"),
+ ("low", "low"),
+ ("low", "low"),
+ ("inherited", "high"),
+ ]
+ assert "Hello there. " in str(bodies[2]["input"])
+ assert "Low work. " in str(bodies[4]["input"])
+ finally:
+ await instance.cleanup()
diff --git a/tests/api/test_model_listing.py b/tests/api/test_model_listing.py
index afca26b3..f388df8e 100644
--- a/tests/api/test_model_listing.py
+++ b/tests/api/test_model_listing.py
@@ -6,6 +6,7 @@ from fastapi.testclient import TestClient
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.custom_providers import CustomProviderDefinition
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.model_capabilities import ModelInputModality
from tests.api.support import create_test_app, provider_manager_for_app
@@ -17,7 +18,7 @@ def _settings(
model_fable: str | None = None,
model_opus: str | None = "open_router/anthropic/claude-opus",
model_haiku: str | None = "deepseek/deepseek-chat",
- model_fallbacks: tuple[str, ...] | None = None,
+ model_fallbacks: tuple[ModelFallback, ...] | None = None,
) -> Settings:
return Settings.model_construct(
model=model,
@@ -79,7 +80,10 @@ def test_sorted_catalog_retains_an_explicit_no_thinking_server_default(view):
model="open_router/Zulu",
model_opus=None,
model_haiku=None,
- model_fallbacks=("wafer/z-fallback", "deepseek/a-fallback"),
+ model_fallbacks=(
+ ModelFallback(model="wafer/z-fallback"),
+ ModelFallback(model="deepseek/a-fallback"),
+ ),
)
app = create_test_app(settings)
provider_manager_for_app(app).cache_model_infos(
@@ -99,7 +103,10 @@ def test_sorted_catalog_retains_an_explicit_no_thinking_server_default(view):
assert payload["default_model_id"] == "claude-3-freecc-no-thinking/open_router/Zulu"
assert payload["first_id"] == "deepseek/a-fallback"
assert payload["last_id"] == "wafer/z-fallback"
- assert settings.model_fallbacks == ("wafer/z-fallback", "deepseek/a-fallback")
+ assert settings.model_fallbacks == (
+ ModelFallback(model="wafer/z-fallback"),
+ ModelFallback(model="deepseek/a-fallback"),
+ )
def test_models_list_includes_configured_refs_cached_provider_models_and_aliases():
@@ -250,7 +257,7 @@ def test_models_list_includes_fallback_refs_without_cached_discovery():
_settings(
model_opus=None,
model_haiku=None,
- model_fallbacks=("wafer/DeepSeek-V4-Pro",),
+ model_fallbacks=(ModelFallback(model="wafer/DeepSeek-V4-Pro"),),
)
)
diff --git a/tests/api/test_native_anthropic.py b/tests/api/test_native_anthropic.py
index 3f0a92ce..f3348bb7 100644
--- a/tests/api/test_native_anthropic.py
+++ b/tests/api/test_native_anthropic.py
@@ -8,12 +8,58 @@ import httpx
import pytest
from fastapi.testclient import TestClient
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider
from tests.api.support import create_test_app
+from tests.providers.test_anthropic_fallback_reasoning import model_metadata
from tests.providers.test_anthropic_provider import native_body, provider
[email protected]("effort", ["inherit", "client", "off", "low", "high", "max"])
+def test_native_fallback_applies_selected_effort_after_passthrough_primary(effort):
+ sent = []
+
+ def handle(request):
+ if request.method == "GET":
+ return httpx.Response(200, json=model_metadata() | {"id": "backup"})
+ body = json.loads(request.content)
+ sent.append(body)
+ if body["model"] == "primary":
+ return httpx.Response(
+ 403,
+ json={"error": {"type": "permission_error", "message": "unavailable"}},
+ )
+ return httpx.Response(
+ 200, json={"type": "message", "model": "backup", "content": []}
+ )
+
+ app = create_test_app(
+ Settings(
+ MODEL="anthropic/primary",
+ MODEL_FALLBACKS=[{"model": "anthropic/backup", "reasoning": effort}],
+ ),
+ providers={"anthropic": provider(handle)},
+ )
+ body = native_body()
+ body["thinking"] = {"type": "enabled", "budget_tokens": 6000, "display": "omitted"}
+ body["output_config"] = {"effort": "medium", "format": {"type": "json_schema"}}
+ with TestClient(app) as client:
+ response = client.post("/v1/messages", json=body)
+ assert response.status_code == 200, response.text
+ assert response.json()["model"] == body["model"]
+ assert sent[0] == body | {"model": "primary"}
+ assert sent[1]["messages"] == body["messages"] and sent[1]["tools"] == body["tools"]
+ if effort in {"inherit", "client"}:
+ assert sent[1] == body | {"model": "backup"}
+ elif effort == "off":
+ assert sent[1]["thinking"] == {"type": "disabled"}
+ assert sent[1]["output_config"] == {"format": {"type": "json_schema"}}
+ else:
+ assert sent[1]["thinking"] == {"type": "adaptive", "display": "omitted"}
+ assert sent[1]["output_config"]["effort"] == effort
+
+
def test_native_ingress_preserves_extensions_and_bypasses_local_processing():
sent = []
@@ -85,7 +131,10 @@ def test_native_fallback_excludes_compatibility_and_preserves_alias():
settings = Settings(
MODEL="anthropic/primary",
ANTHROPIC_API_KEY="key",
- MODEL_FALLBACKS=["nvidia_nim/never", "anthropic/backup"],
+ MODEL_FALLBACKS=[
+ ModelFallback(model="nvidia_nim/never"),
+ ModelFallback(model="anthropic/backup"),
+ ],
)
app = create_test_app(settings, providers={"anthropic": provider(handle)})
body = native_body()
@@ -128,7 +177,10 @@ def test_leading_pings_allow_exhausted_primary_to_reach_native_fallback():
app = create_test_app(
Settings(
MODEL="anthropic/primary",
- MODEL_FALLBACKS=["nvidia_nim/excluded", "anthropic/backup"],
+ MODEL_FALLBACKS=[
+ ModelFallback(model="nvidia_nim/excluded"),
+ ModelFallback(model="anthropic/backup"),
+ ],
),
providers={"anthropic": provider(handle)},
)
@@ -168,7 +220,7 @@ def test_stream_failure_after_metadata_exhausts_then_uses_fallback():
settings = Settings(
MODEL="anthropic/primary",
ANTHROPIC_API_KEY="key",
- MODEL_FALLBACKS=["anthropic/backup"],
+ MODEL_FALLBACKS=[ModelFallback(model="anthropic/backup")],
)
app = create_test_app(settings, providers={"anthropic": provider(handle)})
with TestClient(app) as client:
@@ -264,7 +316,7 @@ def test_compatibility_primary_keeps_conversion_when_anthropic_is_fallback():
settings = Settings(
MODEL="nvidia_nim/primary",
ANTHROPIC_API_KEY="key",
- MODEL_FALLBACKS=["anthropic/backup"],
+ MODEL_FALLBACKS=[ModelFallback(model="anthropic/backup")],
REASONING_POLICY="off",
)
p = provider(handle)
diff --git a/tests/api/test_native_recovery.py b/tests/api/test_native_recovery.py
index edbd5417..f91f9fae 100644
--- a/tests/api/test_native_recovery.py
+++ b/tests/api/test_native_recovery.py
@@ -8,6 +8,7 @@ import httpx
import pytest
from fastapi.testclient import TestClient
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.providers.admission import (
@@ -45,7 +46,10 @@ def test_only_leading_pings_then_all_candidates_fail_returns_json_error():
)
app = create_test_app(
- Settings(MODEL="anthropic/primary", MODEL_FALLBACKS=["anthropic/backup"]),
+ Settings(
+ MODEL="anthropic/primary",
+ MODEL_FALLBACKS=[ModelFallback(model="anthropic/backup")],
+ ),
providers={"anthropic": provider(handle)},
)
with TestClient(app) as client:
@@ -101,7 +105,7 @@ async def test_leading_ping_timeout_or_disconnect_releases_all_resources(disconn
app = create_test_app(
Settings(
MODEL="anthropic/primary",
- MODEL_FALLBACKS=["anthropic/backup"],
+ MODEL_FALLBACKS=[ModelFallback(model="anthropic/backup")],
provider_progress_timeout=0.05,
),
providers={"anthropic": p},
diff --git a/tests/api/test_native_token_count.py b/tests/api/test_native_token_count.py
index ae85ab03..39ea52e0 100644
--- a/tests/api/test_native_token_count.py
+++ b/tests/api/test_native_token_count.py
@@ -9,6 +9,7 @@ import httpx
import pytest
from fastapi.testclient import TestClient
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic import get_token_count
from tests.api.support import create_test_app, provider_manager_for_app
@@ -70,7 +71,10 @@ def test_native_count_accepts_and_estimates_opaque_payload_without_provider(fiel
def test_compatibility_primary_keeps_count_validation_with_native_fallback():
app = create_test_app(
- Settings(MODEL="nvidia_nim/selected", MODEL_FALLBACKS=["anthropic/backup"])
+ Settings(
+ MODEL="nvidia_nim/selected",
+ MODEL_FALLBACKS=[ModelFallback(model="anthropic/backup")],
+ )
)
with TestClient(app) as client:
response = client.post("/v1/messages/count_tokens", json=count_body())
diff --git a/tests/api/test_request_outcomes.py b/tests/api/test_request_outcomes.py
index e45a98b3..7e7f181f 100644
--- a/tests/api/test_request_outcomes.py
+++ b/tests/api/test_request_outcomes.py
@@ -10,6 +10,7 @@ from loguru import logger
from free_claude_code.api.request_ids import RequestCorrelationMiddleware
from free_claude_code.api.request_outcomes import RequestOutcomeMiddleware
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.request_outcomes import (
@@ -125,7 +126,9 @@ def test_one_final_outcome_for_streamed_inference(outcomes, wire_api, result):
def test_fallback_records_selected_provider_without_logging_failed_attempt(outcomes):
- settings = Settings(model_fallbacks=["open_router/fallback-model"])
+ settings = Settings(
+ model_fallbacks=[ModelFallback(model="open_router/fallback-model")]
+ )
providers = {
"nvidia_nim": OutcomeProvider("pre_start"),
"open_router": OutcomeProvider("success"),
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 66b42934..5d5314e4 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -10,6 +10,7 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.execution import ProviderExecutor
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.application.routing import (
+ ProviderModelCandidate,
ProviderModelTarget,
ResolvedModelRoute,
RoutedMessagesRequest,
@@ -37,6 +38,7 @@ class FakeProvider:
request_id: str,
response_model: str,
request_headers: Mapping[str, str] | None = None,
+ reasoning_override: ReasoningPolicy | None = None,
continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Compatibility test provider received a native request")
@@ -349,7 +351,7 @@ def _routed_request(
resolved=ResolvedModelRoute(
original_model="gateway-model",
primary=_target("provider", "provider-model"),
- fallbacks=fallbacks,
+ fallbacks=tuple(ProviderModelCandidate(target) for target in fallbacks),
reasoning_preference=ReasoningPreference.CLIENT,
),
reasoning=ReasoningPolicy.on(),
@@ -434,7 +436,7 @@ def _routed_responses_request(
resolved=ResolvedModelRoute(
original_model="gateway-model",
primary=_target("provider", "provider-model"),
- fallbacks=fallbacks,
+ fallbacks=tuple(ProviderModelCandidate(target) for target in fallbacks),
reasoning_preference=ReasoningPreference.CLIENT,
),
reasoning=ReasoningPolicy.on(),
diff --git a/tests/application/test_model_catalog.py b/tests/application/test_model_catalog.py
index 684842ee..20730e24 100644
--- a/tests/application/test_model_catalog.py
+++ b/tests/application/test_model_catalog.py
@@ -8,6 +8,7 @@ from free_claude_code.application.model_catalog import (
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.application.ports import ModelCatalogSnapshot
from free_claude_code.config.custom_providers import CustomProviderDefinition
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.settings import Settings
@@ -53,7 +54,10 @@ def test_catalog_sorts_components_and_preserves_exact_identity_and_default():
model_opus=None,
model_sonnet=None,
model_haiku=None,
- model_fallbacks=("wafer/z", "deepseek/a"),
+ model_fallbacks=(
+ ModelFallback(model="wafer/z"),
+ ModelFallback(model="deepseek/a"),
+ ),
)
infos = (
ProviderModelInfo("alpha-2/model"),
@@ -90,7 +94,10 @@ def test_catalog_sorts_components_and_preserves_exact_identity_and_default():
model for model in catalog.models if model.wire_slug == catalog.default_model_id
)
assert selected.context_window_tokens == 32000
- assert settings.model_fallbacks == ("wafer/z", "deepseek/a")
+ assert settings.model_fallbacks == (
+ ModelFallback(model="wafer/z"),
+ ModelFallback(model="deepseek/a"),
+ )
def test_catalog_retains_configured_models_and_enriches_each_reference_once():
@@ -100,7 +107,7 @@ def test_catalog_retains_configured_models_and_enriches_each_reference_once():
model_fable=None,
model_sonnet=None,
model_haiku="deepseek/undiscovered",
- model_fallbacks=("open_router/shared",),
+ model_fallbacks=(ModelFallback(model="open_router/shared"),),
)
info = ProviderModelInfo("open_router/shared", context_window_tokens=65536)
catalog = read_model_catalog(ModelCatalogSnapshot(settings, (info,)))
diff --git a/tests/application/test_routing.py b/tests/application/test_routing.py
index a1f5dc98..0822cc5c 100644
--- a/tests/application/test_routing.py
+++ b/tests/application/test_routing.py
@@ -4,6 +4,7 @@ import pytest
from free_claude_code.application.errors import UnknownProviderError
from free_claude_code.application.routing import ModelRouter
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.config.settings import Settings
@@ -30,7 +31,10 @@ def test_retired_direct_ids_route_to_default_before_family_aliases(prefix, off,
MODEL_SONNET="deepseek/sonnet",
MODEL_HAIKU="deepseek/haiku",
MODEL_FABLE="deepseek/fable",
- MODEL_FALLBACKS="groq/default,groq/backup",
+ MODEL_FALLBACKS=(
+ ModelFallback(model="groq/default"),
+ ModelFallback(model="groq/backup"),
+ ),
REASONING_POLICY="high",
REASONING_OPUS="off",
)
@@ -39,7 +43,9 @@ def test_retired_direct_ids_route_to_default_before_family_aliases(prefix, off,
route = router.resolve(original)
assert route.original_model == original
assert route.primary.provider_model_ref == "groq/default"
- assert [target.provider_model_ref for target in route.fallbacks] == ["groq/backup"]
+ assert [candidate.target.provider_model_ref for candidate in route.fallbacks] == [
+ "groq/backup"
+ ]
assert route.reasoning_preference is (
ReasoningPreference.OFF if off else ReasoningPreference.HIGH
)
@@ -317,7 +323,7 @@ def test_model_router_routes_token_count_request(settings):
def test_model_router_routes_responses_request_without_protocol_conversion(settings):
- settings.model_fallbacks = ("open_router/vendor/fallback",)
+ settings.model_fallbacks = (ModelFallback(model="open_router/vendor/fallback"),)
request = OpenAIResponsesRequest(
model="opencode_zen/responses-model",
input=[{"role": "user", "content": "hello"}],
@@ -333,9 +339,9 @@ def test_model_router_routes_responses_request_without_protocol_conversion(setti
assert routed.resolved.original_model == "opencode_zen/responses-model"
assert routed.resolved.primary.provider_id == "opencode_zen"
assert routed.resolved.primary.provider_model == "responses-model"
- assert [target.provider_model_ref for target in routed.resolved.fallbacks] == [
- "open_router/vendor/fallback"
- ]
+ assert [
+ candidate.target.provider_model_ref for candidate in routed.resolved.fallbacks
+ ] == ["open_router/vendor/fallback"]
assert routed.reasoning.control is ReasoningControl.DEFAULT
assert routed.reasoning.effort is ReasoningEffort.HIGH
assert request.model == "opencode_zen/responses-model"
@@ -343,25 +349,46 @@ def test_model_router_routes_responses_request_without_protocol_conversion(setti
def test_model_router_appends_global_fallbacks_and_skips_only_primary(settings):
settings.model_fallbacks = (
- "nvidia_nim/fallback-model",
- "nvidia_nim/alternate-model",
- "open_router/vendor/model-b",
+ ModelFallback(model="nvidia_nim/fallback-model"),
+ ModelFallback(model="nvidia_nim/alternate-model"),
+ ModelFallback(model="open_router/vendor/model-b"),
)
resolved = ModelRouter(settings).resolve("claude-2.1")
- assert [target.provider_model_ref for target in resolved.fallbacks] == [
+ assert [
+ candidate.target.provider_model_ref for candidate in resolved.fallbacks
+ ] == [
"nvidia_nim/alternate-model",
"open_router/vendor/model-b",
]
+ "requested", ["claude-2.1", "nvidia_nim/primary", "claude-opus-4"]
+)
+def test_fallback_effort_does_not_change_primary_identity(requested):
+ settings = Settings(
+ MODEL="nvidia_nim/primary",
+ MODEL_OPUS="nvidia_nim/primary",
+ MODEL_FALLBACKS=[
+ {"model": "nvidia_nim/primary", "reasoning": "off"},
+ {"model": "groq/backup", "reasoning": "low"},
+ ],
+ )
+ route = ModelRouter(settings).resolve(requested)
+ assert [
+ (candidate.target.provider_model_ref, candidate.reasoning_preference)
+ for candidate in route.fallbacks
+ ] == [("groq/backup", ReasoningPreference.LOW)]
+
+
def test_direct_gateway_route_preserves_original_and_deduplicates_canonical_target(
settings,
):
settings.model_fallbacks = (
- "nvidia_nim/deepseek-ai/deepseek-v4-pro",
- "groq/vendor/model-b",
+ ModelFallback(model="nvidia_nim/deepseek-ai/deepseek-v4-pro"),
+ ModelFallback(model="groq/vendor/model-b"),
)
model = "anthropic/nvidia_nim/deepseek-ai/deepseek-v4-pro"
@@ -371,9 +398,9 @@ def test_direct_gateway_route_preserves_original_and_deduplicates_canonical_targ
assert (
resolved.primary.provider_model_ref == "nvidia_nim/deepseek-ai/deepseek-v4-pro"
)
- assert [target.provider_model_ref for target in resolved.fallbacks] == [
- "groq/vendor/model-b"
- ]
+ assert [
+ candidate.target.provider_model_ref for candidate in resolved.fallbacks
+ ] == ["groq/vendor/model-b"]
def test_model_router_logs_mapping(settings):
diff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.py
index 2d926d40..26d8654a 100644
--- a/tests/cli/test_doctor.py
+++ b/tests/cli/test_doctor.py
@@ -266,3 +266,15 @@ def test_doctor_version_does_not_collect_or_copy(monkeypatch, capsys):
monkeypatch.setattr(entrypoints, "package_version", lambda: "1.2.3")
entrypoints.doctor(["--version"])
assert capsys.readouterr().out == "free-claude-code 1.2.3\n"
+
+
+def test_fallback_model_efforts_are_json_serializable_in_doctor_report():
+ entries = [
+ {"model": "groq/one", "reasoning": "low"},
+ {"model": "open_router/vendor/two", "reasoning": "client"},
+ ]
+ settings = Settings(MODEL_FALLBACKS=entries)
+ report = json.loads(json.dumps(diagnostics.settings_report(settings, {})))
+ assert report["model_routing"]["model_fallbacks"] == entries
+ assert report["providers"]["groq"]["referenced"] is True
+ assert report["providers"]["open_router"]["referenced"] is True
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index a9470240..134e9d2a 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -23,6 +23,7 @@ from free_claude_code.config.loader import (
get_settings,
)
from free_claude_code.config.model_refs import (
+ ModelFallback,
configured_chat_model_refs,
parse_model_name,
parse_provider_type,
@@ -37,6 +38,32 @@ from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.config.settings import Settings
+def test_builtin_effort_is_from_client_with_inherited_tier_efforts():
+ snapshot = compose_settings_snapshot({}, {})
+ settings = snapshot.settings
+ assert settings.reasoning_policy is ReasoningPreference.CLIENT
+ assert snapshot.sources["reasoning_policy"] is ConfigSource.DEFAULT
+ router = ModelRouter(settings)
+ for tier in ("fable", "opus", "sonnet", "haiku"):
+ assert getattr(settings, f"model_{tier}") is None
+ assert getattr(settings, f"reasoning_{tier}") is ReasoningPreference.INHERIT
+ route = router.resolve(f"claude-{tier}-test")
+ assert route.primary.provider_model_ref == settings.model
+ assert route.reasoning_preference is ReasoningPreference.CLIENT
+
+
[email protected]("source", [ConfigSource.MANAGED, ConfigSource.PROCESS])
[email protected]("effort", ["client", "off", "medium", "high"])
+def test_explicit_default_effort_is_retained(source, effort):
+ values = {"REASONING_POLICY": effort}
+ snapshot = compose_settings_snapshot(
+ values if source is ConfigSource.MANAGED else {},
+ values if source is ConfigSource.PROCESS else {},
+ )
+ assert snapshot.settings.reasoning_policy is ReasoningPreference(effort)
+ assert snapshot.sources["reasoning_policy"] is source
+
+
@pytest.mark.parametrize("source", [ConfigSource.MANAGED, ConfigSource.PROCESS])
@pytest.mark.parametrize("tier", ["FABLE", "OPUS", "SONNET", "HAIKU"])
def test_retirement_normalizes_sources_without_resurrecting_overrides(source, tier):
@@ -87,7 +114,10 @@ def test_retirement_preserves_effective_default_order_and_process_environment(
assert snapshot.settings.model == "groq/default"
assert snapshot.settings.model_opus is None
assert snapshot.sources["model_opus"] is ConfigSource.PROCESS
- assert snapshot.settings.model_fallbacks == ("groq/first", "deepseek/last")
+ assert snapshot.settings.model_fallbacks == (
+ ModelFallback(model="groq/first"),
+ ModelFallback(model="deepseek/last"),
+ )
assert loader.os.environ["MODEL_OPUS"] == "github_models/opus"
@@ -477,8 +507,8 @@ def test_model_fallbacks_preserve_order_and_trim_members(value: object) -> None:
settings = Settings.model_validate({"MODEL_FALLBACKS": value})
assert settings.model_fallbacks == (
- "open_router/vendor/model-a",
- "groq/vendor/model-b",
+ ModelFallback(model="open_router/vendor/model-a"),
+ ModelFallback(model="groq/vendor/model-b"),
)
@@ -533,9 +563,9 @@ def test_configured_chat_model_refs_are_unique() -> None:
model_fable="open_router/anthropic/claude-fable",
model_sonnet="deepseek/fallback",
model_fallbacks=(
- "groq/vendor/model-a",
- "open_router/anthropic/claude-fable",
- "lmstudio/vendor/model-b",
+ ModelFallback(model="groq/vendor/model-a"),
+ ModelFallback(model="open_router/anthropic/claude-fable"),
+ ModelFallback(model="lmstudio/vendor/model-b"),
),
)
diff --git a/tests/config/test_custom_provider_mutations.py b/tests/config/test_custom_provider_mutations.py
index 46fe9f20..25440208 100644
--- a/tests/config/test_custom_provider_mutations.py
+++ b/tests/config/test_custom_provider_mutations.py
@@ -1,6 +1,8 @@
import json
from pathlib import Path
+import pytest
+
from free_claude_code.config.admin.custom_providers import CustomProviderMutation
from free_claude_code.config.admin.persistence import prepare_admin_update
from free_claude_code.config.admin.values import load_config_response
@@ -84,6 +86,24 @@ def test_deletion_requires_reassignment_and_is_idempotent():
).valid
[email protected]("process_owned", [False, True])
+def test_deletion_recognizes_structured_fallback_references(process_owned):
+ state, provider_id = created()
+ entries = [{"model": f"{provider_id}/one", "reasoning": "low"}]
+ value = json.dumps(entries)
+ selected = snapshot(
+ state.managed | ({} if process_owned else {"MODEL_FALLBACKS": value}),
+ {"MODEL_FALLBACKS": value} if process_owned else {},
+ )
+ rejected = mutate(selected, "delete", provider_id)
+ assert not rejected.valid and "MODEL_FALLBACKS" in str(rejected.errors)
+ if not process_owned:
+ reassigned = mutate(
+ selected, "delete", provider_id, routes={"MODEL_FALLBACKS": None}
+ )
+ assert reassigned.valid and not reassigned.settings.custom_providers
+
+
def test_invalid_duplicate_or_locked_mutation_does_not_expose_keys():
state, provider_id = created()
duplicate = mutate(
diff --git a/tests/config/test_env_migrations.py b/tests/config/test_env_migrations.py
index ced52fe6..624857c5 100644
--- a/tests/config/test_env_migrations.py
+++ b/tests/config/test_env_migrations.py
@@ -16,6 +16,7 @@ from free_claude_code.config.env_migrations import (
migrate_env_setting_in_text,
)
from free_claude_code.config.loader import ManagedConfigStore
+from free_claude_code.config.model_refs import ModelFallback, decode_model_fallbacks
@pytest.mark.parametrize("schema", ["", "FCC_CONFIG_SCHEMA=1\n"])
@@ -34,7 +35,10 @@ def test_retired_models_repair_managed_config_once_preserving_unknowns(
assert consolidate_managed_config({}).changed
values = dotenv_values_from_file(managed)
assert "MODEL" not in values and "MODEL_OPUS" not in values
- assert values["MODEL_FALLBACKS"] == "groq/a,deepseek/b"
+ assert decode_model_fallbacks(values["MODEL_FALLBACKS"]) == (
+ ModelFallback(model="groq/a"),
+ ModelFallback(model="deepseek/b"),
+ )
assert values["REASONING_OPUS"] == "off"
assert values["GITHUB_MODELS_TOKEN"] == "retired-secret"
assert values["GITHUB_MODELS_PROXY"] == "http://user:[email protected]"
diff --git a/tests/config/test_model_fallbacks.py b/tests/config/test_model_fallbacks.py
new file mode 100644
index 00000000..9377cf01
--- /dev/null
+++ b/tests/config/test_model_fallbacks.py
@@ -0,0 +1,192 @@
+"""Fallback model/effort configuration and persistence contracts."""
+
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from free_claude_code.config.admin.persistence import prepare_admin_update
+from free_claude_code.config.admin.values import load_config_response
+from free_claude_code.config.loader import (
+ ConfigSource,
+ ManagedConfigSnapshot,
+ compose_settings_snapshot,
+)
+from free_claude_code.config.model_refs import configured_chat_model_refs
+from free_claude_code.config.reasoning import ReasoningPreference
+from free_claude_code.config.settings import Settings
+
+
+def _snapshot(managed=None, process=None):
+ managed, process = managed or {}, process or {}
+ result = compose_settings_snapshot(managed, process)
+ return ManagedConfigSnapshot(
+ result.settings, result.sources, managed, process, Path("unused.env")
+ )
+
+
+def _fallback_field(state):
+ fields = load_config_response(state)["fields"]
+ assert isinstance(fields, list)
+ for field in fields:
+ assert isinstance(field, dict)
+ if field["key"] == "MODEL_FALLBACKS":
+ return field
+ raise AssertionError("Fallback field is missing")
+
+
+ "effort", ["inherit", "off", "client", "low", "medium", "high", "xhigh", "max"]
+)
[email protected]("as_json", [False, True])
+def test_fallback_records_preserve_model_and_effort(effort, as_json):
+ value = [
+ {"model": " groq/vendor/Model-A ", "reasoning": effort},
+ {"model": "open_router/vendor/model-b"},
+ ]
+ settings = Settings.model_validate(
+ {"MODEL_FALLBACKS": json.dumps(value) if as_json else value}
+ )
+ assert settings.model_fallbacks is not None
+ assert [
+ (entry.model, entry.reasoning.value) for entry in settings.model_fallbacks
+ ] == [
+ ("groq/vendor/Model-A", effort),
+ ("open_router/vendor/model-b", "inherit"),
+ ]
+ with pytest.raises(ValidationError):
+ settings.model_fallbacks[0].__setattr__("reasoning", ReasoningPreference.OFF)
+
+
+ "value",
+ [
+ "groq/one, open_router/vendor/two ",
+ ["groq/one", "open_router/vendor/two"],
+ ("groq/one", "open_router/vendor/two"),
+ ],
+)
+def test_legacy_fallbacks_are_inherit_records(value):
+ settings = Settings.model_validate({"MODEL_FALLBACKS": value})
+ assert settings.model_fallbacks is not None
+ assert [
+ (entry.model, entry.reasoning.value) for entry in settings.model_fallbacks
+ ] == [("groq/one", "inherit"), ("open_router/vendor/two", "inherit")]
+
+
+ "value",
+ [
+ [{"model": "groq/one", "reasoning": "minimal"}],
+ [{"model": "groq/one", "reasoning": True}],
+ [{"model": "groq/one", "reasoning": "low", "unknown": 1}],
+ [{"model": "groq/"}],
+ [{"model": "unknown/one"}],
+ [
+ {"model": "groq/one", "reasoning": "low"},
+ {"model": "groq/one", "reasoning": "high"},
+ ],
+ '[{"model":"groq/one"}',
+ ],
+)
+def test_invalid_fallback_records_are_rejected(value):
+ with pytest.raises(ValidationError):
+ Settings.model_validate({"MODEL_FALLBACKS": value})
+
+
+def test_fallback_records_retain_primary_overlap_and_discovery_identity():
+ settings = Settings(
+ MODEL="groq/one",
+ MODEL_OPUS="groq/one",
+ MODEL_FALLBACKS=[
+ {"model": "groq/one", "reasoning": "off"},
+ {"model": "open_router/vendor/two", "reasoning": "max"},
+ ],
+ )
+ assert [entry.model_ref for entry in configured_chat_model_refs(settings)] == [
+ "groq/one",
+ "open_router/vendor/two",
+ ]
+
+
[email protected]("as_json", [False, True])
+def test_admin_fallback_records_round_trip_without_restart_or_false_changes(as_json):
+ entries = [
+ {"model": "groq/one", "reasoning": "low"},
+ {"model": "open_router/vendor/two", "reasoning": "inherit"},
+ ]
+ original = _snapshot()
+ saved = prepare_admin_update(
+ {"MODEL_FALLBACKS": json.dumps(entries) if as_json else entries},
+ original,
+ original.settings,
+ )
+ assert saved.valid, saved.errors
+ assert saved.pending_fields == ()
+ assert json.loads(saved.target_values["MODEL_FALLBACKS"]) == entries
+ loaded = _snapshot(saved.target_values)
+ field = _fallback_field(loaded)
+ value = field["value"]
+ assert isinstance(value, str) and json.loads(value) == entries
+ assert field["source"] == ConfigSource.MANAGED.value
+ options = field["options"]
+ assert isinstance(options, list)
+ values = []
+ for option in options:
+ assert isinstance(option, dict)
+ values.append(option["value"])
+ assert values == [
+ "inherit",
+ "off",
+ "client",
+ "low",
+ "medium",
+ "high",
+ "xhigh",
+ "max",
+ ]
+ unchanged = prepare_admin_update(
+ {"MODEL_FALLBACKS": field["value"]}, loaded, loaded.settings
+ )
+ assert unchanged.valid and unchanged.changed_keys == ()
+
+
[email protected]("empty", ["", "[]", []])
+def test_empty_process_fallbacks_override_managed_records_and_remain_locked(empty):
+ managed = {"MODEL_FALLBACKS": '[{"model":"groq/one","reasoning":"max"}]'}
+ state = _snapshot(
+ managed,
+ {"MODEL_FALLBACKS": json.dumps(empty) if isinstance(empty, list) else empty},
+ )
+ assert state.settings.model_fallbacks is None
+ field = _fallback_field(state)
+ assert field["locked"] is True and field["value"] is None
+ result = prepare_admin_update(
+ {"MODEL_FALLBACKS": [{"model": "groq/two", "reasoning": "off"}]},
+ state,
+ state.settings,
+ )
+ assert result.valid and result.settings is not None
+ assert result.settings.model_fallbacks is None
+ assert json.loads(result.target_values["MODEL_FALLBACKS"]) == json.loads(
+ managed["MODEL_FALLBACKS"]
+ )
+
+
+def test_retired_provider_normalization_preserves_surviving_efforts():
+ state = _snapshot(
+ {
+ "MODEL_FALLBACKS": json.dumps(
+ [
+ {"model": "groq/one", "reasoning": "low"},
+ {"model": "github_models/retired", "reasoning": "high"},
+ {"model": "deepseek/two", "reasoning": "max"},
+ ]
+ )
+ }
+ )
+ assert state.settings.model_fallbacks is not None
+ assert [
+ (entry.model, entry.reasoning.value) for entry in state.settings.model_fallbacks
+ ] == [("groq/one", "low"), ("deepseek/two", "max")]
diff --git a/tests/core/openai_responses/test_native.py b/tests/core/openai_responses/test_native.py
index 7a5fe1bf..76ebe4b5 100644
--- a/tests/core/openai_responses/test_native.py
+++ b/tests/core/openai_responses/test_native.py
@@ -210,10 +210,10 @@ def test_native_request_preserves_reasoning_when_fcc_did_not_override_it() -> No
@pytest.mark.parametrize(
("reasoning", "expected"),
(
- (ReasoningPolicy.off(), {"effort": "none"}),
+ (ReasoningPolicy.off(), {"effort": "none", "summary": "detailed"}),
(
ReasoningPolicy.on(effort=ReasoningEffort.XHIGH),
- {"effort": "xhigh", "summary": "auto"},
+ {"effort": "xhigh", "summary": "detailed"},
),
),
)
diff --git a/tests/providers/test_anthropic_fallback_reasoning.py b/tests/providers/test_anthropic_fallback_reasoning.py
new file mode 100644
index 00000000..ec0c7560
--- /dev/null
+++ b/tests/providers/test_anthropic_fallback_reasoning.py
@@ -0,0 +1,173 @@
+"""Explicit native fallback controls retain the raw Anthropic request contract."""
+
+import json
+
+import httpx
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from tests.providers.test_anthropic_native_transport import collect
+from tests.providers.test_anthropic_provider import native_body, provider
+
+
+def model_metadata(*, adaptive=True, supported_efforts=None):
+ return {
+ "id": "claude-test",
+ "max_tokens": 10000,
+ "capabilities": {
+ "thinking": {
+ "supported": True,
+ "types": {
+ "adaptive": {"supported": adaptive},
+ "enabled": {"supported": not adaptive},
+ },
+ },
+ "effort": {
+ "supported": adaptive,
+ **{
+ level: {"supported": True}
+ for level in supported_efforts
+ or ["low", "medium", "high", "xhigh", "max"]
+ },
+ },
+ },
+ }
+
+
[email protected]("adaptive", [False, True])
[email protected]("effort", ["off", "low", "medium", "high", "xhigh", "max"])
+async def test_native_override_replaces_controls_and_preserves_extensions(
+ adaptive, effort
+):
+ received = []
+ lookups = []
+
+ def handle(request):
+ if request.method == "GET":
+ lookups.append(request.url.path)
+ return httpx.Response(200, json=model_metadata(adaptive=adaptive))
+ received.append(request)
+ if len(received) == 1:
+ return httpx.Response(529, json={"error": {"type": "overloaded_error"}})
+ return httpx.Response(200, json={"type": "message", "content": []})
+
+ p = provider(handle)
+ body = native_body()
+ body["thinking"] = {
+ "type": "enabled",
+ "budget_tokens": 6000,
+ "display": "omitted",
+ "future": "keep",
+ }
+ body["output_config"] = {
+ "effort": "high",
+ "format": {"type": "json_schema", "schema": {"type": "object"}},
+ "future": True,
+ }
+ body["extra_body"] = {"new_option": {"keep": True}}
+ body["betas"] = ["request-beta"]
+ original = json.loads(json.dumps(body))
+ reasoning = (
+ ReasoningPolicy.off()
+ if effort == "off"
+ else ReasoningPolicy.on(effort=ReasoningEffort(effort))
+ )
+ try:
+ await collect(
+ p,
+ body,
+ reasoning_override=reasoning,
+ request_headers={"anthropic-beta": "header-beta"},
+ )
+ assert lookups == ["/v1/models/claude-test"]
+ sent, retried = [json.loads(request.content) for request in received]
+ assert sent == retried and body == original
+ assert sent["max_tokens"] == 10000
+ assert (
+ sent["messages"] == original["messages"]
+ and sent["tools"] == original["tools"]
+ )
+ assert sent["future_option"] == original["future_option"]
+ assert sent["new_option"] == {"keep": True} and "extra_body" not in sent
+ assert sent["output_config"]["format"] == original["output_config"]["format"]
+ assert sent["output_config"]["future"] is True
+ assert all(
+ request.headers["anthropic-beta"] == "header-beta,request-beta"
+ for request in received
+ )
+ thinking = sent["thinking"]
+ assert thinking["future"] == "keep"
+ if effort == "off":
+ assert thinking == {"type": "disabled", "future": "keep"}
+ assert "effort" not in sent["output_config"]
+ elif adaptive:
+ assert thinking == {
+ "type": "adaptive",
+ "display": "omitted",
+ "future": "keep",
+ }
+ assert sent["output_config"]["effort"] == effort
+ else:
+ assert thinking["type"] == "enabled" and thinking["display"] == "omitted"
+ budget = reasoning.numeric_budget_tokens
+ assert budget is not None
+ assert thinking["budget_tokens"] == min(max(1024, budget), 9999)
+ assert "effort" not in sent["output_config"]
+ finally:
+ await p.cleanup()
+
+
[email protected]("case", ["unknown", "unsupported_effort", "small_output"])
+async def test_native_override_uses_existing_capability_validation(case):
+ sent = []
+
+ def handle(request):
+ if request.method == "GET":
+ if case == "unknown":
+ return httpx.Response(404, json={"error": "unknown"})
+ return httpx.Response(
+ 200,
+ json=model_metadata(
+ adaptive=case != "small_output", supported_efforts=["low"]
+ ),
+ )
+ sent.append(request)
+ raise AssertionError("Invalid controls reached generation")
+
+ p = provider(handle)
+ body = native_body()
+ if case == "small_output":
+ body["max_tokens"] = 1024
+ try:
+ with pytest.raises(InvalidRequestError):
+ await collect(
+ p,
+ body,
+ reasoning_override=ReasoningPolicy.on(effort=ReasoningEffort.HIGH),
+ )
+ assert sent == []
+ finally:
+ await p.cleanup()
+
+
+async def test_native_inherit_preserves_unknown_controls_without_metadata():
+ sent = []
+
+ def handle(request):
+ assert request.method == "POST"
+ sent.append(json.loads(request.content))
+ return httpx.Response(200, json={"type": "message", "content": []})
+
+ p = provider(handle)
+ body = native_body()
+ body["thinking"] = {"type": "future_mode", "future_budget": 7}
+ body["output_config"] = {"effort": "future_effort", "future": True}
+ try:
+ await collect(p, body, reasoning_override=None)
+ assert sent == [body]
+ finally:
+ await p.cleanup()
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 92f3d792..1b621517 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, patch
import pytest
from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.nim import NimSettings
from free_claude_code.config.provider_catalog import (
DEEPSEEK_DEFAULT_BASE,
@@ -40,7 +41,7 @@ def _settings(
model_opus: str | None = None,
model_sonnet: str | None = None,
model_haiku: str | None = None,
- model_fallbacks: tuple[str, ...] | None = None,
+ model_fallbacks: tuple[ModelFallback, ...] | None = None,
nvidia_nim_api_key: str = "",
open_router_api_key: str = "",
deepseek_api_key: str = "",
@@ -407,7 +408,7 @@ class FakeProvider(BaseProvider):
@pytest.mark.asyncio
async def test_runtime_warm_caches_all_referenced_provider_models() -> None:
settings = _settings(
- model_fallbacks=("open_router/anthropic/claude-opus",),
+ model_fallbacks=(ModelFallback(model="open_router/anthropic/claude-opus"),),
nvidia_nim_api_key="nim-key",
open_router_api_key="open-router-key",
)
diff --git a/tests/providers/test_openai_responses_transport.py b/tests/providers/test_openai_responses_transport.py
index aa826109..a72bdc63 100644
--- a/tests/providers/test_openai_responses_transport.py
+++ b/tests/providers/test_openai_responses_transport.py
@@ -652,7 +652,7 @@ async def test_native_responses_applies_resolved_reasoning_override() -> None:
finally:
await client.close()
- assert captured[0]["reasoning"] == {"effort": "none"}
+ assert captured[0]["reasoning"] == {"effort": "none", "summary": "detailed"}
@pytest.mark.asyncio
diff --git a/tests/providers/test_opencode.py b/tests/providers/test_opencode.py
index 443d361d..9deb2fb2 100644
--- a/tests/providers/test_opencode.py
+++ b/tests/providers/test_opencode.py
@@ -16,6 +16,7 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.execution import ProviderExecutor
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.application.routing import (
+ ProviderModelCandidate,
ProviderModelTarget,
ResolvedModelRoute,
RoutedMessagesRequest,
@@ -1114,7 +1115,7 @@ async def test_candidate_fallback_resolves_each_opencode_transport(
resolved = ResolvedModelRoute(
original_model="public-model",
primary=target(primary_model),
- fallbacks=(target(fallback_model),),
+ fallbacks=(ProviderModelCandidate(target(fallback_model)),),
reasoning_preference=ReasoningPreference.INHERIT,
)
executor = ProviderExecutor(