Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

fix(launch): guard zero-config default trio and report routing bundle in --dry-run (#108)

Elyas Mehtabuddind4c37dc0e47a
diff --git a/docs/guides/agent_launchers.md b/docs/guides/agent_launchers.md
index a48ee9001..f22562c7e 100644
--- a/docs/guides/agent_launchers.md
+++ b/docs/guides/agent_launchers.md
@@ -48,6 +48,13 @@ strong tier using the validated coding-agent trio:
when route resolution selects an explicit or saved route bundle or single
model.
+The default trio uses OpenRouter model ids and therefore requires OpenRouter
+connectivity (`OPENROUTER_API_KEY`). If the resolved provider is not OpenRouter,
+the launcher fails fast. The strong tier stays `anthropic/claude-opus-4.7`, so
+`--weak-model`/`--classifier-model` don't make the trio reachable — pass
+`--model` for a single model, use `--routing-profiles` for a bundle, or set
+`OPENROUTER_API_KEY`.
+
## Override the default route
Use `--model` for a single-model passthrough session:
diff --git a/switchyard/cli/launch_command.py b/switchyard/cli/launch_command.py
index 5db565de5..b79a5164c 100644
--- a/switchyard/cli/launch_command.py
+++ b/switchyard/cli/launch_command.py
@@ -97,6 +97,36 @@ def resolve_launch_connectivity(
return connectivity.api_key, connectivity.base_url
+# Marker for the OpenRouter gateway. The zero-flag deterministic default trio
+# uses OpenRouter-only model ids, so a resolved endpoint that isn't OpenRouter
+# cannot serve them.
+_OPENROUTER_URL_MARKER = "openrouter.ai"
+
+
+def _reject_openrouter_only_default_trio(target: str, base_url: str) -> None:
+ """Fail fast when the zero-config default trio can't reach the provider.
+
+ The deterministic zero-flag default uses OpenRouter-only model ids
+ (``anthropic/claude-opus-4.7`` / ``moonshotai/kimi-k2.6`` /
+ ``google/gemini-3.5-flash``). This runs only on the deterministic path, so
+ ``--model`` has already been ruled out, and ``--weak-model`` /
+ ``--classifier-model`` do not help because the strong tier stays
+ ``anthropic/claude-opus-4.7``. So when the resolved endpoint is not
+ OpenRouter, raise :class:`SystemExit` pointing the user at ``--model``,
+ ``--routing-profiles``, or ``OPENROUTER_API_KEY`` instead of launching a
+ trio that can't work.
+ """
+ if _OPENROUTER_URL_MARKER in base_url:
+ return
+ raise SystemExit(
+ f"launch {target}: the zero-config default trio "
+ f"(anthropic/claude-opus-4.7, moonshotai/kimi-k2.6, "
+ f"google/gemini-3.5-flash) is OpenRouter-only, but the resolved "
+ f"endpoint is {base_url!r}. Pass --model, use --routing-profiles, or "
+ f"set OPENROUTER_API_KEY."
+ )
+
+
def _is_deterministic_launch(
target: str,
args: argparse.Namespace,
@@ -605,6 +635,7 @@ def cmd_launch_claude(args: argparse.Namespace) -> None:
classifier_model=dry_run_classifier_model,
profile=dry_run_profile,
classifier_min_confidence=dry_run_min_confidence,
+ routing_profiles=routing_profiles,
))
return
@@ -614,6 +645,10 @@ def cmd_launch_claude(args: argparse.Namespace) -> None:
startup_timing.mark("config + credentials resolved")
if deterministic:
+ _reject_openrouter_only_default_trio(
+ target="claude",
+ base_url=primary_connectivity.base_url,
+ )
primary_connectivity = require_launch_tier_key(
target="claude",
tier=PRIMARY_TIER,
@@ -798,6 +833,7 @@ def cmd_launch_codex(args: argparse.Namespace) -> None:
classifier_model=dry_run_classifier_model,
profile=dry_run_profile,
classifier_min_confidence=dry_run_min_confidence,
+ routing_profiles=routing_profiles,
))
return
@@ -806,6 +842,10 @@ def cmd_launch_codex(args: argparse.Namespace) -> None:
)
if deterministic:
+ _reject_openrouter_only_default_trio(
+ target="codex",
+ base_url=primary_connectivity.base_url,
+ )
primary_connectivity = require_launch_tier_key(
target="codex",
tier=PRIMARY_TIER,
@@ -1006,6 +1046,7 @@ def cmd_launch_openclaw(args: argparse.Namespace) -> None:
classifier_model=dry_run_classifier_model,
profile=dry_run_profile,
classifier_min_confidence=dry_run_min_confidence,
+ routing_profiles=routing_profiles,
))
return
@@ -1014,6 +1055,10 @@ def cmd_launch_openclaw(args: argparse.Namespace) -> None:
)
if deterministic:
+ _reject_openrouter_only_default_trio(
+ target="openclaw",
+ base_url=primary_connectivity.base_url,
+ )
primary_connectivity = require_launch_tier_key(
target="openclaw",
tier=PRIMARY_TIER,
diff --git a/switchyard/cli/output.py b/switchyard/cli/output.py
index c2f614a71..887e96c54 100644
--- a/switchyard/cli/output.py
+++ b/switchyard/cli/output.py
@@ -143,12 +143,19 @@ def format_dry_run(
classifier_model: str | None = None,
profile: str | None = None,
classifier_min_confidence: float | None = None,
+ routing_profiles: str | None = None,
) -> str:
"""Render resolved launch settings without exposing secrets.
The optional ``classifier_*`` / ``profile`` kwargs are populated by the
deterministic-routing dispatch path — the routing-policy fields that
aren't carried on :class:`LaunchRouteConfig`.
+
+ ``routing_profiles`` is the resolved routing-profiles YAML path for a
+ multi-chain bundle launch. When set, the summary reports ``route: bundle``
+ plus the bundle path and its route ids instead of the single-tier
+ :func:`format_route_config` view (``route`` is a placeholder single-tier
+ config in that case).
"""
lines = [
@@ -158,15 +165,28 @@ def format_dry_run(
f"port: {port if port is not None else 'auto'}",
f"timeout: {timeout if timeout is not None else 'default'}",
]
- for route_line in format_route_config(route):
- lines.append(route_line)
- if route.type == "deterministic":
- if classifier_model:
- lines.append(f"classifier model: {classifier_model}")
- if profile:
- lines.append(f"profile: {profile}")
- if classifier_min_confidence is not None:
- lines.append(f"min confidence: {classifier_min_confidence:.2f}")
+ if routing_profiles:
+ from switchyard.cli.route_bundle import (
+ parse_routing_profiles_file,
+ routing_profile_model_ids,
+ )
+
+ lines.append("route: bundle")
+ lines.append(f"routing profiles: {routing_profiles}")
+ for route_id in routing_profile_model_ids(
+ parse_routing_profiles_file(routing_profiles)
+ ):
+ lines.append(f" {route_id}")
+ else:
+ for route_line in format_route_config(route):
+ lines.append(route_line)
+ if route.type == "deterministic":
+ if classifier_model:
+ lines.append(f"classifier model: {classifier_model}")
+ if profile:
+ lines.append(f"profile: {profile}")
+ if classifier_min_confidence is not None:
+ lines.append(f"min confidence: {classifier_min_confidence:.2f}")
if forwarded_args:
lines.append(f"forwarded args: {' '.join(forwarded_args)}")
return "\n".join(lines)
diff --git a/tests/test_launch_claude_deterministic.py b/tests/test_launch_claude_deterministic.py
index c06a371a8..17d09170d 100644
--- a/tests/test_launch_claude_deterministic.py
+++ b/tests/test_launch_claude_deterministic.py
@@ -10,8 +10,6 @@ overrides (``--weak-model``, ``--classifier-model``, ``--profile``,
``--classifier-min-confidence``) still tune the default trio.
"""
-from __future__ import annotations
-
import pytest
@@ -249,6 +247,66 @@ class TestDispatch:
# Dry-run prints + returns without SystemExit.
_cmd_launch_claude(args)
+ def test_dry_run_routing_profiles_reports_bundle(
+ self, monkeypatch, tmp_path, capsys,
+ ) -> None:
+ """A ``--routing-profiles`` dry run reports ``route: bundle``, not single."""
+ from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
+
+ yaml_path = tmp_path / "routes.yaml"
+ yaml_path.write_text(
+ "routes:\n"
+ " my-route:\n"
+ " type: model\n"
+ " model: openai/gpt-4o-mini\n",
+ encoding="utf-8",
+ )
+
+ parser = _build_parser()
+ args = parser.parse_args([
+ "--routing-profiles", str(yaml_path),
+ "launch", "claude", "--dry-run",
+ ])
+
+ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
+ monkeypatch.setattr(
+ "switchyard.cli.launch_command.resolve_launch_connectivity",
+ lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
+ )
+
+ _cmd_launch_claude(args)
+
+ out = capsys.readouterr().out
+ assert "route: bundle" in out
+ assert "route: single" not in out
+
+ def test_zero_config_non_openrouter_rejects_default_trio(
+ self, monkeypatch, tmp_path,
+ ) -> None:
+ """Zero-flag launch against a non-OpenRouter provider fails fast."""
+ from switchyard.cli.switchyard_cli import _build_parser, _cmd_launch_claude
+
+ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
+ monkeypatch.setenv("NVIDIA_API_KEY", "nvapi-test")
+ monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+ monkeypatch.setattr(
+ "switchyard.cli.launch_command.resolve_launch_connectivity",
+ lambda args, **_kw: ("nvapi-test", "https://inference-api.nvidia.com/v1"),
+ )
+
+ parser = _build_parser()
+ args = parser.parse_args(["launch", "claude"])
+
+ with pytest.raises(SystemExit) as exc_info:
+ _cmd_launch_claude(args)
+
+ message = str(exc_info.value)
+ assert "OpenRouter-only" in message
+ assert "anthropic/claude-opus-4.7" in message
+ assert "moonshotai/kimi-k2.6" in message
+ assert "google/gemini-3.5-flash" in message
+ assert "https://inference-api.nvidia.com/v1" in message
+
class TestRoutesByDefault:
"""The deterministic launch must boot claude on the *router*, not strong.
diff --git a/tests/test_launch_codex.py b/tests/test_launch_codex.py
index 1c3ab32b2..5fc23a6bc 100644
--- a/tests/test_launch_codex.py
+++ b/tests/test_launch_codex.py
@@ -506,9 +506,12 @@ class TestLaunchCodex:
)
monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))
+ # OpenRouter endpoint: the zero-flag default trio is OpenRouter-only, so
+ # the deterministic default only dispatches when the resolved endpoint is
+ # OpenRouter (a non-OpenRouter provider is rejected).
monkeypatch.setattr(
"switchyard.cli.launch_command.resolve_launch_connectivity",
- lambda args, **_kw: ("sk-test", "https://inference-api.nvidia.com/v1"),
+ lambda args, **_kw: ("sk-test", "https://openrouter.ai/api/v1"),
)
captured: dict = {}