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
chore: Remove Python launchers and `switchyard` CLI (#501)
Graham King43fc1a71b8ba
diff --git a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md b/.agents/skills/switchyard-coding-agent-launchers/SKILL.mddeleted file mode 100644index 18a7d9e2d..000000000--- a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md+++ /dev/null@@ -1,48 +0,0 @@-----name: switchyard-coding-agent-launchers-description: Modify or debug Switchyard's Claude Code, Codex CLI, or OpenClaw launchers. Use for changes under switchyard/cli/launchers, launch_command.py, launcher configuration, temporary agent workspaces, model catalogs, or launcher smoke tests.------# Coding-Agent Launchers--Launchers start a local Switchyard server and configure an external agent process to use it. Read-the current launcher, its dispatch path, and its tests before editing; routing construction changes-often, while the process-specific contracts below are stable.--## Process Contracts--- Claude Code is configured through Anthropic environment variables.-- Codex receives a temporary provider and model catalog through CLI configuration.-- OpenClaw receives a temporary state directory and `openclaw.json`.-- Temporary files, environment changes, and child processes must be cleaned up on success, error,- and interruption.-- Secrets may be passed to child processes but must not be logged, persisted in committed files, or- rendered in status output.--## Workflow--1. Trace the command from `switchyard/cli/switchyard_cli.py` through- `switchyard/cli/launch_command.py` into the selected launcher.-2. Read the launcher-specific tests and any shared server/configuration helpers it calls.-3. Keep launcher code focused on external-process configuration. Routing policies and LLM behavior- belong in the shared server or library path, not launcher-only branches.-4. Preserve optional-dependency boundaries with lazy imports.-5. Run the focused launcher tests discovered for the changed command, then the CLI help smoke.--Find the current focused tests rather than maintaining a static test inventory:--```bash-rg --files tests | rg 'launch|openclaw|codex|claude|user_config|model_discovery|verify'-```--For OpenAI-compatible providers such as OpenRouter or NVIDIA endpoints, prefer existing base URL,-API key, and model configuration. Add provider-specific launcher behavior only for a real process,-authentication, or protocol difference.--## Anti-Patterns--- Adding one launcher flag per routing algorithm.-- Building a separate routing stack inside a launcher.-- Importing server or provider dependencies at module import time.-- Leaving temporary catalogs, config files, or modified environment variables behind.-- Assuming the three external agents accept the same configuration mechanism.diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 901618b59..3a2c30382 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -168,7 +168,6 @@ jobs:runs-on: ubuntu-latestenv:SWITCHYARD_DEFAULT_PACKAGE: "nemo-switchyard @ file://${{ github.workspace }}"- SWITCHYARD_EXTRAS_PACKAGE: "nemo-switchyard[cli] @ file://${{ github.workspace }}"steps:- uses: actions/checkout@v4- uses: astral-sh/setup-uv@v6@@ -213,19 +212,6 @@ jobs:sys.exit(f"FAIL: heavy packages pulled into slim install: {extras}")print(f"OK: all {len(forbidden)} heavy packages absent from slim install.")PY- - name: Verify CLI works with its extra- working-directory: /tmp- run: |- uv run --isolated --no-project --python 3.10 \- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \- switchyard launch claude --help > /dev/null- uv run --isolated --no-project --python 3.10 \- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \- switchyard launch claude --help 2>&1 | grep -q -- '--model' || { echo 'FAIL: --model flag missing from help'; exit 1; }- uv run --isolated --no-project --python 3.10 \- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \- switchyard launch claude --help 2>&1 | grep -q -- '--config' || { echo 'FAIL: --config flag missing from help'; exit 1; }-# Single required check for branch protection. Gates on every job above so# the ruleset never needs editing when jobs are added or renamed.ci-success:diff --git a/.github/workflows/readme.yml b/.github/workflows/readme.ymldeleted file mode 100644index 458428c86..000000000--- a/.github/workflows/readme.yml+++ /dev/null@@ -1,57 +0,0 @@-name: README--# Executable coverage for README.md.-#-# Fails when the Rust server configuration in the README is malformed. The-# exercise lives in tests/readme/ so it reproduces locally with-# `uv run pytest tests/readme -v`.--on:- pull_request:- paths:- - "README.md"- - "Cargo.toml"- - "crates/switchyard-server/**"- - "tests/readme/**"- - "pyproject.toml"- - "uv.lock"- - ".github/workflows/readme.yml"- push:- branches: [main]- paths:- - "README.md"- - "Cargo.toml"- - "crates/switchyard-server/**"- - "tests/readme/**"- - "pyproject.toml"- - "uv.lock"- - ".github/workflows/readme.yml"--concurrency:- group: ${{ github.workflow }}-${{ github.ref }}- cancel-in-progress: ${{ github.event_name == 'pull_request' }}--permissions:- contents: read--jobs:- readme:- name: Run README flow- runs-on: ubuntu-latest- steps:- - uses: actions/checkout@v4- - uses: astral-sh/setup-uv@v6- with:- python-version: "3.12"- enable-cache: true- cache-dependency-glob: "uv.lock"- - name: Install- run: uv sync --locked- - name: Exercise the README- run: uv run pytest tests/readme -v- # Legacy Python README execution:- # run: uv run pytest tests/readme --markdown-docs README.md -v- # env:- # OPENAI_API_KEY: sk-test- # NVIDIA_API_KEY: nvapi-test- # ANTHROPIC_API_KEY: sk-ant-testdiff --git a/AGENTS.md b/AGENTS.mdindex e80f0a5e8..852fc811d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -127,7 +127,6 @@ testing, and review do not require loading a skill.| Skill | Use it for ||---|---|| `publish-python-release` | Python wheel artifacts, PyPI releases, and release workflow changes |-| `switchyard-coding-agent-launchers` | Claude Code, Codex, or OpenClaw launcher behavior || `switchyard-docs` | Published MkDocs pages, strict builds, previews, and docs CI || `switchyard-rust-review` | Focused review of Rust, PyO3, async, streaming, and crate boundaries || `switchyard-testing-ci` | Selecting non-obvious validation or diagnosing CI failures |@@ -149,8 +148,7 @@ OpenAI Responses, and Anthropic Messages APIs. `switchyard-libsy` owns routingalgorithms, `switchyard-protocol` owns provider-neutral request and responsetypes, and `switchyard-llm-client` performs translated HTTP calls.-Python is an integration layer. `switchyard launch` hosts the native server for-coding agents, `switchyard.libsy` exposes selected algorithms, and+Python is an integration layer. `switchyard.libsy` exposes selected algorithms, and`switchyard_rust.server` exposes the native server lifecycle through PyO3.## Project Structure@@ -158,11 +156,6 @@ coding agents, `switchyard.libsy` exposes selected algorithms, and```switchyard/├── __init__.py # Package version-├── cli/ # CLI (requires `nemo-switchyard[cli]`)-│ ├── switchyard_cli.py # `switchyard` entry point-│ ├── launch_command.py # `switchyard launch`-│ ├── defaults/ # packaged OpenRouter TOML deployment-│ └── launchers/ # Claude, Codex, and OpenClaw launchers└── libsy/ # typed Python wrappers for libsy algorithmsswitchyard_rust/ # Python facades over the PyO3 extension@@ -179,8 +172,7 @@ tests/ # Unit tests (pytest)## Tech Stack- **Rust 1.96.1**, edition 2024, Tokio, Axum, and PyO3-- **Python 3.10+** for launchers and native bindings-- **prompt-toolkit** for interactive launcher sessions+- **Python 3.10+** for native bindings- **uv** as the package manager (preferred over pip)- **Cargo test + pytest** for testing- **ruff** for linting, **mypy** (strict) for type checking@@ -202,16 +194,7 @@ and their transitives never appear in downstream vulnerability scans.### Running Switchyard```bash-export OPENROUTER_API_KEY="sk-or-..."--# Launch against the packaged OpenRouter deployment.-switchyard launch claude --model switchyard-switchyard launch codex --model switchyard--# Or select a route from a custom native TOML deployment.-switchyard launch claude --model my-route --config routes.toml--# Run a standalone native server.+# Run the standalone native server.switchyard-server --config routes.toml --port 4000```@@ -222,7 +205,7 @@ switchyard-server --config routes.toml --port 4000uv run pytest tests/ -v# Single test file / function-uv run pytest tests/test_launchers.py -v+uv run pytest tests/test_libsy_minimal_bindings.py -v# Live end-to-end tests are not part of the public test suite; if you write# one, set the provider key explicitly and run it directly, e.g.:@@ -242,7 +225,7 @@ cargo test --workspace| `OPENAI_BASE_URL` | Base URL for OpenAI-compatible API || `ANTHROPIC_API_KEY` | API key for Anthropic Claude || `NVIDIA_API_KEY` | API key for NVIDIA NIM / Inference Hub |-| `OPENROUTER_API_KEY` | OpenRouter key used by the packaged launcher deployment |+| `OPENROUTER_API_KEY` | API key for OpenRouter-backed routes |## Code Stylediff --git a/CHANGELOG.md b/CHANGELOG.mdindex fe5576407..47e1a6b41 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -33,12 +33,15 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).### Removed+- **Python coding-agent launcher CLI** — the `switchyard` command, its Claude+ Code, Codex, and OpenClaw wrappers, and the shared launcher runtime are+ removed. Connect clients directly to the standalone native server instead.- **Deprecated Python server stack** — `switchyard serve`, YAML route bundles,the FastAPI endpoints and legacy chain, the `switchyard-components` crate,and their compatibility PyO3 bindings are removed. Use `switchyard-server`- with native TOML deployments, or `switchyard launch` for coding agents.-- **Packaging extras `[server]`, `[gpu]`, and `[all]`** — dropped together- with the deprecated Python server stack; only `[cli]` remains. Install+ with native TOML deployments.+- **Packaging extras `[server]`, `[gpu]`, `[all]`, and `[cli]`** — dropped+ together with the deprecated Python server stack and launcher CLI. Installserver functionality via the standalone `switchyard-server` binary instead.### Fixed@@ -58,8 +61,6 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).so moderation stops remain distinguishable. (#370)- **JSON rejection statuses preserved** — request-body rejections keep theunderlying status code instead of always returning 400. (#406)-- **Launcher config errors without tracebacks** — `switchyard launch` reports- configuration errors as messages rather than Python tracebacks. (#475)- **Default log level** — logging defaults to `info` for all crates instead ofdiscarding logs from crates without an explicit level; an unnecessary `rand`callback was removed on the way. (#471)diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex b4fd8983b..d7a42839b 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -203,7 +203,6 @@ Before making a change, identify the surface that owns it:`crates/switchyard-skill-distillation/tests/contracts.rs`.- Put native Python bindings in `crates/switchyard-py`; keep Python wrappers in`switchyard/libsy` or `switchyard_rust`.-- Put launcher behavior in `switchyard/cli`.Add Rust tests in the owning crate and Python tests in `tests/`. Export newpublic symbols from the owning crate or package rather than the top-leveldiff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdindex e9fae8ba5..c4191f50d 100644--- a/DEVELOPMENT.md+++ b/DEVELOPMENT.md@@ -27,21 +27,10 @@ installs pytest, ruff, mypy, and friends. Use `uv sync --group dev` if you wantto be explicit. Dev tooling is **not** part of the published wheel's METADATA,so it never appears in downstream vulnerability scans.-To pull in optional user-facing features as well:--```bash-uv sync --extra cli # add prompt-toolkit-uv sync --all-extras # everything (dev group is still included by default)-```--(`server` is already pulled in by the dev group, so you don't need-`--extra server` for local development.)-## Project Structure```switchyard/ # Python package-├── cli/ # CLI and coding-agent launchers└── libsy/ # Typed wrappers for libsy algorithmsswitchyard_rust/ # Python facades over the PyO3 extensioncrates/diff --git a/INSTALLATION.md b/INSTALLATION.mdindex 587c5c4e0..6354f120f 100644--- a/INSTALLATION.md+++ b/INSTALLATION.md@@ -22,20 +22,6 @@ pip install nemo-switchyardThe base package has no Python runtime dependencies. Its native extension ownsthe libsy and server implementations.-## Coding-Agent Launchers--Install the CLI extra to launch Claude Code, Codex CLI, or OpenClaw through the-packaged native server:--```bash-uv tool install --python 3.10 "nemo-switchyard[cli]"-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret-switchyard launch claude --model switchyard-```--The selected coding agent must already be installed and available on `PATH`.-Use `--config routes.toml` to select a custom native TOML deployment.-## Standalone ServerInstall the native Rust proxy from crates.io:diff --git a/README.md b/README.mdindex afeb70248..142f80ee7 100644--- a/README.md+++ b/README.md@@ -31,39 +31,8 @@ Switchyard is pre-alpha software that is evolving rapidly. The API and algorithm## Quick Start-Choose the launcher path to run Claude Code, Codex CLI, or OpenClaw through-Switchyard. Choose the server path to run Switchyard as a standalone proxy.-Choose the library path to embed routing in your own Rust application.--### Launcher Path--Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if it is-not already available, then install the published Switchyard tool:--```bash-curl -LsSf https://astral.sh/uv/install.sh | sh-source "$HOME/.local/bin/env"-uv tool install --python 3.10 "nemo-switchyard[cli]"-```--The coding agent you launch must also be installed and on your `PATH`. This does-not install the standalone `switchyard-server` binary; use the Server Path for-that.--Set an OpenRouter key and launch against the packaged deployment:--```bash-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret-switchyard launch claude --model switchyard-switchyard launch codex --model switchyard-switchyard launch openclaw --model switchyard-```--To use your own native TOML deployment, pass its route ID and configuration:--```bash-switchyard launch claude --model my-route --config routes.toml-```+Choose the server path to run Switchyard as a standalone proxy. Choose the library path to embed+routing in your own Rust application.### Server Path@@ -147,7 +116,7 @@ configured LLM client selects one upstream format.## Documentation-- **[Getting Started](docs/getting_started.md)**: complete launcher and standalone server walkthroughs+- **[Getting Started](docs/getting_started.md)**: complete standalone server walkthrough- **[Core Concepts](docs/core_concepts.md)**: LLM clients, targets, routes, model IDs, and routing algorithms- **[Routing Overview](docs/routing_algorithms/overview.md)**: choose and configure a routing algorithm- **[`switchyard-server`](crates/switchyard-server/README.md)**: server configuration, routing algorithms, and metricsdiff --git a/benchmark/codex_model_catalog.py b/benchmark/codex_model_catalog.pyindex 2fae573fc..b563b73ab 100644--- a/benchmark/codex_model_catalog.py+++ b/benchmark/codex_model_catalog.py@@ -9,7 +9,7 @@ import argparseimport jsonfrom pathlib import Path-from switchyard.cli.launchers.codex_model_catalog import (+from codex_model_catalog_lib import (_build_codex_model_catalog,_codex_model_display_name,)diff --git a/switchyard/cli/launchers/codex_model_catalog.py b/benchmark/codex_model_catalog_lib.pysimilarity index 80%rename from switchyard/cli/launchers/codex_model_catalog.pyrename to benchmark/codex_model_catalog_lib.pyindex 12e5acd71..76b5e25a2 100644--- a/switchyard/cli/launchers/codex_model_catalog.py+++ b/benchmark/codex_model_catalog_lib.py@@ -1,11 +1,11 @@# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0-"""Helpers for generating Codex model-catalog JSON.+"""Helpers for generating benchmark Codex model-catalog JSON.Codex only forwards reasoning controls for models it recognizes as-reasoning-capable. Switchyard often exposes synthetic route ids, so launchers-and benchmark harnesses generate a tiny catalog that maps those route ids onto+reasoning-capable. Switchyard often exposes synthetic route ids, so the+benchmark harness generates a tiny catalog that maps those route ids ontoCodex's bundled GPT-5-style metadata."""@@ -14,9 +14,7 @@ from __future__ import annotationsimport copyimport jsonimport logging-import osimport subprocess-import tempfilefrom collections.abc import Sequencefrom typing import Any, TypeAlias@@ -124,37 +122,6 @@ def _build_codex_model_catalog(return {"models": models}-def _write_codex_model_catalog(- codex_bin: str,- entries: Sequence[CodexModelCatalogEntry],-) -> str | None:- """Write a temporary Codex catalog file and return its path."""- if not entries:- return None-- catalog = _build_codex_model_catalog(codex_bin, entries)- with tempfile.NamedTemporaryFile(- "w",- encoding="utf-8",- prefix="switchyard-codex-models-",- suffix=".json",- delete=False,- ) as handle:- json.dump(catalog, handle, separators=(",", ":"))- handle.write("\n")- return handle.name---def _remove_codex_model_catalog(path: str | None) -> None:- """Remove a temporary catalog created by :func:`_write_codex_model_catalog`."""- if path is None:- return- try:- os.unlink(path)- except OSError:- logger.debug("failed to remove temporary Codex model catalog %s", path, exc_info=True)--def _codex_model_display_name(model_id: str) -> str:"""Return a compact display name for a model id."""return model_id.rsplit("/", maxsplit=1)[-1]diff --git a/crates/switchyard-server/src/lib.rs b/crates/switchyard-server/src/lib.rsindex ffb5db06e..b4464f52d 100644--- a/crates/switchyard-server/src/lib.rs+++ b/crates/switchyard-server/src/lib.rs@@ -1358,10 +1358,10 @@ fn model_entry_json(model: &str, capabilities: ModelCapabilities) -> Value {// Builds the metadata Codex requires when it discovers models from a direct provider.//-// This mirrors Codex's `ModelInfo` card. The launcher path builds the same card in-// `switchyard/cli/launchers/codex_model_catalog.py`; keep the two in sync when Codex-// changes the shape. Every field below is either derived from the route's declared-// capabilities or a required `ModelInfo` field the server has no better value for.+// This mirrors Codex's `ModelInfo` card. The benchmark harness builds the same card in+// `benchmark/codex_model_catalog_lib.py`; keep the two in sync when Codex changes+// the shape. Every field below is either derived from the route's declared capabilities or a+// required `ModelInfo` field the server has no better value for.//// Two kinds of fields live here. context_window, tool_calling, and reasoning are model// facts a backend can publish; the route declares them in config today. The rest@@ -1417,7 +1417,7 @@ fn codex_model_entry_json(model: &str, capabilities: ModelCapabilities, priority}// The reasoning-effort presets Codex offers for a reasoning-capable route. Kept in-// step with the launcher template in `codex_model_catalog.py`.+// step with the benchmark template in `codex_model_catalog_lib.py`.fn reasoning_levels() -> Value {json!([{"effort": "low", "description": "Fast responses with lighter reasoning"},diff --git a/crates/switchyard-server/tests/server.rs b/crates/switchyard-server/tests/server.rsindex 21b1e46da..f19a22620 100644--- a/crates/switchyard-server/tests/server.rs+++ b/crates/switchyard-server/tests/server.rs@@ -2128,8 +2128,8 @@ target = "shared"json!(true));assert_eq!(codex_metadata["reasoning"]["default_verbosity"], "low");- // An undeclared route: null context window, non-reasoning, but tools default on- // so `switchyard launch codex` stays usable out of the box.+ // An undeclared route: null context window, non-reasoning, but tools default on so Codex+ // remains usable when connected directly to the server.assert_eq!(codex_metadata["undeclared"]["context_window"], json!(null));assert_eq!(codex_metadata["undeclared"]["supported_reasoning_levels"],diff --git a/docs/architecture.md b/docs/architecture.mdindex af38d0e8a..b795036aa 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -62,4 +62,4 @@ keep their native wire format regardless of the upstream a route selects.- [Getting Started](getting_started.md): install Switchyard and run a first request- [Routing Overview](routing_algorithms/overview.md): choose and configure a routing strategy-- [CLI Reference](cli_reference.md): configure and operate Switchyard from the command line+- [Server CLI Reference](cli_reference.md): configure and operate the standalone serverdiff --git a/docs/cli_reference.md b/docs/cli_reference.mdindex a8a0e583c..e5da32455 100644--- a/docs/cli_reference.md+++ b/docs/cli_reference.md@@ -1,57 +1,9 @@-# CLI Reference+# Server CLI Reference-Switchyard has two command-line paths:--- **Launcher Path:** `switchyard launch` starts a supported coding agent and- hosts the native Rust server through the packaged PyO3 binding.-- **Server Path:** `switchyard-server` runs the standalone Rust proxy for API- clients and custom deployments.--## Launcher Path: `switchyard launch`--Install the launcher with `uv tool install --python 3.10 "nemo-switchyard[cli]"`. The-selected coding agent must also be installed and available on `PATH`.--### Usage--```bash-switchyard launch <agent> --model <route-id> [--config <deployment.toml>] [-- <agent args>]-```--Supported agents are `claude`, `codex`, and `openclaw`.--| Option | Required | Purpose |-|---|:---:|---|-| `--model ID` | Yes | Route ID from the selected deployment. |-| `--config PATH` | No | Native TOML deployment. Defaults to the packaged OpenRouter deployment. |-| `-- ...` | No | Arguments forwarded unchanged to the coding agent. |--### Packaged Deployment--The packaged deployment exposes the route ID `switchyard` and uses OpenRouter:--```bash-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret-switchyard launch claude --model switchyard-switchyard launch codex --model switchyard-switchyard launch openclaw --model switchyard-```--### Custom Deployment--Select a route ID from an explicit native TOML deployment:--```bash-switchyard launch claude --model my-route --config routes.toml-```--The launcher owns the server lifecycle and stops it when the coding agent exits.-This command does not install or run the standalone `switchyard-server` binary.--## Server Path: `switchyard-server`+`switchyard-server` runs the standalone Rust proxy for API clients and custom deployments.Install the standalone binary with `cargo install --locked switchyard-server`.-It reads the same native TOML deployment schema accepted by the launcher.+It reads a native TOML deployment.### Usage@@ -81,29 +33,7 @@ switchyard-server --config routes.toml \--host 127.0.0.1 --port 4000```-## Removed Setup Commands--`switchyard configure`, `switchyard serve`, and `switchyard verify` are not-available. Export the-environment variable named by `api_key_env` in the native TOML deployment,-then pass that deployment on each run. For example:--```toml-[llm_clients.provider]-api_key_env = "PROVIDER_API_KEY"-```--```bash-export PROVIDER_API_KEY="your-provider-key" # pragma: allowlist secret-switchyard launch claude --model my-route --config routes.toml-```--The CLI does not save provider credentials, deployment paths, or host a-standalone server.-Use `switchyard-server --config routes.toml --dry-run` to-validate a native deployment before starting the standalone server.-## Related Documentation-- [Getting Started](getting_started.md): installation, configuration, and validation for both paths+- [Getting Started](getting_started.md): installation, configuration, and validation- [`switchyard-server`](../crates/switchyard-server/README.md): complete TOML schema, TLS, and metricsdiff --git a/docs/core_concepts.md b/docs/core_concepts.mdindex 79e29e2b2..87a3eeb4e 100644--- a/docs/core_concepts.md+++ b/docs/core_concepts.md@@ -16,10 +16,6 @@ Switchyard exposes the same Rust routing core through two runtime surfaces:targets and algorithms directly and can let libsy make calls or fulfill itsrequested model calls themselves.-The `switchyard launch` command is a launcher for coding agents. It hosts the-native Rust server through the packaged PyO3 binding and points the selected-agent at that server.-## Request FlowThe standalone server translates an inbound provider format into the shared@@ -107,7 +103,7 @@ selected target uses a different upstream protocol.## Where to Go Next- [Getting Started](getting_started.md): install and run either execution path.-- [CLI Reference](cli_reference.md): launcher and standalone server arguments.+- [Server CLI Reference](cli_reference.md): standalone server arguments.- [LLM Classifier Routing](routing_algorithms/llm_classifier_routing.md): configure classifier routing.- [Architecture](architecture.md): follow a request through the server and Rust crates.- [`switchyard-server`](../crates/switchyard-server/README.md): complete TOML schema, endpoints, and metrics.diff --git a/docs/getting_started.md b/docs/getting_started.mdindex 7ae7aaab9..b6070c865 100644--- a/docs/getting_started.md+++ b/docs/getting_started.md@@ -1,72 +1,12 @@# Getting Started with Switchyard-Switchyard has three native Rust execution paths:+Switchyard has two native Rust execution paths:-- **Launcher path:** install the Python-distributed CLI and launch Claude Code,- Codex, or OpenClaw through the packaged Rust server binding.- **Server path:** build and run the standalone Rust server for API clients andcustom deployments.- **Library path:** embed the routing algorithms directly in your own Rustapplication with `switchyard-libsy`.-## Launcher Path--Use this path when you want Switchyard to start and configure a supported coding-agent for you.--### Install the CLI--Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if it is-not already available:--```bash-curl -LsSf https://astral.sh/uv/install.sh | sh-source "$HOME/.local/bin/env"-```--Then install the published Switchyard tool:--```bash-uv tool install --python 3.10 "nemo-switchyard[cli]"-```--This creates an isolated Python tool environment containing the `switchyard`-CLI, its launcher dependency, and the packaged PyO3 Rust extension.-`switchyard launch` starts the native Rust server through that extension; this-path does not install or run the standalone `switchyard-server` binary.--Install the coding agent you want to launch, then verify both commands are on-your `PATH`.--### Launch with the packaged OpenRouter deployment--The packaged deployment exposes the route ID `switchyard`. Export an OpenRouter-key and choose an agent:--```bash-export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret-switchyard launch claude --model switchyard-```--Codex and OpenClaw use the same deployment:--```bash-switchyard launch codex --model switchyard-switchyard launch openclaw --model switchyard-```--### Launch with a custom deployment--Pass a native TOML deployment and select one of its route IDs:--```bash-switchyard launch codex --model my-route --config routes.toml-```--The launcher manages the native server lifecycle and points the selected coding-agent at it. The server configuration format is the same TOML schema used by the-standalone server below.-## Server PathUse this path when you want a standalone proxy for API clients or need todiff --git a/docs/index.md b/docs/index.mdindex 1dc5056cd..e68ed477b 100644--- a/docs/index.md+++ b/docs/index.md@@ -7,20 +7,17 @@ It supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages.| Goal | Path | Start here ||---|---|---|-| Run Claude Code, Codex, or OpenClaw through Switchyard | Launcher Path | [Install and launch an agent](getting_started.md#launcher-path) || Run Switchyard as a standalone proxy for API clients | Server Path | [Build and run the Rust server](getting_started.md#server-path) || Add Switchyard routing to a Rust application | Library Path | [`switchyard-libsy`](../crates/libsy/README.md) |-The Launcher Path installs the `switchyard` CLI and hosts the native Rust server-through its packaged PyO3 binding. The Server Path builds and runs the-standalone `switchyard-server` binary.+The Server Path builds and runs the standalone `switchyard-server` binary.## Explore- [Core Concepts](core_concepts.md): learn the LLM client, target, and route layers- [Routing Algorithms](routing_algorithms/overview.md): choose how requests select a model- [Architecture](architecture.md): understand the proxy and library components-- [CLI Reference](cli_reference.md): inspect supported launcher commands and options+- [Server CLI Reference](cli_reference.md): inspect `switchyard-server` commands and options- [Rust API](reference/rust_api.md): browse libsy and protocol crate documentation- [Context-Window Handling](operations/context_window.md): configure eviction and retry behaviordiff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.mdindex b6e8cb4a5..f5945acbd 100644--- a/docs/reference/toml_schema.md+++ b/docs/reference/toml_schema.md@@ -1,8 +1,7 @@# TOML Schema-The native deployment file defines the LLM clients, targets, and routes a-Switchyard server serves. It is read by `switchyard-server --config` and by-`switchyard launch --config`.+The native deployment file defines the LLM clients, targets, and routes that a+Switchyard server serves. It is read by `switchyard-server --config`.Validate a file without starting the server:diff --git a/examples/experimental/litellm/uv.lock b/examples/experimental/litellm/uv.lockindex 656b5b6a8..950a05de7 100644--- a/examples/experimental/litellm/uv.lock+++ b/examples/experimental/litellm/uv.lock@@ -458,15 +458,12 @@ version = "0.2.0"source = { editable = "../../../" }[package.metadata]-requires-dist = [{ name = "prompt-toolkit", marker = "extra == 'cli'", specifier = ">=3.0.52,<4.0" }]-provides-extras = ["cli"][package.metadata.requires-dev]dev = [{ name = "harbor", marker = "python_full_version >= '3.12'", git = "https://github.com/harbor-framework/harbor.git?rev=v0.6.4" },{ name = "maturin", specifier = ">=1.9,<2.0" },{ name = "mypy", specifier = ">=1.20.2,<2.0" },- { name = "nemo-switchyard", extras = ["cli"] },{ name = "pytest", specifier = ">=9.0.3,<10.0" },{ name = "pytest-asyncio", specifier = ">=1.3.0,<2.0" },{ name = "pytest-markdown-docs", specifier = ">=0.9.2" },diff --git a/mkdocs.yml b/mkdocs.ymlindex cbcea947b..05fd415bb 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -35,7 +35,7 @@ nav:- Context-Window Handling: operations/context_window.md- Soak Testing: operations/soak_test.md- Reference:- - CLI Reference: cli_reference.md+ - Server CLI Reference: cli_reference.md- TOML Schema: reference/toml_schema.md- Rust API: reference/rust_api.mddiff --git a/pyproject.toml b/pyproject.tomlindex 3b1c6aa3d..952404e36 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -27,18 +27,11 @@ classifiers = [dependencies = []-[project.optional-dependencies]-# CLI dependencies — prompt-toolkit for Claude Code launcher and ShellTUI.-# Only needed for users running the switchyard CLI.-cli = [- "prompt-toolkit>=3.0.52,<4.0",-]-# Dev tooling lives in a PEP 735 dependency group rather than an optional# extra so it is not advertised in the published wheel's METADATA. This# keeps pytest / ruff / mypy / pygments-via-pytest out of downstream# vulnerability scans, since they're never installed by `pip install-# nemo-switchyard` or any of the user-facing extras above.+# nemo-switchyard`.## Install dev tooling with `uv sync` (the `dev` group is uv's default and# is installed automatically) or `uv sync --group dev` to be explicit.@@ -56,7 +49,6 @@ dev = [# Harbor is needed only for local evaluation runs and currently requires Python 3.12.# Package users and Python 3.10/3.11 contributors do not install it."harbor @ git+https://github.com/harbor-framework/[email protected] ; python_version >= '3.12'",- "nemo-switchyard[cli]","pytest-markdown-docs>=0.9.2",]docs = [@@ -68,9 +60,6 @@ docs = [[tool.uv]managed = true-[project.scripts]-switchyard = "switchyard.cli.switchyard_cli:main"-[project.urls]Homepage = "https://github.com/NVIDIA-NeMo/Switchyard"Repository = "https://github.com/NVIDIA-NeMo/Switchyard"@@ -83,7 +72,6 @@ include = ["switchyard*"][tool.setuptools.package-data]switchyard = ["py.typed",- "cli/defaults/*.toml",]switchyard_rust = ["py.typed", "*.pyi"]diff --git a/switchyard/__init__.py b/switchyard/__init__.pyindex d978b6355..0725d384f 100644--- a/switchyard/__init__.py+++ b/switchyard/__init__.py@@ -1,7 +1,7 @@# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0-"""Switchyard's Python launcher and libsy bindings."""+"""Switchyard's Python libsy bindings."""from importlib import metadata as _metadatadiff --git a/switchyard/cli/__init__.py b/switchyard/cli/__init__.pydeleted file mode 100644index 37492b5ba..000000000--- a/switchyard/cli/__init__.py+++ /dev/null@@ -1,5 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Command-line UX for Switchyard."""-diff --git a/switchyard/cli/command_utils.py b/switchyard/cli/command_utils.pydeleted file mode 100644index 1b826383c..000000000--- a/switchyard/cli/command_utils.py+++ /dev/null@@ -1,16 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Small helpers shared by the remaining CLI commands."""---def strip_forwarded_args(args: list[str] | None) -> list[str]:- """Strip argparse's leading ``--`` sentinel from forwarded arguments."""-- forwarded = args or []- if forwarded and forwarded[0] == "--":- return forwarded[1:]- return forwarded---__all__ = ["strip_forwarded_args"]diff --git a/switchyard/cli/defaults/__init__.py b/switchyard/cli/defaults/__init__.pydeleted file mode 100644index b762f67df..000000000--- a/switchyard/cli/defaults/__init__.py+++ /dev/null@@ -1,4 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Packaged launcher deployment defaults."""diff --git a/switchyard/cli/defaults/openrouter.toml b/switchyard/cli/defaults/openrouter.tomldeleted file mode 100644index b598511d1..000000000--- a/switchyard/cli/defaults/openrouter.toml+++ /dev/null@@ -1,32 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--schema_version = 1--[llm_clients.openrouter]-format = "openai_chat"-base_url = "https://openrouter.ai/api/v1"-api_key_env = "OPENROUTER_API_KEY"--[targets.classifier]-id = "google/gemini-3.5-flash"-llm_client = "openrouter"--[targets.strong]-id = "anthropic/claude-opus-4.7"-llm_client = "openrouter"--[targets.weak]-id = "moonshotai/kimi-k2.7-code"-llm_client = "openrouter"--[routes.switchyard]-id = "switchyard"-type = "llm_classifier"-classifier_target = "classifier"-strong_target = "strong"-weak_target = "weak"-base_threshold = 0.5-threshold_step = 0.0-classify_trigger = "new_session"-message_hash_fallback = truediff --git a/switchyard/cli/launch_command.py b/switchyard/cli/launch_command.pydeleted file mode 100644index 94d08c190..000000000--- a/switchyard/cli/launch_command.py+++ /dev/null@@ -1,65 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Launch coding agents against an explicit native Switchyard deployment."""--import argparse-from pathlib import Path--from switchyard.cli.command_utils import strip_forwarded_args--_DEFAULT_CONFIG = Path(__file__).with_name("defaults") / "openrouter.toml"---def _config_path(value: str | None) -> Path:- """Resolve the selected deployment, defaulting to the packaged OpenRouter config."""- path = Path(value).expanduser() if value else _DEFAULT_CONFIG- if not path.is_file():- raise SystemExit(f"launch: config file not found: {path}")- return path---def cmd_launch_claude(args: argparse.Namespace) -> None:- """Run Claude Code against a native TOML deployment."""- from switchyard.cli.launchers.claude_code_launcher import launch_claude_config-- raise SystemExit(- launch_claude_config(- config=_config_path(args.config),- model=args.model,- claude_args=strip_forwarded_args(args.claude_args),- )- )---def cmd_launch_codex(args: argparse.Namespace) -> None:- """Run Codex against a native TOML deployment."""- from switchyard.cli.launchers.codex_cli_launcher import launch_codex_config-- raise SystemExit(- launch_codex_config(- config=_config_path(args.config),- model=args.model,- codex_args=strip_forwarded_args(args.codex_args),- )- )---def cmd_launch_openclaw(args: argparse.Namespace) -> None:- """Run OpenClaw against a native TOML deployment."""- from switchyard.cli.launchers.openclaw_launcher import launch_openclaw_config-- raise SystemExit(- launch_openclaw_config(- config=_config_path(args.config),- model=args.model,- openclaw_args=strip_forwarded_args(args.openclaw_args),- )- )---__all__ = [- "cmd_launch_claude",- "cmd_launch_codex",- "cmd_launch_openclaw",-]diff --git a/switchyard/cli/launchers/__init__.py b/switchyard/cli/launchers/__init__.pydeleted file mode 100644index 77748929d..000000000--- a/switchyard/cli/launchers/__init__.py+++ /dev/null@@ -1,5 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Tool launchers that supervise a local Switchyard proxy."""-diff --git a/switchyard/cli/launchers/claude_code_launcher.py b/switchyard/cli/launchers/claude_code_launcher.pydeleted file mode 100644index af7a0d98e..000000000--- a/switchyard/cli/launchers/claude_code_launcher.py+++ /dev/null@@ -1,218 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Run Claude Code through an in-process native Switchyard server."""--import logging-import os-import shutil-import subprocess-from pathlib import Path--from switchyard.cli.launchers.launcher_runtime import (- banner_pause,- configure_debug_file_logging,- print_ready_banner,- print_startup_failure,- silence_launch_loggers,- stdin_is_tty,- wait_for_proxy_ready,-)-from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter-from switchyard.cli.launchers.native_server import NativeServer-from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor-from switchyard.cli.launchers.session_summary import print_session_summary-from switchyard.cli.launchers.shell_tui import ShellTUI--logger = logging.getLogger(__name__)--_READY_TIMEOUT_S = 10.0-_EXIT_BINARY_NOT_FOUND = 127-_EXIT_SIGINT = 130---def _quiet_launch_loggers() -> None:- """Keep dependency chatter out of Claude Code's terminal UI."""- silence_launch_loggers(local_logger=logger)---def _find_claude_binary() -> str | None:- """Locate the ``claude`` executable.-- Checks ``$PATH`` first, then falls back to the two paths Claude- Code's installer writes to (``~/.claude/local/claude`` for the- official installer, ``~/.local/bin/claude`` for alternative layouts).- """- path_hit = shutil.which("claude")- if path_hit:- return path_hit- for candidate in (- Path.home() / ".claude" / "local" / "claude",- Path.home() / ".local" / "bin" / "claude",- ):- if candidate.is_file() and os.access(candidate, os.X_OK):- return str(candidate)- return None---def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:- """Probe ``GET /health`` until HTTP 200 or timeout."""- return wait_for_proxy_ready(port, timeout_s=timeout_s)---def _claude_env(- port: int,- model: str,- use_anthropic_auth: bool = False,-) -> dict[str, str]:- """Build the env-var overrides that route Claude Code through our proxy.-- * ``ANTHROPIC_BASE_URL`` — our proxy URL.- * ``ANTHROPIC_AUTH_TOKEN`` — an opaque local token unless the deployment- forwards the caller's Anthropic login.- * ``ANTHROPIC_API_KEY=""`` — silences the auth-conflict warning.- * ``ANTHROPIC_MODEL`` — initial active model for the session.- * ``ANTHROPIC_SMALL_FAST_MODEL`` — existing background-model override,- falling back to the active model.- * ``ANTHROPIC_CUSTOM_MODEL_OPTION`` — registers ``model`` as a custom- slot in ``/model`` so the user can come back to it after toggling- to a builtin.- * ``CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`` — tells Claude Code- to populate the picker from ``GET /v1/models``.- """- env = {- "ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}",- "ANTHROPIC_API_KEY": "",- "ANTHROPIC_MODEL": model,- "ANTHROPIC_SMALL_FAST_MODEL": os.environ.get("ANTHROPIC_SMALL_FAST_MODEL", model),- "ANTHROPIC_CUSTOM_MODEL_OPTION": model,- "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",- }- if not use_anthropic_auth:- env["ANTHROPIC_AUTH_TOKEN"] = "switchyard"- return env---def _supervise_claude_plain(- claude_bin: str,- claude_args: list[str],- env_overrides: dict[str, str],-) -> int:- """Run ``claude`` via plain subprocess (non-TTY / headless fallback).-- ``subprocess.run`` inherits stdin/stdout/stderr so piped use works.- ``KeyboardInterrupt`` is translated to exit code 130.- """- env = os.environ.copy()- env.update(env_overrides)- try:- result = subprocess.run([claude_bin, *claude_args], env=env, check=False)- return result.returncode- except KeyboardInterrupt:- return _EXIT_SIGINT---def _start_native_server(config: Path) -> NativeServer:- """Start the native server; kept separate for launcher supervision tests."""- return NativeServer(config)---def _run_claude_with_switchyard(- config: Path,- display_model: str,- claude_args: list[str],-) -> int:- """Host a native deployment and run Claude Code against it."""- claude_bin = _find_claude_binary()- if claude_bin is None:- logger.error(- "claude binary not found. Install it with "- "`curl -fsSL https://claude.ai/install.sh | bash`, "- "or place it on your PATH."- )- return _EXIT_BINARY_NOT_FOUND-- log_path = configure_debug_file_logging(display_model=display_model)- logger.debug("claude launcher module=%s", __file__)- server = _start_native_server(config)- resolved_port = server.port- stats = server.stats- strategy_summary = f"config → {config.name}"-- try:- try:- caller_auth = server.caller_auth_kind(display_model)- except ValueError as error:- logger.error("%s", error)- return 1- if caller_auth == "openai":- logger.error(- "this route forwards an OpenAI login; run it with `switchyard launch codex`"- )- return 1- env_overrides = _claude_env(- resolved_port,- display_model,- use_anthropic_auth=caller_auth == "anthropic",- )- if not _wait_ready(resolved_port):- print_startup_failure(- port=resolved_port,- timeout_s=_READY_TIMEOUT_S,- log_path=log_path,- )- return 1-- logger.info("proxy ready on port %d", resolved_port)- print_ready_banner(- port=resolved_port,- display_model=display_model,- log_path=log_path,- strategy_summary=strategy_summary,- routes=[display_model],- default_route=display_model,- )- if stdin_is_tty():- banner_pause()-- health = ProxyHealthMonitor(resolved_port)- logger.debug(- "claude env ANTHROPIC_BASE_URL=%s ANTHROPIC_MODEL=%s "- "ANTHROPIC_CUSTOM_MODEL_OPTION=%s GATEWAY_DISCOVERY=%s",- env_overrides.get("ANTHROPIC_BASE_URL"),- env_overrides.get("ANTHROPIC_MODEL"),- env_overrides.get("ANTHROPIC_CUSTOM_MODEL_OPTION"),- env_overrides.get("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"),- )- if stdin_is_tty():- footer = LiveStatsFooter(- stats, display_model, health,- strategy_label="config",- )- tui = ShellTUI(- command=[claude_bin, *claude_args],- footer_fn=footer.as_footer_fn(),- footer_height=lambda: footer.height,- env=env_overrides,- )- return tui.run()- return _supervise_claude_plain(- claude_bin, claude_args, env_overrides,- )- finally:- print_session_summary(stats)- server.close()---def launch_claude_config(- config: Path,- model: str,- claude_args: list[str],-) -> int:- """Run Claude Code against an explicit native server TOML deployment."""- _quiet_launch_loggers()- return _run_claude_with_switchyard(- config,- display_model=model,- claude_args=claude_args,- )diff --git a/switchyard/cli/launchers/codex_cli_launcher.py b/switchyard/cli/launchers/codex_cli_launcher.pydeleted file mode 100644index d3b1aced7..000000000--- a/switchyard/cli/launchers/codex_cli_launcher.py+++ /dev/null@@ -1,248 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Run Codex through an in-process native Switchyard server."""--import json-import logging-import os-import shutil-import subprocess-from collections.abc import Sequence-from pathlib import Path--from switchyard.cli.launchers.codex_model_catalog import (- CodexModelCatalogEntry,- _codex_model_display_name,- _remove_codex_model_catalog,- _write_codex_model_catalog,-)-from switchyard.cli.launchers.launcher_runtime import (- banner_pause,- configure_debug_file_logging,- print_ready_banner,- print_startup_failure,- silence_launch_loggers,- stdin_is_tty,- wait_for_proxy_ready,-)-from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter-from switchyard.cli.launchers.native_server import NativeServer-from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor-from switchyard.cli.launchers.session_summary import print_session_summary-from switchyard.cli.launchers.shell_tui import ShellTUI--logger = logging.getLogger(__name__)--_READY_TIMEOUT_S = 10.0-_EXIT_BINARY_NOT_FOUND = 127-_EXIT_SIGINT = 130-_PROVIDER_ID = "switchyard"---def _find_codex_binary() -> str | None:- """Locate the ``codex`` executable."""- path_hit = shutil.which("codex")- if path_hit:- return path_hit- for candidate in (- Path.home() / ".npm-global" / "bin" / "codex",- Path.home() / ".local" / "bin" / "codex",- ):- if candidate.is_file() and os.access(candidate, os.X_OK):- return str(candidate)- return None---def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:- """Probe ``GET /health`` until HTTP 200 or timeout."""- return wait_for_proxy_ready(port, timeout_s=timeout_s)---def _provider_overrides(- port: int,- use_openai_auth: bool = False,- model_catalog_json: str | None = None,-) -> list[str]:- """Build transient Codex provider overrides for the local proxy."""- base_url = f"http://127.0.0.1:{port}/v1"- overrides = [- "-c",- f'model_provider="{_PROVIDER_ID}"',- "-c",- f'model_providers.{_PROVIDER_ID}.name="{_PROVIDER_ID}"',- "-c",- f'model_providers.{_PROVIDER_ID}.base_url="{base_url}"',- "-c",- f'model_providers.{_PROVIDER_ID}.wire_api="responses"',- ]- if use_openai_auth:- overrides.extend(- ["-c", f"model_providers.{_PROVIDER_ID}.requires_openai_auth=true"]- )- else:- overrides.extend(- [- "-c",- f'model_providers.{_PROVIDER_ID}.env_key="OPENAI_API_KEY"',- "-c",- f"model_providers.{_PROVIDER_ID}.requires_openai_auth=false",- ]- )- if model_catalog_json is not None:- overrides.extend(["-c", f"model_catalog_json={json.dumps(model_catalog_json)}"])- return overrides---def _codex_env(use_openai_auth: bool = False) -> dict[str, str]:- """Return the environment required by the transient provider."""- env = os.environ.copy()- if not use_openai_auth:- env["OPENAI_API_KEY"] = "switchyard"- return env---def _codex_command(- codex_bin: str,- codex_args: list[str],- port: int,- model: str,- use_openai_auth: bool = False,- model_catalog_json: str | None = None,-) -> list[str]:- """Build the exact Codex command for the local proxy."""- return [- codex_bin,- *_provider_overrides(- port,- use_openai_auth=use_openai_auth,- model_catalog_json=model_catalog_json,- ),- "-m",- model,- *codex_args,- ]---def _supervise_codex(- command: list[str],- env: dict[str, str],-) -> int:- """Run Codex and return its exit code."""- try:- result = subprocess.run(command, env=env, check=False)- return result.returncode- except KeyboardInterrupt:- return _EXIT_SIGINT---def _start_native_server(config: Path) -> NativeServer:- """Start the native server; kept separate for supervision tests."""- return NativeServer(config)---def _run_codex_with_switchyard(- config: Path,- display_model: str,- codex_args: list[str],- codex_model_catalog: Sequence[CodexModelCatalogEntry],-) -> int:- """Host a native deployment and run Codex against it."""- codex_bin = _find_codex_binary()- if codex_bin is None:- logger.error(- "codex binary not found. Install it with "- "`npm install -g @openai/codex`, or place it on your PATH.",- )- return _EXIT_BINARY_NOT_FOUND-- silence_launch_loggers(local_logger=logger)- log_path = configure_debug_file_logging(display_model=display_model)- server = _start_native_server(config)- resolved_port = server.port- stats = server.stats- model_catalog_json: str | None = None- strategy_summary = f"config → {config.name}"-- try:- try:- caller_auth = server.caller_auth_kind(display_model)- except ValueError as error:- logger.error("%s", error)- return 1- if caller_auth == "anthropic":- logger.error(- "this route forwards an Anthropic login; run it with `switchyard launch claude`"- )- return 1- use_openai_auth = caller_auth == "openai"- model_catalog_json = _write_codex_model_catalog(codex_bin, codex_model_catalog)- command = _codex_command(- codex_bin,- codex_args,- resolved_port,- display_model,- use_openai_auth=use_openai_auth,- model_catalog_json=model_catalog_json,- )- env = _codex_env(use_openai_auth)- if not _wait_ready(resolved_port):- print_startup_failure(- port=resolved_port,- timeout_s=_READY_TIMEOUT_S,- log_path=log_path,- )- return 1-- logger.info("proxy ready on port %d", resolved_port)- print_ready_banner(- port=resolved_port,- display_model=display_model,- log_path=log_path,- strategy_summary=strategy_summary,- routes=[display_model],- default_route=display_model,- )- if stdin_is_tty():- banner_pause()-- if stdin_is_tty():- footer = LiveStatsFooter(- stats,- display_model,- ProxyHealthMonitor(resolved_port),- strategy_label="config",- )- return ShellTUI(- command=command,- footer_fn=footer.as_footer_fn(),- footer_height=lambda: footer.height,- env=env,- ).run()-- return _supervise_codex(command, env)- finally:- print_session_summary(stats)- server.close()- _remove_codex_model_catalog(model_catalog_json)---def launch_codex_config(- config: Path,- model: str,- codex_args: list[str],-) -> int:- """Run Codex against a native server TOML deployment."""- catalog = [- (- model,- f"{_codex_model_display_name(model)} (Switchyard)",- f"Route from {config.name}.",- )- ]- return _run_codex_with_switchyard(- config,- display_model=model,- codex_args=codex_args,- codex_model_catalog=catalog,- )diff --git a/switchyard/cli/launchers/cost_estimator.py b/switchyard/cli/launchers/cost_estimator.pydeleted file mode 100644index 642da5e25..000000000--- a/switchyard/cli/launchers/cost_estimator.py+++ /dev/null@@ -1,500 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Token cost estimation for LLM models.--Pricing is per 1 million tokens, stored on :class:`ModelPriceData`-so callers get attribute-level autocompletion and mypy-checked-field names instead of stringly-typed dict lookups.--Usage::-- from switchyard.cli.launchers.cost_estimator import estimate_cost-- breakdown = estimate_cost({"model": {"prompt_tokens": 10}})- print(f"Total: ${breakdown['total_cost']:.4f}")--See ``docs.anthropic.com/en/docs/about-claude/pricing`` for the-up-to-date Anthropic multipliers that back the Claude entries below.-"""--from __future__ import annotations--from dataclasses import dataclass---@dataclass(frozen=True)-class ModelPriceData:- """Per-model pricing, priced in USD per 1 million tokens.-- Attributes:- input: Base input price (fresh tokens that hit the model).- output: Output / completion price.- cached: Cache-read price (prompt cache *hit*). On Anthropic- this is 0.1× the base input price; on OpenAI the- provider applies the discount automatically when- ``prompt_tokens_details.cached_tokens`` is non-zero.- cache_write: Cache-write price (prompt cache *creation*).- On Anthropic the 5-minute TTL is 1.25× base input; the- 1-hour TTL is 2× base input (use a separate entry if- you need the long-TTL rate). OpenAI has no cache-write- premium — set this equal to ``input`` so the math- falls through to the base price. Defaults to 0.0 for- providers that do not bill cache-writes separately.- """-- input: float- output: float- cached: float- cache_write: float = 0.0---# Anthropic multipliers: 5m cache write = 1.25x base input, 1h cache-# write = 2x base input, cache read = 0.1x base input. The entries-# below use the 5m TTL prices when callers explicitly use Anthropic-# ephemeral prompt caching. Add per-tier overrides in :class:`LlmTarget`-# when we start pinning the 1h TTL.-MODEL_PRICING: dict[str, ModelPriceData] = {- # --- OpenAI / NVIDIA Inference Hub (OpenAI wire format) ---- # OpenAI caching has no write premium; ``cache_write`` = ``input``.- "openai/openai/gpt-5.2": ModelPriceData(- input=1.75, output=14.00, cached=0.175, cache_write=1.75,- ),- "openai/openai/openai/gpt-5.2": ModelPriceData(- input=1.75, output=14.00, cached=0.175, cache_write=1.75,- ),- "nvidia/nvidia/nemotron-3-super-v3": ModelPriceData(- input=0.10, output=0.50, cached=0.01, cache_write=0.10,- ),- "openai/nvidia/nvidia/nemotron-3-super-v3": ModelPriceData(- input=0.10, output=0.50, cached=0.01, cache_write=0.10,- ),- # Nemotron 3 Nano 30B-A3B — NVIDIA NIM published price (May 2026):- # $0.05 / $0.20 per 1M tokens. 30B total / 3B active params, 262K- # context window. OpenAI wire format on NIH; no cache_write premium.- # NIH model id is case-sensitive — only the CamelCase variant is- # exposed under the default-models key tier.- "nvidia/nvidia/Nemotron-3-Nano-30B-A3B": ModelPriceData(- input=0.05, output=0.20, cached=0.005, cache_write=0.05,- ),- "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B": ModelPriceData(- input=0.05, output=0.20, cached=0.005, cache_write=0.05,- ),- # Nemotron 3 Ultra — 550B/55B-active MoE, 1M ctx (released 2026-06-04).- # OpenRouter reference list price (June 2026): $0.50 / $2.20 per 1M- # tokens. The ``evals-nemotron-ultra-N`` ids are parallel deployments- # of the same model on the hub's benchmarking gateway (pair with- # ``X-Inference-Priority: batch``); same per-token pricing.- "nvidia/nvidia/nemotron-3-ultra": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- "openai/nvidia/nvidia/nemotron-3-ultra": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- "nvidia/nvidia/evals-nemotron-ultra": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- "nvidia/nvidia/evals-nemotron-ultra-2": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- "nvidia/nvidia/evals-nemotron-ultra-3": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- "nvidia/nvidia/evals-nemotron-ultra-4": ModelPriceData(- input=0.50, output=2.20, cached=0.05, cache_write=0.50,- ),- # Moonshot Kimi K2.6 — official platform.kimi.ai pricing (May 2026).- # OpenAI wire format, so no cache_write premium (cache_write = input).- "nvidia/moonshotai/kimi-k2.6": ModelPriceData(- input=0.95, output=4.00, cached=0.16, cache_write=0.95,- ),- "openai/nvidia/moonshotai/kimi-k2.6": ModelPriceData(- input=0.95, output=4.00, cached=0.16, cache_write=0.95,- ),- # Moonshot Kimi K2 / K2.5 — platform.kimi.ai (k2-thinking variant- # pricing, the closest standard tier; NVIDIA hub serves this as- # ``kimi-k2.5``). K2 series scheduled for discontinuation 2026-05-25- # per Moonshot; entry kept for runs still pinning the older preset- # until those migrate to K2.6.- "nvidia/moonshotai/kimi-k2.5": ModelPriceData(- input=0.60, output=2.50, cached=0.15, cache_write=0.60,- ),- "openai/nvidia/moonshotai/kimi-k2.5": ModelPriceData(- input=0.60, output=2.50, cached=0.15, cache_write=0.60,- ),- # Z.ai GLM-5.2 — REFERENCE pricing only. Switchyard reaches this model as- # ``glm-5.2-fp8`` on a self-hosted vLLM deployment, which has no per-token- # billing at all: the real cost is GPU-hours. These rates are an average of- # OpenRouter provider rates captured in late July 2026, not a first-party- # Z.ai quote. Keeping the same snapshot across benchmark calculations makes- # estimates comparable; it represents "what this traffic would have cost at- # market rates", not what NVIDIA is billed. The snapshot provides input,- # output, and cache-read prices but no cache-creation price, and the Hub does- # not report a separate cache-write bucket for this deployment. Use the base- # input rate as the fallback so any reported cache-write tokens are not- # accidentally zero-rated.- "glm-5.2-fp8": ModelPriceData(- input=0.805, output=2.53, cached=0.1495, cache_write=0.805,- ),- # DeepSeek V4 Flash — official api-docs.deepseek.com standard list- # price (post-promo). 284B total / 13B active, 1M-token context- # window. Aggressive cache discount (98% off on hits). OpenAI wire- # format on NVIDIA hub; no cache_write premium.- "nvidia/deepseek-ai/deepseek-v4-flash": ModelPriceData(- input=0.14, output=0.28, cached=0.0028, cache_write=0.14,- ),- "openai/nvidia/deepseek-ai/deepseek-v4-flash": ModelPriceData(- input=0.14, output=0.28, cached=0.0028, cache_write=0.14,- ),- "deepseek-v4-flash": ModelPriceData(- input=0.14, output=0.28, cached=0.0028, cache_write=0.14,- ),- # Gemini 3.5 Flash — Google Vertex global list price (ai.google.dev):- # input $1.50, output $9.00, cache-read $0.15 (90% off input). The- # default LLM-classifier model (gcp wire). No per-token cache-write- # premium (cache storage is billed per-hour, not per-token), so- # cache_write = input. Non-global regions run ~10% higher ($1.65/$9.90).- "gcp/google/gemini-3.5-flash": ModelPriceData(- input=1.50, output=9.00, cached=0.15, cache_write=1.50,- ),- "openai/gcp/google/gemini-3.5-flash": ModelPriceData(- input=1.50, output=9.00, cached=0.15, cache_write=1.50,- ),- "gemini-3.5-flash": ModelPriceData(- input=1.50, output=9.00, cached=0.15, cache_write=1.50,- ),- # DeepSeek V4 Pro — official api-docs.deepseek.com standard list- # price (post-promo). 1.6T total / 49B active, 1M-token context- # window. Pro tier is currently under a 75% promotional discount- # through 2026-05-31 UTC ($0.435 / $0.87 effective); we price at- # the standard rate for stable cost-model comparisons that outlive- # the promo window. The ``evals-`` prefix variant is the same- # model exposed on NVIDIA Inference Hub's benchmarking gateway- # (paired with the ``X-Inference-Priority: batch`` header) —- # bypasses the regular gateway's 6-min timeout that manifests as- # cascading 504s on V4-class models under -n 8 concurrency. Same- # per-token pricing on either gateway.- "nvidia/deepseek-ai/deepseek-v4-pro": ModelPriceData(- input=1.74, output=3.48, cached=0.0145, cache_write=1.74,- ),- "openai/nvidia/deepseek-ai/deepseek-v4-pro": ModelPriceData(- input=1.74, output=3.48, cached=0.0145, cache_write=1.74,- ),- "nvidia/deepseek-ai/evals-deepseek-v4-pro": ModelPriceData(- input=1.74, output=3.48, cached=0.0145, cache_write=1.74,- ),- "openai/nvidia/deepseek-ai/evals-deepseek-v4-pro": ModelPriceData(- input=1.74, output=3.48, cached=0.0145, cache_write=1.74,- ),- "deepseek-v4-pro": ModelPriceData(- input=1.74, output=3.48, cached=0.0145, cache_write=1.74,- ),- # --- Anthropic Claude on AWS Bedrock (via NVIDIA Inference Hub) ---- # 5-minute cache write = 1.25x input; cache read = 0.1x input.- # Opus 4.8 keeps the Opus-tier $5/$25 list price (docs.anthropic.com,- # verified 2026-07-11). Opus 5 ships as a drop-in upgrade at the same- # Opus-tier rate (platform.claude.com/docs/en/about-claude/pricing,- # verified 2026-07-27); fast mode ($10/$50) is a separate SKU and is- # not priced here.- "aws/anthropic/bedrock-claude-opus-5": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "aws/anthropic/bedrock-claude-opus-4-8": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "aws/anthropic/bedrock-claude-opus-4-7": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "aws/anthropic/bedrock-claude-opus-4-6": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "aws/anthropic/bedrock-claude-opus-4-5": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- # --- Anthropic Claude on Azure (via NVIDIA Inference Hub) ---- # Same per-token pricing as the Bedrock tier at parity versions;- # listed separately so routing decisions that pick the Azure-hosted- # variant doesn't silently report $0 in cost dashboards.- "azure/anthropic/claude-opus-4-6": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "azure/anthropic/claude-opus-4-7": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "azure/anthropic/claude-opus-4-8": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "azure/anthropic/claude-opus-5": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "azure/anthropic/claude-sonnet-4-5": ModelPriceData(- input=3.00, output=15.00, cached=0.30, cache_write=3.75,- ),- "aws/anthropic/bedrock-claude-sonnet-4-6": ModelPriceData(- input=3.00, output=15.00, cached=0.30, cache_write=3.75,- ),- "aws/anthropic/bedrock-claude-sonnet-4-5": ModelPriceData(- input=3.00, output=15.00, cached=0.30, cache_write=3.75,- ),- "aws/anthropic/bedrock-claude-haiku-4-5": ModelPriceData(- input=1.00, output=5.00, cached=0.10, cache_write=1.25,- ),- # --- Anthropic direct API aliases (no AWS prefix) ---- "claude-opus-5": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "claude-opus-4-8": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "claude-opus-4-7": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "claude-opus-4-6": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "claude-opus-4-5": ModelPriceData(- input=5.00, output=25.00, cached=0.50, cache_write=6.25,- ),- "claude-sonnet-4-6": ModelPriceData(- input=3.00, output=15.00, cached=0.30, cache_write=3.75,- ),- "claude-sonnet-4-5": ModelPriceData(- input=3.00, output=15.00, cached=0.30, cache_write=3.75,- ),- "claude-haiku-4-5": ModelPriceData(- input=1.00, output=5.00, cached=0.10, cache_write=1.25,- ),-}--_UNKNOWN_MODEL_PRICE = ModelPriceData(input=0.0, output=0.0, cached=0.0)---def estimate_model_cost(- model: str,- prompt_tokens: int,- completion_tokens: int,- cached_tokens: int = 0,- cache_creation_tokens: int = 0,- pricing: dict[str, ModelPriceData] | None = None,-) -> dict[str, float]:- """Estimate cost for a single model's token usage.-- Splits input tokens into three priced buckets:-- * **Base input** = ``prompt_tokens - cached_tokens -- cache_creation_tokens`` at the ``input`` rate.- * **Cached** = ``cached_tokens`` at the ``cached`` rate (0.1×- base on Anthropic, typically 10 % of base on OpenAI).- * **Cache creation** = ``cache_creation_tokens`` at the- ``cache_write`` rate (1.25× base on Anthropic 5m TTL; equal to- ``input`` on OpenAI where there is no write premium).-- Args:- model: Model name (looked up in *pricing*, defaults to- :data:`MODEL_PRICING`).- prompt_tokens: **Total** input tokens billed. Must include- the cached and cache-creation subsets — stats- normalise Anthropic's three sibling counters into this- semantic.- completion_tokens: Output tokens.- cached_tokens: Subset of ``prompt_tokens`` served from- prompt cache (cache *read* / hit).- cache_creation_tokens: Subset of ``prompt_tokens`` written- to prompt cache (cache *write*). 0 for OpenAI- responses. Anthropic-only.- pricing: Optional per-model price table override. Defaults- to :data:`MODEL_PRICING`.-- Returns:- Dict with the three input-bucket sub-costs plus totals:- ``base_input_cost``, ``cached_input_cost``,- ``cache_write_cost``, ``input_cost`` (sum of the three),- ``output_cost``, ``total_cost``. Unknown models get zero- prices and therefore zero costs across the board.- """- prices = (pricing or MODEL_PRICING).get(model, _UNKNOWN_MODEL_PRICE)-- base_input = max(prompt_tokens - cached_tokens - cache_creation_tokens, 0)- base_cost = (base_input / 1e6) * prices.input- cached_cost = (cached_tokens / 1e6) * prices.cached- cache_write_cost = (cache_creation_tokens / 1e6) * prices.cache_write- input_cost = base_cost + cached_cost + cache_write_cost- output_cost = (completion_tokens / 1e6) * prices.output- return {- "base_input_cost": round(base_cost, 6),- "cached_input_cost": round(cached_cost, 6),- "cache_write_cost": round(cache_write_cost, 6),- "input_cost": round(input_cost, 6),- "output_cost": round(output_cost, 6),- "total_cost": round(input_cost + output_cost, 6),- }---def estimate_cost(- models_stats: dict[str, dict[str, object]],- pricing: dict[str, ModelPriceData] | None = None,-) -> dict[str, object]:- """Estimate cost from a routing-stats ``models`` dict.-- Args:- models_stats: The ``"models"`` dict from- ``GET /v1/routing/stats``. Each key is a model ID; each- value has ``prompt_tokens`` + ``completion_tokens`` and- (optionally) ``cached_tokens`` + ``cache_creation_tokens``.- Missing optional fields default to 0 — so older stats- dumps still compute, they just don't get the new- cache-write accuracy benefit. Value type is- ``dict[str, object]`` because the routing-stats JSON- mixes ints / floats / strings (``tier`` label) under- the same mapping; callers should read token counters- with :func:`int` coercion.- pricing: Custom pricing table. Defaults to- :data:`MODEL_PRICING`.-- Returns:- A dict with ``{"models": {<name>: <breakdown>}, "total_cost":- float}`` where each ``<breakdown>`` is the return value of- :func:`estimate_model_cost`.- """- models_out: dict[str, dict[str, float]] = {}- total_cost = 0.0- for model, data in models_stats.items():- breakdown = estimate_model_cost(- model=model,- prompt_tokens=_as_int(data.get("prompt_tokens", 0)),- completion_tokens=_as_int(data.get("completion_tokens", 0)),- cached_tokens=_as_int(data.get("cached_tokens", 0)),- cache_creation_tokens=_as_int(data.get("cache_creation_tokens", 0)),- pricing=pricing,- )- models_out[model] = breakdown- total_cost += breakdown["total_cost"]- return {- "models": models_out,- "total_cost": round(total_cost, 6),- }---def _as_int(value: object) -> int:- """Best-effort coercion to ``int`` for values read out of a- ``dict[str, object]`` stats mapping.-- Values that arrive as integers stay as integers; ``float`` gets- truncated with :func:`int`; anything else returns 0 so malformed- input silently degrades to "no-op" rather than raising. The- project's ``disallow_any_explicit`` mypy setting means we can't- type the dict as ``dict[str, Any]`` and call ``data.get(...) + 0``- directly.- """- if isinstance(value, int):- return value- if isinstance(value, float):- return int(value)- return 0---def _as_float(value: object) -> float:- """Best-effort coercion to ``float`` (mirror of :func:`_as_int`)."""- if isinstance(value, (int, float)):- return float(value)- return 0.0---def format_cost_report(- stats: dict[str, object],- pricing: dict[str, ModelPriceData] | None = None,-) -> str:- """Format a human-readable cost report from routing stats.-- Args:- stats: The full response from ``GET /v1/routing/stats``.- pricing: Custom pricing table. Defaults to- :data:`MODEL_PRICING`.-- Returns:- Multi-line string suitable for printing.- """- models_raw = stats.get("models", {})- models_stats: dict[str, dict[str, object]] = (- models_raw if isinstance(models_raw, dict) else {}- )- cost = estimate_cost(models_stats, pricing)- cost_models_raw = cost.get("models", {})- cost_models: dict[str, dict[str, float]] = (- cost_models_raw if isinstance(cost_models_raw, dict) else {}- )-- totals_raw = stats.get("total_tokens", {})- totals: dict[str, object] = (- totals_raw if isinstance(totals_raw, dict) else {}- )-- lines: list[str] = []- # One routing decision == one agent turn at the router layer, so we- # surface it as "Turns" to match benchmark vocabulary (TerminalBench,- # SWE-bench, PinchBench all talk turns). ``stats["total_requests"]``- # stays the authoritative JSON field — only the human label changes.- lines.append(f"Turns: {_as_int(stats.get('total_requests', 0))}")- lines.append(- f"Tokens: {_as_int(totals.get('total', 0)):,} "- f"(prompt: {_as_int(totals.get('prompt', 0)):,}, "- f"completion: {_as_int(totals.get('completion', 0)):,})"- )- lines.append("")- for model, data in models_stats.items():- model_cost = cost_models.get(model, {})- cached = _as_int(data.get("cached_tokens", 0))- cache_create = _as_int(data.get("cache_creation_tokens", 0))- base_in = _as_int(data.get("prompt_tokens", 0)) - cached - cache_create- tok_total = _as_int(data.get("total_tokens", 0))- tok_pct = _as_float(data.get("token_pct", 0))- comp_tok = _as_int(data.get("completion_tokens", 0))- in_cost = model_cost.get("input_cost", 0.0)- out_cost = model_cost.get("output_cost", 0.0)- m_total = model_cost.get("total_cost", 0.0)- lines.append(f" {model}:")- # Per-model turn count == per-model ``calls`` in the stats JSON.- lines.append(f" Turns: {_as_int(data.get('calls', 0))}")- lines.append(f" Tokens: {tok_total:,} ({tok_pct:.1f}%)")- # Break down the input token counts only when cache activity- # happened — keeps the report terse on plain traffic.- if cached or cache_create:- lines.append(- f" Input cost: ${in_cost:,.4f} "- f"({base_in:,} base + {cache_create:,} cache-write "- f"+ {cached:,} cache-read)"- )- else:- lines.append(- f" Input cost: ${in_cost:,.4f} "- f"({base_in:,} tokens)"- )- lines.append(f" Output cost: ${out_cost:,.4f} "- f"({comp_tok:,} tokens)")- lines.append(f" Model total: ${m_total:,.4f}")- lines.append("")- # ``cost["total_cost"]`` is backend-only — ``estimate_cost`` ran- # against the backend ``models`` block. Add the classifier overhead- # (recorded into a separate accumulator bucket and surfaced under- # ``stats["classifier"]``) to get the true grand total.- classifier_raw = stats.get("classifier")- classifier_block = (- classifier_raw if isinstance(classifier_raw, dict) else {}- )- classifier_cost_raw = classifier_block.get("cost_estimate", {})- classifier_cost: dict[str, object] = (- classifier_cost_raw if isinstance(classifier_cost_raw, dict) else {}- )- classifier_total = _as_float(classifier_cost.get("total_cost", 0))- backend_total = _as_float(cost["total_cost"])- grand_total = backend_total + classifier_total- if classifier_total > 0:- lines.append(- f" Backend cost: ${backend_total:,.4f}",- )- lines.append(- f" Classifier overhead: ${classifier_total:,.4f} "- f"({_as_int(classifier_block.get('total_requests', 0))} calls)",- )- lines.append(f" TOTAL COST: ${grand_total:,.4f}")- return "\n".join(lines)diff --git a/switchyard/cli/launchers/launcher_runtime.py b/switchyard/cli/launchers/launcher_runtime.pydeleted file mode 100644index 8a5149aee..000000000--- a/switchyard/cli/launchers/launcher_runtime.py+++ /dev/null@@ -1,251 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Shared proxy/runtime helpers for one-command launchers."""--import logging-import os-import sys-import time-import urllib.request-from pathlib import Path--_debug_file_handler: logging.FileHandler | None = None-log = logging.getLogger(__name__)--#: Opener that ignores env proxies — loopback probes to the in-process proxy-#: must never be routed through a configured HTTP_PROXY.-_LOCAL_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))---def wait_for_proxy_ready(port: int, *, timeout_s: float) -> bool:- """Probe ``GET /health`` until HTTP 200 or timeout."""- url = f"http://127.0.0.1:{port}/health"- deadline = time.monotonic() + timeout_s- while time.monotonic() < deadline:- try:- # Loopback: bypass env proxies so a configured HTTP_PROXY can't- # intercept the 127.0.0.1 health probe.- with _LOCAL_OPENER.open(url, timeout=0.5):- return True- except Exception:- time.sleep(0.05)- return False---def configure_debug_file_logging(*, display_model: str) -> Path:- """Move launcher diagnostics to a per-run debug log and return its path."""- global _debug_file_handler-- state_home = os.environ.get("XDG_STATE_HOME")- state_dir = (- Path(state_home).expanduser()- if state_home- else Path.home() / ".local" / "state"- )- log_dir = state_dir / "switchyard" / "logs"- log_dir.mkdir(parents=True, exist_ok=True)- log_path = log_dir / f"switchyard-{os.getpid()}.log"-- if _debug_file_handler is not None:- _debug_file_handler.close()-- # Truncate any prior file under this pid, then let the delayed handler open- # it only when the first diagnostic is emitted.- log_path.write_text("", encoding="utf-8")- file_handler = logging.FileHandler(- log_path, mode="a", encoding="utf-8", delay=True,- )- _debug_file_handler = file_handler- file_handler.setLevel(logging.DEBUG)- file_handler.setFormatter(logging.Formatter(- "%(asctime)s %(levelname)-8s %(name)s %(message)s",- datefmt="%H:%M:%S",- ))-- root = logging.getLogger()- for handler in root.handlers[:]:- root.removeHandler(handler)- handler.close()- root.setLevel(logging.WARNING)-- switchyard_logger = logging.getLogger("switchyard")- for handler in switchyard_logger.handlers[:]:- switchyard_logger.removeHandler(handler)- handler.close()- switchyard_logger.addHandler(file_handler)- switchyard_logger.setLevel(logging.DEBUG)- switchyard_logger.propagate = False-- logging.getLogger("switchyard").info(- "=== switchyard debug log: model=%s pid=%d ===",- display_model,- os.getpid(),- )- return log_path---def silence_launch_loggers(*, local_logger: logging.Logger) -> None:- """Keep dependency chatter out of a child process terminal UI."""- logging.getLogger("switchyard").setLevel(logging.WARNING)- local_logger.setLevel(logging.INFO)---def stdin_is_tty() -> bool:- """Return whether stdin is a usable TTY."""- try:- return os.isatty(sys.stdin.fileno())- except Exception:- return False---# Keys that are abbreviated in the banner display.-_KEY_ABBREV: dict[str, str] = {- "confidence_threshold": "conf",- "llm-classifier": "classifier",-}---def _c(code: str, text: str, enabled: bool) -> str:- return f"\x1b[{code}m{text}\x1b[0m" if enabled else text---def _format_strategy_lines(summary: str) -> list[str]:- """Expand a strategy summary string into one or more banner lines.-- ``type: k1=v1, k2=v2`` → type on first line, each k=v pair indented.- ``noop`` → single line (no key=value pairs to split).- """- col = " routing " # label column: 2 indent + 7 label + 3 gap = 12 chars- pad = " " * len(col)- if ": " not in summary:- return [f"{col}{summary}"]- route_type, rest = summary.split(": ", 1)- pairs = [p.strip() for p in rest.split(", ") if p.strip()]- return [f"{col}{route_type}", *(f"{pad}{p}" for p in pairs)]---def _format_strategy_indented(- summary: str, indent: str, *, color: bool = False,-) -> list[str]:- """Expand a strategy summary as aligned key→value rows under *indent*."""- def dim(t: str) -> str: return _c("2", t, color)- def bold(t: str) -> str: return _c("1", t, color)-- if ": " not in summary:- return [f"{indent}{summary}"]-- route_type, rest = summary.split(": ", 1)- raw_pairs = [p.strip() for p in rest.split(", ") if p.strip()]-- kvs: list[tuple[str, str]] = []- for p in raw_pairs:- k, _, v = p.partition("=")- kvs.append((_KEY_ABBREV.get(k, k), v if _ else p))-- max_key = max((len(k) for k, _ in kvs if _), default=0)-- out = [f"{indent}{dim(route_type)}"]- for k, v in kvs:- pad = " " * (max_key - len(k) + 2)- out.append(f"{indent}{dim(k)}{pad}{bold(v)}")- return out---def print_ready_banner(- *,- port: int,- display_model: str,- log_path: Path | None = None,- strategy_summary: str | None = None,- routes: list[str] | None = None,- default_route: str | None = None,-) -> None:- """Write proxy/stats/routing details to stderr before the child takes over."""- clr = sys.stderr.isatty()-- def dim(t: str) -> str: return _c("2", t, clr)- def bold(t: str) -> str: return _c("1", t, clr)- def green(t: str) -> str: return _c("32", t, clr)- def cyan(t: str) -> str: return _c("36", t, clr)- def amber(t: str) -> str: return _c("33", t, clr)-- base = f"http://127.0.0.1:{port}"- sep = " " + dim("─" * 58)-- lines: list[str] = [- "",- sep,- f" {bold('switchyard')} {green('ready')} → {bold(display_model)}",- ]-- if routes:- col = " routes "- pad = " " * len(col)- lines.append("")- shown, rest = routes[:5], routes[5:]- for i, route in enumerate(shown):- is_default = route == default_route- marker = amber("▶") + " " if is_default else dim("○") + " "- default_tag = dim(" (default)") if is_default else ""- prefix = col if i == 0 else pad- name = bold(route) if is_default else dim(route)- lines.append(f"{prefix}{marker}{name}{default_tag}")- if is_default and strategy_summary:- lines.extend(- _format_strategy_indented(strategy_summary, pad + " ", color=clr)- )- if rest:- lines.append(f"{pad} {dim(f'… +{len(rest)} more')}")- elif strategy_summary:- lines.append("")- lines.extend(_format_strategy_lines(strategy_summary))-- lines += [- "",- f" {dim('proxy')} {cyan(base)}",- f" {dim('models')} {dim(f'curl -s {base}/v1/models')}",- f" {dim('stats')} {dim(f'curl -s {base}/v1/stats | python3 -m json.tool')}",- ]- if log_path is not None:- lines.append(f" {dim('debug')} {dim(str(log_path))}")- lines += [sep, ""]-- sys.stderr.write("\n".join(lines) + "\n")- sys.stderr.flush()---def banner_pause(timeout: float = 10.0) -> None:- """Hold the banner on screen for up to *timeout* seconds.-- Returns early if the user presses any key. Only call when stdin is a TTY.- """- import os- import select- import termios- import tty- if not sys.stdin.isatty():- return- fd = sys.stdin.fileno()- old = termios.tcgetattr(fd)- sys.stderr.write(f" [press any key to start, or waiting {int(timeout)}s…]\n")- sys.stderr.flush()- try:- tty.setraw(fd)- ready, _, _ = select.select([sys.stdin], [], [], timeout)- if ready:- os.read(fd, 1)- finally:- termios.tcsetattr(fd, termios.TCSADRAIN, old)- sys.stderr.write("\r\x1b[2K")- sys.stderr.flush()---def print_startup_failure(*, port: int, timeout_s: float, log_path: Path) -> None:- """Write proxy startup failure details to stderr."""- sys.stderr.write(- f"switchyard: proxy failed to become ready within {timeout_s:.1f}s — "- f"GET http://127.0.0.1:{port}/health never returned 200\n"- f"Check {log_path} for details.\n"- )- sys.stderr.flush()diff --git a/switchyard/cli/launchers/live_stats_footer.py b/switchyard/cli/launchers/live_stats_footer.pydeleted file mode 100644index 89855e7ca..000000000--- a/switchyard/cli/launchers/live_stats_footer.py+++ /dev/null@@ -1,154 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Shared live token-usage footer for launcher TUI sessions.--One layout for every routing strategy: an aggregate row across all requests-plus one indented row per active outbound model.-"""--from __future__ import annotations--from collections.abc import Callable, Mapping-from typing import cast--from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor-from switchyard.cli.launchers.stats_source import StatsSource--FOOTER_ROWS = 2---class LiveStatsFooter:- """Live stats footer: aggregate row plus one row per active model."""-- def __init__(- self,- stats: StatsSource,- model: str,- health: ProxyHealthMonitor,- *,- strategy_label: str | None = None,- ) -> None:- self._stats = stats- self._default_model_short = model.rsplit("/", 1)[-1]- self._health = health- self._strategy_label = strategy_label- # Ordered list of models seen in traffic so far. Grows as new tiers- # receive their first request; order is first-seen, which keeps the- # display stable across renders.- self._seen_models: list[str] = []- self._seen_set: set[str] = set()-- @property- def height(self) -> int:- """Current footer height: one aggregate plus each seen model (minimum two)."""- return FOOTER_ROWS - 1 + max(1, len(self._seen_models))-- def as_footer_fn(self) -> Callable[[int], list[tuple[str, int]]]:- return self.render-- def render(self, cols: int) -> list[tuple[str, int]]: # noqa: ARG002- self._health.poll()- snapshot = self._stats.snapshot_sync()- return [self._aggregate_row(snapshot), *self._tier_rows(snapshot)]-- def _aggregate_row(self, snapshot: Mapping[str, object]) -> tuple[str, int]:- totals = _mapping(snapshot, "total_tokens")- req = _int(snapshot, "total_requests")- errs = _int(snapshot, "total_errors")- prompt = _int(totals, "prompt")- completion = _int(totals, "completion")- cached = _int(totals, "cached")- h_str, h_w = self._health.indicator-- req_label = f"{req:,} req" + (f" ({errs} err)" if errs else "")- strategy_part = f" [{self._strategy_label}]" if self._strategy_label else ""- prefix = f" switchyard{strategy_part} · {req_label}"- styled = (- "\x1b[2m switchyard\x1b[0m"- + (f"\x1b[2m [{self._strategy_label}]\x1b[0m" if self._strategy_label else "")- + f"\x1b[2m · {req_label}\x1b[0m"- )-- in_p, in_s = f" · {prompt:,} in", f" · \x1b[96m{prompt:,}\x1b[0m in"- out_p, out_s = f" {completion:,} out", f" \x1b[92m{completion:,}\x1b[0m out"- cache_p = cache_s = ""- if cached:- cache_p = f" {cached:,} cached"- cache_s = f" \x1b[33m{cached:,}\x1b[0m cached"-- line = " " + h_str + styled + in_s + out_s + cache_s- width = 1 + h_w + len(prefix) + len(in_p) + len(out_p) + len(cache_p)- return (line, width)-- def _tier_rows(- self, snapshot: Mapping[str, object],- ) -> list[tuple[str, int]]:- """Return one row per model that has received traffic.-- Before traffic lands, a placeholder uses the launch model. Once traffic- arrives, rows grow in first-seen order and never shrink.- """- models = _mapping(snapshot, "models")- if not models:- return [_model_row(- self._default_model_short,- calls=0,- errors=0,- prompt=0,- completion=0,- cached=0,- )]-- for m in models:- if m not in self._seen_set:- self._seen_models.append(m)- self._seen_set.add(m)-- rows = []- for m in self._seen_models:- md = _mapping(models, m)- rows.append(_model_row(- m,- calls=_int(md, "calls"),- errors=_int(md, "errors"),- prompt=_int(md, "prompt_tokens"),- completion=_int(md, "completion_tokens"),- cached=_int(md, "cached_tokens"),- ))- return rows---def _model_row(- model: str,- *,- calls: int,- errors: int,- prompt: int,- completion: int,- cached: int,-) -> tuple[str, int]:- short = model.rsplit("/", 1)[-1]- req_label = f"{calls:,} req" + (f" ({errors} err)" if errors else "")- plain = f" {short} {req_label} · {prompt:,} in {completion:,} out"- styled = (- f"\x1b[2m \x1b[0m"- f"\x1b[1m{short}\x1b[0m "- f"\x1b[2m{req_label} · \x1b[0m"- f"\x1b[96m{prompt:,}\x1b[0m in "- f"\x1b[92m{completion:,}\x1b[0m out"- )- if cached:- plain += f" {cached:,} cached"- styled += f" \x1b[33m{cached:,}\x1b[0m cached"- return (styled, len(plain))---def _mapping(data: Mapping[str, object], key: str) -> Mapping[str, object]:- value = data.get(key)- return cast(Mapping[str, object], value) if isinstance(value, Mapping) else {}---def _int(data: Mapping[str, object], key: str) -> int:- value = data.get(key)- return value if isinstance(value, int) else 0diff --git a/switchyard/cli/launchers/native_server.py b/switchyard/cli/launchers/native_server.pydeleted file mode 100644index 98a01cb25..000000000--- a/switchyard/cli/launchers/native_server.py+++ /dev/null@@ -1,65 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Native Rust server lifecycle for coding-agent launchers."""--import json-import logging-import urllib.request-from collections.abc import Mapping-from pathlib import Path--from switchyard.cli.launchers.stats_source import StatsSource--log = logging.getLogger(__name__)--_LOCAL_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))---class NativeServerConfigError(RuntimeError):- """Raised when a native server deployment configuration is invalid."""---class HttpStatsSource(StatsSource):- """Read launcher statistics from the native server."""-- def __init__(self, base_url: str) -> None:- self._url = f"{base_url}/v1/stats"- self._last_snapshot: Mapping[str, object] = {}-- def snapshot_sync(self) -> Mapping[str, object]:- """Return fresh stats, retaining the last snapshot on transient failure."""- try:- with _LOCAL_OPENER.open(self._url, timeout=0.5) as response:- payload = json.load(response)- if isinstance(payload, dict):- self._last_snapshot = payload- except Exception:- log.debug("failed to fetch native launcher stats", exc_info=True)- return self._last_snapshot---class NativeServer:- """Host one TOML deployment through the PyO3 Rust server binding."""-- def __init__(self, config: Path) -> None:- from switchyard_rust.server import Server, ServerConfigError-- try:- self._server = Server(config, port=0)- except ServerConfigError as exc:- raise NativeServerConfigError(str(exc)) from exc- self.port: int = self._server.port- self.base_url: str = self._server.base_url- self.stats: StatsSource = HttpStatsSource(self.base_url)-- def caller_auth_kind(self, model: str) -> str | None:- """Return which caller credential the route forwards, if any."""- return self._server.caller_auth_kind(model)-- def close(self) -> None:- """Gracefully stop the native server."""- self._server.close()---__all__ = ["HttpStatsSource", "NativeServer", "NativeServerConfigError"]diff --git a/switchyard/cli/launchers/openclaw_launcher.py b/switchyard/cli/launchers/openclaw_launcher.pydeleted file mode 100644index 2fbe04977..000000000--- a/switchyard/cli/launchers/openclaw_launcher.py+++ /dev/null@@ -1,269 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Run OpenClaw through an in-process native Switchyard server."""--import json-import logging-import os-import shutil-import subprocess-import tempfile-from collections.abc import Sequence-from pathlib import Path-from typing import Any, TypeAlias--from switchyard.cli.launchers.launcher_runtime import (- banner_pause,- configure_debug_file_logging,- print_ready_banner,- print_startup_failure,- silence_launch_loggers,- stdin_is_tty,- wait_for_proxy_ready,-)-from switchyard.cli.launchers.live_stats_footer import LiveStatsFooter-from switchyard.cli.launchers.native_server import NativeServer-from switchyard.cli.launchers.proxy_health_monitor import ProxyHealthMonitor-from switchyard.cli.launchers.session_summary import print_session_summary-from switchyard.cli.launchers.shell_tui import ShellTUI--logger = logging.getLogger(__name__)--_READY_TIMEOUT_S = 10.0-_EXIT_BINARY_NOT_FOUND = 127-_EXIT_SIGINT = 130-_PROVIDER_ID = "switchyard"-_API_KEY_ENV = "SWITCHYARD_API_KEY"-_API_KEY_PLACEHOLDER = "switchyard"--OpenClawModelCatalogEntry: TypeAlias = tuple[str, str, str]---def _find_openclaw_binary() -> str | None:- """Locate the ``openclaw`` executable."""- path_hit = shutil.which("openclaw")- if path_hit:- return path_hit- for candidate in (- Path.home() / ".npm-global" / "bin" / "openclaw",- Path.home() / ".local" / "bin" / "openclaw",- ):- if candidate.is_file() and os.access(candidate, os.X_OK):- return str(candidate)- nvm_root = Path.home() / ".nvm" / "versions" / "node"- if nvm_root.is_dir():- for node_version in sorted(nvm_root.iterdir(), reverse=True):- candidate = node_version / "bin" / "openclaw"- if candidate.is_file() and os.access(candidate, os.X_OK):- return str(candidate)- return None---def _wait_ready(port: int, timeout_s: float = _READY_TIMEOUT_S) -> bool:- """Probe ``GET /health`` until HTTP 200 or timeout."""- return wait_for_proxy_ready(port, timeout_s=timeout_s)---def _qualified_model_id(model_id: str) -> str:- """Return the provider-qualified model ID used by OpenClaw."""- return f"{_PROVIDER_ID}/{model_id.lstrip('/')}"---def _openclaw_model_display_name(model_id: str) -> str:- """Return a short display name for a model ID."""- return model_id.rsplit("/", maxsplit=1)[-1]---def _build_openclaw_config(- port: int,- entries: Sequence[OpenClawModelCatalogEntry],- primary_model_id: str,-) -> dict[str, Any]:- """Build the transient OpenClaw configuration."""- models = [- {- "id": model_id,- "name": display_name,- "input": ["text"],- "contextWindow": 128000,- "maxTokens": 32000,- }- for model_id, display_name, _description in entries- ]- aliases = {- _qualified_model_id(model_id): {"alias": display_name}- for model_id, display_name, _description in entries- }- return {- "models": {- "mode": "merge",- "providers": {- _PROVIDER_ID: {- "baseUrl": f"http://127.0.0.1:{port}/v1",- "apiKey": "${" + _API_KEY_ENV + "}",- "api": "openai-completions",- "models": models,- }- },- },- "agents": {- "defaults": {- "model": {"primary": primary_model_id},- "models": aliases,- }- },- }---def _write_openclaw_workspace(- port: int,- entries: Sequence[OpenClawModelCatalogEntry],- primary_model_id: str,-) -> str:- """Write a transient OpenClaw workspace and return its path."""- workspace = tempfile.mkdtemp(prefix="switchyard-openclaw-")- config_path = Path(workspace) / "openclaw.json"- with config_path.open("w", encoding="utf-8") as handle:- json.dump(- _build_openclaw_config(port, entries, primary_model_id),- handle,- indent=2,- )- handle.write("\n")- return workspace---def _remove_openclaw_workspace(workspace: str | None) -> None:- """Remove a transient OpenClaw workspace."""- if workspace is not None:- shutil.rmtree(workspace, ignore_errors=True)---def _openclaw_env(workspace: str) -> dict[str, str]:- """Return the environment that selects the transient workspace."""- env = os.environ.copy()- env["OPENCLAW_STATE_DIR"] = workspace- env["OPENCLAW_HOME"] = workspace- env["OPENCLAW_CONFIG_PATH"] = str(Path(workspace) / "openclaw.json")- env["OPENCLAW_HIDE_BANNER"] = "1"- env[_API_KEY_ENV] = _API_KEY_PLACEHOLDER- return env---def _openclaw_command(openclaw_bin: str, openclaw_args: list[str]) -> list[str]:- """Build the OpenClaw command, defaulting to interactive chat."""- return [openclaw_bin, *(openclaw_args or ["chat"])]---def _supervise_openclaw(- openclaw_bin: str,- openclaw_args: list[str],- workspace: str,-) -> int:- """Run OpenClaw and return its exit code."""- try:- result = subprocess.run(- _openclaw_command(openclaw_bin, openclaw_args),- env=_openclaw_env(workspace),- check=False,- )- return result.returncode- except KeyboardInterrupt:- return _EXIT_SIGINT---def _start_native_server(config: Path) -> NativeServer:- """Start the native server; kept separate for supervision tests."""- return NativeServer(config)---def _run_openclaw_with_switchyard(- config: Path,- display_model: str,- openclaw_args: list[str],- catalog_entries: Sequence[OpenClawModelCatalogEntry],-) -> int:- """Host a native deployment and run OpenClaw against it."""- openclaw_bin = _find_openclaw_binary()- if openclaw_bin is None:- logger.error(- "openclaw binary not found. Install it with "- "`npm install -g openclaw@latest`, or place it on your PATH.",- )- return _EXIT_BINARY_NOT_FOUND-- silence_launch_loggers(local_logger=logger)- log_path = configure_debug_file_logging(display_model=display_model)- server = _start_native_server(config)- resolved_port = server.port- stats = server.stats- workspace: str | None = None- strategy_summary = f"config → {config.name}"-- try:- workspace = _write_openclaw_workspace(- port=resolved_port,- entries=catalog_entries,- primary_model_id=_qualified_model_id(display_model),- )- if not _wait_ready(resolved_port):- print_startup_failure(- port=resolved_port,- timeout_s=_READY_TIMEOUT_S,- log_path=log_path,- )- return 1-- logger.info("proxy ready on port %d", resolved_port)- print_ready_banner(- port=resolved_port,- display_model=display_model,- log_path=log_path,- strategy_summary=strategy_summary,- routes=[display_model],- default_route=display_model,- )- if stdin_is_tty():- banner_pause()-- if stdin_is_tty():- footer = LiveStatsFooter(- stats,- display_model,- ProxyHealthMonitor(resolved_port),- strategy_label="config",- )- return ShellTUI(- command=_openclaw_command(openclaw_bin, openclaw_args),- footer_fn=footer.as_footer_fn(),- footer_height=lambda: footer.height,- env=_openclaw_env(workspace),- ).run()-- return _supervise_openclaw(openclaw_bin, openclaw_args, workspace)- finally:- print_session_summary(stats)- server.close()- _remove_openclaw_workspace(workspace)---def launch_openclaw_config(- config: Path,- model: str,- openclaw_args: list[str],-) -> int:- """Run OpenClaw against a native server TOML deployment."""- catalog = [- (- model,- f"{_openclaw_model_display_name(model)} (Switchyard)",- f"Route from {config.name}.",- )- ]- return _run_openclaw_with_switchyard(- config,- display_model=model,- openclaw_args=openclaw_args,- catalog_entries=catalog,- )diff --git a/switchyard/cli/launchers/proxy_health_monitor.py b/switchyard/cli/launchers/proxy_health_monitor.pydeleted file mode 100644index b5a12933c..000000000--- a/switchyard/cli/launchers/proxy_health_monitor.py+++ /dev/null@@ -1,45 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Lightweight health indicator for launcher footers."""--import time--from switchyard.cli.launchers.launcher_runtime import _LOCAL_OPENER---class ProxyHealthMonitor:- """Periodic liveness probe for the in-process proxy.-- ``poll()`` is designed to run from a footer-render thread. It performs a- quick ``GET /health`` only when the check interval has elapsed and otherwise- returns immediately.- """-- _CHECK_INTERVAL_S = 2.0-- def __init__(self, port: int) -> None:- self._url = f"http://127.0.0.1:{port}/health"- self._healthy: bool | None = None- self._last_check: float = 0.0-- def poll(self) -> None:- """Run a health check if the check interval has elapsed."""- now = time.monotonic()- if now - self._last_check < self._CHECK_INTERVAL_S:- return- self._last_check = now- try:- # Loopback: bypass env proxies so a configured HTTP_PROXY can't- # intercept the 127.0.0.1 health probe.- with _LOCAL_OPENER.open(self._url, timeout=0.5):- self._healthy = True- except Exception:- self._healthy = False-- @property- def indicator(self) -> tuple[str, int]:- """Return ``(styled_str, visible_width)`` for the footer."""- if self._healthy is None:- return "\x1b[33m●\x1b[0m", 1- return ("\x1b[92m●\x1b[0m", 1) if self._healthy else ("\x1b[91m●\x1b[0m", 1)diff --git a/switchyard/cli/launchers/session_summary.py b/switchyard/cli/launchers/session_summary.pydeleted file mode 100644index 681ae466b..000000000--- a/switchyard/cli/launchers/session_summary.py+++ /dev/null@@ -1,84 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""End-of-session summary printed when a launcher exits."""--from __future__ import annotations--import contextlib-import logging-from collections.abc import Mapping-from typing import cast--from switchyard.cli.launchers.cost_estimator import estimate_model_cost-from switchyard.cli.launchers.stats_source import StatsSource--_RULE = "─" * 51-_LOG = logging.getLogger(__name__)---def print_session_summary(stats: StatsSource) -> None:- """Print a session summary to stdout after the launcher exits."""- try:- snapshot = stats.snapshot_sync()- summary = _format_summary(snapshot)- if summary:- with contextlib.suppress(BrokenPipeError):- print(summary)- except Exception:- _LOG.debug("Failed to print session summary", exc_info=True)---def _format_summary(snapshot: Mapping[str, object]) -> str:- """Return a formatted summary string, or empty string if no requests were made."""- total_requests = _int(snapshot, "total_requests")- if total_requests == 0:- return ""-- total_errors = _int(snapshot, "total_errors")- totals = _mapping(snapshot, "total_tokens")- prompt = _int(totals, "prompt")- completion = _int(totals, "completion")- cached = _int(totals, "cached")-- req_str = f"{total_requests:,}" + (f" ({total_errors} errors)" if total_errors else "")- tok_str = f"{prompt:,} in {completion:,} out" + (f" {cached:,} cached" if cached else "")-- lines = [- "",- _RULE,- f" requests : {req_str}",- f" tokens : {tok_str}",- ]-- models = _mapping(snapshot, "models")- if models:- lines.append(" models :")- for model_name, model_data in models.items():- md = cast(Mapping[str, object], model_data) if isinstance(model_data, Mapping) else {}- calls = _int(md, "calls")- pt = _int(md, "prompt_tokens")- ct = _int(md, "completion_tokens")- cached_t = _int(md, "cached_tokens")- cache_creation_t = _int(md, "cache_creation_tokens")- cost = estimate_model_cost(- model_name, pt, ct, cached_tokens=cached_t, cache_creation_tokens=cache_creation_t- )- short = model_name.rsplit("/", 1)[-1]- cost_str = f" ${cost['total_cost']:.4f}" if cost["total_cost"] else ""- lines.append(f" {short} {calls:,} req · {pt:,} in {ct:,} out{cost_str}")-- lines.append(_RULE)- return "\n".join(lines)---def _mapping(data: Mapping[str, object], key: str) -> Mapping[str, object]:- """Safely extract a nested mapping from snapshot data, returning {} on missing/wrong type."""- value = data.get(key)- return cast(Mapping[str, object], value) if isinstance(value, Mapping) else {}---def _int(data: Mapping[str, object], key: str) -> int:- """Safely extract an int from snapshot data, returning 0 on missing/wrong type."""- value = data.get(key)- return value if isinstance(value, int) else 0diff --git a/switchyard/cli/launchers/shell_tui.py b/switchyard/cli/launchers/shell_tui.pydeleted file mode 100644index 536902a40..000000000--- a/switchyard/cli/launchers/shell_tui.py+++ /dev/null@@ -1,419 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Embed a child process in a PTY with a live footer drawn below it.--Uses DECSTBM to confine the child's output to the upper rows and a-background thread to repaint the footer at a fixed refresh rate.--The footer function signature::-- footer_fn(cols: int) -> list[tuple[str, int]]--Each tuple is ``(styled_line, visible_width)`` — the visible width-excludes ANSI escape sequences so padding is applied correctly for-lines that contain colour codes or multi-cell emoji.-"""--from __future__ import annotations--import errno-import fcntl-import os-import pty-import select-import signal-import struct-import sys-import termios-import threading-import time-import tty-import types-from collections.abc import Callable--ESC = b"\x1b"-CSI = ESC + b"["--# Defer footer paints until the child has been silent for at least this long.-# Ink (Claude Code's renderer) emits an in-place update as a burst of small-# write() calls — cursor move, SGR colour, partial line text, clear-to-EOL,-# repeat — and between any two of those writes our non-blocking drain can hit-# BlockingIOError. If the footer paint barges in there, its leading ESC-# resets the terminal's CSI parser and the child's continuation bytes land-# naked, producing visible CSI fragments (``[3A``, ``M s``, etc.) wherever the-# tree was being redrawn. 30 ms comfortably outlasts a typical Ink burst-# (sub-10 ms locally) while keeping the footer feeling responsive between-# requests.-_FOOTER_QUIET_THRESHOLD_S = 0.030-_FOOTER_POLL_INTERVAL_S = 0.05---def _get_winsize(fd: int) -> tuple[int, int]:- data = fcntl.ioctl(fd, termios.TIOCGWINSZ, b"\x00" * 8)- rows, cols, _, _ = struct.unpack("HHHH", data)- return rows, cols---def _set_winsize(fd: int, rows: int, cols: int) -> None:- fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))---def _writeall(fd: int, data: bytes) -> None:- """Loop ``os.write`` until every byte is flushed.-- A single ``os.write`` to a tty can return fewer bytes than requested when- the kernel's tty output buffer is full; the caller is expected to retry- with the remaining slice. Without this loop, large writes (e.g. a- coalesced 100-KiB Ink frame) can be truncated, which manifests as- visibly garbled output.- """- view = memoryview(data)- while view:- n = os.write(fd, view)- view = view[n:]---class ShellTUI:- """Run a child process in a PTY with a live footer drawn below it.-- The terminal is split into two regions via DECSTBM (scroll-region):-- * rows 1 … (total - footer_height): the child process's viewport.- * rows (total - footer_height + 1) … total: redrawn by a background- thread at ``refresh_hz`` times per second.-- The child inherits a PTY that reports a reduced row count so its own- TUI doesn't overlap the footer. SIGWINCH is forwarded to the child- and triggers an immediate footer repaint.-- Parameters- ----------- command:- Argv for the child process (``[binary, *args]``).- footer_fn:- Called with the current terminal column width; returns a list of- ``(styled_line, visible_width)`` tuples, one per footer row.- footer_height:- Callable returning the number of rows reserved at the bottom of the- terminal. Called on every paint so the height can grow dynamically.- refresh_hz:- Footer repaint frequency in Hz.- env:- Optional dict of environment variable overrides merged on top of- ``os.environ`` before ``execvpe``. ``TERM`` is set to- ``xterm-256color`` if not already present.- """-- def __init__(- self,- command: list[str],- footer_fn: Callable[[int], list[tuple[str, int]]],- footer_height: Callable[[], int] = lambda: 1,- refresh_hz: float = 2.0,- env: dict[str, str] | None = None,- ) -> None:- self.command = command- self.footer_fn = footer_fn- self._footer_height_fn: Callable[[], int] = footer_height- self.refresh_interval = 1.0 / refresh_hz- self._env = env- self._out_lock = threading.Lock()- self._stop = threading.Event()- self._master_fd: int | None = None- # Monotonic time of the most recent child-output write to stdout.- # Used by ``_maybe_paint_footer`` to debounce paints away from- # the middle of Ink's multi-write frame bursts. ``-inf`` so the- # very first paint (after startup, with no traffic yet) is not- # blocked.- self._last_activity_ts: float = float("-inf")- # Monotonic time of the most recent footer paint. Throttled by- # ``refresh_interval`` so we don't repaint at the polling rate.- self._last_paint_ts: float = float("-inf")- # Set by ``_on_winch`` (the SIGWINCH handler) and drained by the main- # loop, which calls ``_handle_winch`` to perform the deferred resize- # work. The handler must do no I/O of its own: CPython delivers- # signals to the main thread between bytecodes — including bytecodes- # inside the main thread's ``with self._out_lock:`` block in- # ``_drain`` — and re-acquiring a non-reentrant lock from the same- # thread deadlocks the input-forwarding loop. Doing the work in the- # main loop sidesteps that entirely.- self._winch_pending: bool = False-- @property- def footer_height(self) -> int:- return self._footer_height_fn()-- def _write(self, data: bytes) -> None:- with self._out_lock:- _writeall(sys.stdout.fileno(), data)-- def _apply_scroll_region(self, shell_rows: int) -> None:- self._write(CSI + f"1;{shell_rows}r".encode() + CSI + b"1;1H")-- def _build_footer_bytes(self, rows: int, cols: int) -> bytes:- """Render the footer as a single escape-sequence blob (no I/O).-- Order matters:-- * ``DECSC`` first — saves the child's cursor + SGR attrs so we can- restore them at the end.- * ``DECSTBM`` second — reapplies the scroll region. The child enters- the alt screen with ``\\x1b[?1049h`` early on, and per xterm spec- alt-screen entry resets DECSTBM. Reapplying it on every footer- paint keeps the scroll region in force for the lifetime of the- session, even after alt-screen toggles. DECSTBM also moves the- cursor to home as a side effect — harmless because we explicitly- move to the footer rows next, and DECRC at the end restores the- original (saved-before-DECSTBM) position.- * Footer rows.- * ``DECRC`` last — restores the child's cursor.- """- lines = list(self.footer_fn(cols))[: self.footer_height]- while len(lines) < self.footer_height:- lines.append(("", 0))- shell_rows = max(1, rows - self.footer_height)- parts = [- ESC + b"7", # DECSC: save cursor + attrs- CSI + f"1;{shell_rows}r".encode(), # DECSTBM: keep scroll region in force- ]- for i, (line, visible) in enumerate(lines):- row = shell_rows + 1 + i- padding = max(0, cols - visible)- parts.append(CSI + f"{row};1H".encode())- parts.append(CSI + b"2K")- parts.append(line.encode("utf-8", "replace"))- if padding:- parts.append(b" " * padding)- parts.append(CSI + b"0m")- parts.append(ESC + b"8") # DECRC: restore cursor + attrs- return b"".join(parts)-- def _draw_footer(self, rows: int, cols: int) -> None:- """Paint the footer under ``_out_lock``. Called from the footer thread."""- self._write(self._build_footer_bytes(rows, cols))-- def _drain(self, master_fd: int) -> bool:- """Drain ``master_fd`` non-blocking and write the batch to stdout.-- Returns ``False`` if the child closed (EIO or EOF), else ``True``.-- The drain does NOT paint the footer. Painting between child writes- regularly lands inside an Ink frame burst — between two of the- child's small write() calls, where the next bytes would have been- the continuation of an unfinished CSI — and the paint's own ESC- resets the terminal's parser. The footer thread paints separately,- debounced on ``_FOOTER_QUIET_THRESHOLD_S`` of child silence so it- only ever falls in a gap between bursts.- """- chunks: list[bytes] = []- eof = False- while True:- try:- data = os.read(master_fd, 65536)- except BlockingIOError:- break- except OSError as e:- if e.errno == errno.EIO:- eof = True- break- raise- if not data:- eof = True- break- chunks.append(data)- if chunks:- batch = b"".join(chunks)- with self._out_lock:- _writeall(sys.stdout.fileno(), batch)- # Stamp inside the lock so the footer thread, if it- # acquires the lock next, observes a fresh timestamp on- # its inside-lock re-check and skips painting.- self._last_activity_ts = time.monotonic()- return not eof-- def _maybe_paint_footer(self) -> bool:- """Paint the footer if the child has been quiet long enough.-- Returns ``True`` iff a paint actually happened. Callable from- unit tests as a single deterministic step in place of running- the footer thread.-- The check is double-guarded: an optimistic outside-lock check- avoids paying lock contention when the child is busy, and an- inside-lock re-check handles the race where a drain wins the- lock between the optimistic check and our acquisition (in which- case it just bumped ``_last_activity_ts`` and the paint must- skip).- """- now = time.monotonic()- if (now - self._last_activity_ts) < _FOOTER_QUIET_THRESHOLD_S:- return False- if (now - self._last_paint_ts) < self.refresh_interval:- return False- with self._out_lock:- now = time.monotonic()- if (now - self._last_activity_ts) < _FOOTER_QUIET_THRESHOLD_S:- return False- try:- rows, cols = _get_winsize(sys.stdout.fileno())- except OSError:- return False- _writeall(sys.stdout.fileno(), self._build_footer_bytes(rows, cols))- self._last_paint_ts = now- return True-- def _footer_loop(self) -> None:- while not self._stop.is_set():- self._maybe_paint_footer()- self._stop.wait(_FOOTER_POLL_INTERVAL_S)-- def _on_winch(self, _signum: int, _frame: types.FrameType | None) -> None:- # Async-signal-safe: only set a flag. ``_handle_winch`` runs from the- # main loop where ``_out_lock`` is uncontended.- self._winch_pending = True-- def _handle_winch(self) -> None:- """Perform deferred resize work scheduled by ``_on_winch``.-- Runs from the main loop, never from a signal handler. Steps:-- * Re-query the outer terminal size.- * Forward the new size to the child PTY so the child receives its- own SIGWINCH and redraws — the child's redraw is what repaints- the upper region.- * Reapply DECSTBM for the new shell-rows count.- * Repaint the footer at the new geometry.- * Stamp ``_last_activity_ts`` so the footer thread's quiet-window- debounce blocks paints during the child's resize burst.-- Deliberately does NOT issue ``CSI 2J``: clearing the user's screen- on resize would wipe primary-screen content the user can scroll- back to and serves no purpose for alt-screen TUIs (the child's- own SIGWINCH-driven full redraw covers the in-region content).- """- if self._master_fd is None:- return- try:- rows, cols = _get_winsize(sys.stdout.fileno())- except OSError:- return- shell_rows = max(1, rows - self.footer_height)- try:- _set_winsize(self._master_fd, shell_rows, cols)- except OSError:- return- with self._out_lock:- _writeall(- sys.stdout.fileno(),- CSI + f"1;{shell_rows}r".encode() + CSI + b"1;1H",- )- _writeall(sys.stdout.fileno(), self._build_footer_bytes(rows, cols))- now = time.monotonic()- self._last_paint_ts = now- self._last_activity_ts = now-- def run(self) -> int:- """Start the child and block until it exits. Returns its exit code."""- if not os.isatty(sys.stdin.fileno()):- raise RuntimeError("ShellTUI requires a TTY on stdin")-- rows, cols = _get_winsize(sys.stdout.fileno())- shell_rows = max(1, rows - self.footer_height)-- pid, master_fd = pty.fork()- if pid == 0:- child_env = os.environ.copy()- child_env.setdefault("TERM", "xterm-256color")- if self._env:- child_env.update(self._env)- try:- os.execvpe(self.command[0], self.command, child_env)- except OSError as e:- sys.stderr.write(f"exec failed: {e}\n")- os._exit(127)-- self._master_fd = master_fd- _set_winsize(master_fd, shell_rows, cols)-- # Non-blocking master so ``_drain_and_paint`` can read until- # ``BlockingIOError`` and emit the whole batch + footer atomically.- fcntl.fcntl(- master_fd,- fcntl.F_SETFL,- fcntl.fcntl(master_fd, fcntl.F_GETFL) | os.O_NONBLOCK,- )-- # Disable echo + canonical mode on the PTY. Without this the line- # discipline echoes anything we forward into the child's stdin- # (``os.write(master_fd, ...)``) back through ``master_fd``'s read- # side, where we then paint it to the user's stdout. The user sees- # CSI-fragment artifacts (``[3;153R``, ``[?62;...c`` etc.) whenever- # their real terminal answers a DSR/DA query the child issued.- # Cbreak is the minimal-surgery option: clears ``ECHO`` and- # ``ICANON`` but leaves ``ISIG`` on so Ctrl-C still signals the- # child. Most TUIs (Claude Code's Ink included) reset their tty- # to raw mode shortly after exec, but during the startup window- # — and any time the terminal answers asynchronously — echo- # would otherwise leak.- try:- tty.setcbreak(master_fd)- except termios.error:- pass # best-effort — never fail launch on a quirky platform-- stdin_fd = sys.stdin.fileno()- old_termios = termios.tcgetattr(stdin_fd)- tty.setraw(stdin_fd)- old_winch = signal.signal(signal.SIGWINCH, self._on_winch)-- self._write(CSI + b"2J")- self._apply_scroll_region(shell_rows)- self._draw_footer(rows, cols)-- footer_thread = threading.Thread(target=self._footer_loop, daemon=True)- footer_thread.start()-- try:- while True:- if self._winch_pending:- self._winch_pending = False- self._handle_winch()- try:- r, _, _ = select.select([stdin_fd, master_fd], [], [], 0.1)- except (InterruptedError, OSError):- continue- if master_fd in r:- if not self._drain(master_fd):- break- if stdin_fd in r:- data = os.read(stdin_fd, 65536)- if not data:- break- os.write(master_fd, data)- try:- rpid, _ = os.waitpid(pid, os.WNOHANG)- if rpid == pid:- break- except ChildProcessError:- break- finally:- self._stop.set()- footer_thread.join(timeout=0.5)- signal.signal(signal.SIGWINCH, old_winch)- try:- self._write(CSI + b"r" + CSI + b"?25h")- rows, _ = _get_winsize(sys.stdout.fileno())- self._write(CSI + f"{rows};1H".encode() + b"\n")- except OSError:- pass- termios.tcsetattr(stdin_fd, termios.TCSADRAIN, old_termios)- try:- os.close(master_fd)- except OSError:- pass-- try:- _, status = os.waitpid(pid, 0)- return os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1- except ChildProcessError:- return 0diff --git a/switchyard/cli/launchers/stats_source.py b/switchyard/cli/launchers/stats_source.pydeleted file mode 100644index b2bcbbdc3..000000000--- a/switchyard/cli/launchers/stats_source.py+++ /dev/null@@ -1,20 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Stats snapshot interface shared by launcher presentation code."""--from __future__ import annotations--from collections.abc import Mapping-from typing import Protocol---class StatsSource(Protocol):- """Provides the current launcher-session statistics."""-- def snapshot_sync(self) -> Mapping[str, object]:- """Return the latest statistics snapshot."""- ...---__all__ = ["StatsSource"]diff --git a/switchyard/cli/switchyard_cli.py b/switchyard/cli/switchyard_cli.pydeleted file mode 100644index edacc0e65..000000000--- a/switchyard/cli/switchyard_cli.py+++ /dev/null@@ -1,84 +0,0 @@-#!/usr/bin/env python3-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Switchyard command-line entry point."""--import argparse--from switchyard import __version__-from switchyard.cli.launch_command import (- cmd_launch_claude,- cmd_launch_codex,- cmd_launch_openclaw,-)-from switchyard.cli.launchers.native_server import NativeServerConfigError---def _add_launch_parser(- subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]",-) -> None:- launch = subparsers.add_parser(- "launch",- help="Launch a coding agent through the native server",- )- launch_sub = launch.add_subparsers(dest="launch_target", help="Agent to launch")- launcher_parsers = (- ("claude", "Launch Claude Code", "claude_args", cmd_launch_claude),- ("codex", "Launch Codex CLI", "codex_args", cmd_launch_codex),- ("openclaw", "Launch OpenClaw", "openclaw_args", cmd_launch_openclaw),- )- for name, help_text, args_dest, command in launcher_parsers:- agent = launch_sub.add_parser(name, help=help_text)- agent.add_argument("--model", required=True, help="Route ID from the deployment.")- agent.add_argument(- "--config",- metavar="PATH",- help="TOML deployment (default: packaged OpenRouter deployment).",- )- agent.add_argument(- args_dest,- nargs=argparse.REMAINDER,- help="Arguments forwarded to the coding agent after --.",- )- agent.set_defaults(func=command)-- def _launch_help(args: argparse.Namespace) -> None: # noqa: ARG001- launch.print_help()- raise SystemExit(1)-- launch.set_defaults(func=_launch_help)---def _build_parser() -> argparse.ArgumentParser:- parser = argparse.ArgumentParser(- prog="switchyard",- description="Switchyard LLM proxy",- )- parser.add_argument(- "--version",- action="version",- version=f"%(prog)s {__version__}",- )- subparsers = parser.add_subparsers(dest="command")-- _add_launch_parser(subparsers)- return parser---def main() -> None:- """Run the Switchyard CLI."""-- parser = _build_parser()- args = parser.parse_args()- if not hasattr(args, "func"):- parser.print_help()- raise SystemExit(1)- try:- args.func(args)- except NativeServerConfigError as exc:- parser.exit(1, f"error: {exc}\n")---if __name__ == "__main__":- main()diff --git a/tests/getting_started/test_getting_started.py b/tests/getting_started/test_getting_started.pyindex e053a9dc2..1b8fe89f5 100644--- a/tests/getting_started/test_getting_started.py+++ b/tests/getting_started/test_getting_started.py@@ -11,9 +11,9 @@ def test_getting_started_documents_current_paths() -> None:Path(__file__).resolve().parents[2] / "docs" / "getting_started.md").read_text()- assert guide.index("## Launcher Path") < guide.index("## Server Path")- assert 'uv tool install --python 3.10 "nemo-switchyard[cli]"' in guide- assert "switchyard launch claude --model switchyard" in guide+ assert guide.index("## Server Path") < guide.index("## Library Path")+ assert "switchyard launch" not in guide+ assert "nemo-switchyard[cli]" not in guideassert "cargo install --locked switchyard-server" in guideassert "switchyard-server --config routes.toml --dry-run" in guide@@ -21,6 +21,7 @@ def test_getting_started_documents_current_paths() -> None:"switchyard configure","switchyard serve","switchyard verify",+ "switchyard launch","--routing-profiles","routes.yaml",):diff --git a/tests/readme/test_readme.py b/tests/readme/test_readme.pydeleted file mode 100644index ee9561ce3..000000000--- a/tests/readme/test_readme.py+++ /dev/null@@ -1,27 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Drift checks for the repository README."""--from pathlib import Path---def test_readme_documents_current_paths() -> None:- readme = (Path(__file__).resolve().parents[2] / "README.md").read_text()-- assert readme.index("### Launcher Path") < readme.index("### Server Path")- assert 'uv tool install --python 3.10 "nemo-switchyard[cli]"' in readme- assert "switchyard launch claude --model switchyard" in readme- assert "cargo install --locked switchyard-server" in readme- assert "switchyard-server --config routes.toml --dry-run" in readme-- for legacy_command in (- "switchyard configure",- "switchyard serve",- "switchyard verify",- ):- assert legacy_command not in readme---# TODO: Add Python snippet coverage when the supported Rust-backed API is finalized.-# TODO: Add TOML schema coverage if the README includes a complete server config.diff --git a/tests/test_cli_reference_docs.py b/tests/test_cli_reference_docs.pyindex 857e3eb99..fc87031e8 100644--- a/tests/test_cli_reference_docs.py+++ b/tests/test_cli_reference_docs.py@@ -1,70 +1,14 @@# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0-"""CLI reference drift tests."""+"""Server CLI reference drift tests."""-import argparseimport subprocessfrom pathlib import Path-from switchyard.cli.switchyard_cli import _build_parser-CLI_REFERENCE = Path(__file__).resolve().parents[1] / "docs" / "cli_reference.md"-def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:- action = next(- action- for action in parser._actions- if isinstance(action, argparse._SubParsersAction)- )- return action.choices # type: ignore[return-value]---def _long_options(parser: argparse.ArgumentParser) -> set[str]:- return {- option- for action in parser._actions- for option in action.option_strings- if option.startswith("--") and option != "--help"- }---def test_reference_documents_launcher_before_server() -> None:- text = CLI_REFERENCE.read_text()- launcher = text.index("## Launcher Path: `switchyard launch`")- server = text.index("## Server Path: `switchyard-server`")- removed = text.index("## Removed Setup Commands")- related = text.index("## Related Documentation")-- assert launcher < server < removed < related---def test_reference_marks_removed_setup_commands() -> None:- text = CLI_REFERENCE.read_text()- removed_start = text.index("## Removed Setup Commands")- related_start = text.index("## Related Documentation", removed_start)- removed = text[removed_start:related_start]- commands = _subparsers(_build_parser())-- assert (- "`switchyard configure`, `switchyard serve`, and `switchyard verify` are not"- in removed- )- assert "api_key_env" in removed- assert "The CLI does not save provider credentials, deployment paths" in removed- assert {"configure", "serve", "verify"}.isdisjoint(commands)---def test_reference_lists_launcher_contract() -> None:- launch = _subparsers(_build_parser())["launch"]- text = CLI_REFERENCE.read_text()- for parser in _subparsers(launch).values():- assert _long_options(parser) == {"--model", "--config"}- assert "--model" in text- assert "--config" in text--def test_reference_lists_server_contract() -> None:result = subprocess.run([diff --git a/tests/test_cli_version.py b/tests/test_cli_version.pydeleted file mode 100644index 44bde1c43..000000000--- a/tests/test_cli_version.py+++ /dev/null@@ -1,19 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Tests for the top-level ``switchyard --version`` flag."""--import pytest--from switchyard import __version__-from switchyard.cli.switchyard_cli import _build_parser---def test_version_flag_prints_version_and_exits(capsys: pytest.CaptureFixture[str]) -> None:- parser = _build_parser()-- with pytest.raises(SystemExit) as exc:- parser.parse_args(["--version"])-- assert exc.value.code == 0- assert capsys.readouterr().out.strip() == f"switchyard {__version__}"diff --git a/tests/test_cost_estimator_gemini.py b/tests/test_cost_estimator_gemini.pydeleted file mode 100644index 4407b8535..000000000--- a/tests/test_cost_estimator_gemini.py+++ /dev/null@@ -1,44 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Pricing for the default LLM-classifier model (Gemini 3.5 Flash).--Guards the ``cost_estimator`` entry so a typo or accidental removal —-which silently zeroes the default classifier's cost in routing-stats —-fails loudly instead.-"""--from __future__ import annotations--from switchyard.cli.launchers.cost_estimator import MODEL_PRICING, estimate_cost--_GEMINI_KEYS = (- "gcp/google/gemini-3.5-flash",- "openai/gcp/google/gemini-3.5-flash",- "gemini-3.5-flash",-)---def test_gemini_flash_keys_registered_with_global_list_price() -> None:- for key in _GEMINI_KEYS:- price = MODEL_PRICING[key]- # Google Vertex global list price (ai.google.dev), USD / 1M tokens.- assert price.input == 1.50- assert price.output == 9.00- assert price.cached == 0.15 # 90% off input- assert price.cache_write == price.input # no per-token write premium---def test_gemini_flash_estimate_includes_cache_discount() -> None:- # prompt_tokens is the TOTAL input (cached is a subset): 2M total with- # 1M cached => 1M fresh + 1M cached, plus 1M output.- result = estimate_cost({- "gcp/google/gemini-3.5-flash": {- "prompt_tokens": 2_000_000,- "cached_tokens": 1_000_000,- "completion_tokens": 1_000_000,- },- })- model = result["models"]["gcp/google/gemini-3.5-flash"]- # 1.50 (fresh in) + 0.15 (cached in) + 9.00 (out) = 10.65- assert model["total_cost"] == 10.65diff --git a/tests/test_launcher_proxy_bypass.py b/tests/test_launcher_proxy_bypass.pydeleted file mode 100644index bb553ee82..000000000--- a/tests/test_launcher_proxy_bypass.py+++ /dev/null@@ -1,39 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Loopback readiness probes must ignore env proxies (HTTP_PROXY/NO_PROXY)."""--import threading-from http.server import BaseHTTPRequestHandler, HTTPServer--from switchyard.cli.launchers.launcher_runtime import wait_for_proxy_ready---class _HealthHandler(BaseHTTPRequestHandler):- def do_GET(self) -> None:- self.send_response(200)- self.end_headers()-- def log_message(self, format: str, *args: object) -> None: # noqa: A002- pass---def test_wait_for_proxy_ready_bypasses_env_proxy(monkeypatch):- """A configured HTTP_PROXY must not intercept the 127.0.0.1 health probe."""- server = HTTPServer(("127.0.0.1", 0), _HealthHandler)- port = server.server_address[1]- thread = threading.Thread(target=server.serve_forever, daemon=True)- thread.start()-- # Point env proxy at a dead port and remove any NO_PROXY exemption; before- # the fix the loopback probe would route here and fail.- monkeypatch.setenv("HTTP_PROXY", "http://127.0.0.1:9")- monkeypatch.setenv("http_proxy", "http://127.0.0.1:9")- monkeypatch.delenv("NO_PROXY", raising=False)- monkeypatch.delenv("no_proxy", raising=False)-- try:- assert wait_for_proxy_ready(port, timeout_s=2) is True- finally:- server.shutdown()- server.server_close()diff --git a/tests/test_launchers.py b/tests/test_launchers.pydeleted file mode 100644index 4f2c9a995..000000000--- a/tests/test_launchers.py+++ /dev/null@@ -1,152 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Contract tests for the minimal coding-agent launcher surface."""--import argparse-from pathlib import Path--import pytest--from switchyard.cli.command_utils import strip_forwarded_args-from switchyard.cli.launch_command import _config_path-from switchyard.cli.launchers.claude_code_launcher import _claude_env-from switchyard.cli.launchers.codex_cli_launcher import _codex_env, _provider_overrides-from switchyard.cli.launchers.native_server import NativeServer-from switchyard.cli.launchers.openclaw_launcher import _openclaw_command-from switchyard.cli.switchyard_cli import _build_parser---def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:- action = next(- action- for action in parser._actions- if isinstance(action, argparse._SubParsersAction)- )- return action.choices # type: ignore[return-value]---def test_cli_exposes_only_launch() -> None:- assert set(_subparsers(_build_parser())) == {"launch"}--[email protected]("agent", ["claude", "codex", "openclaw"])-def test_launcher_surface_is_model_config_and_forwarded_args(agent: str) -> None:- launch = _subparsers(_build_parser())["launch"]- parser = _subparsers(launch)[agent]- options = {- option- for action in parser._actions- for option in action.option_strings- if option != "--help"- }- assert options == {"-h", "--model", "--config"}-- args = parser.parse_args(["--model", "switchyard", "--", "--version"])- assert args.model == "switchyard"- assert args.config is None- assert vars(args)[f"{agent}_args"] == ["--", "--version"]--- ("agent_args", "expected"),- [- ([], ["openclaw", "chat"]),- (["--", "--version"], ["openclaw", "--version"]),- (["--", "chat", "--help"], ["openclaw", "chat", "--help"]),- ],-)-def test_openclaw_uses_forwarded_args_as_the_complete_argument_list(- agent_args: list[str],- expected: list[str],-) -> None:- launch = _subparsers(_build_parser())["launch"]- parser = _subparsers(launch)["openclaw"]- args = parser.parse_args(["--model", "switchyard", *agent_args])-- command = _openclaw_command("openclaw", strip_forwarded_args(args.openclaw_args))-- assert command == expected---def test_default_config_is_packaged_openrouter_deployment() -> None:- config = _config_path(None)- assert config.name == "openrouter.toml"- assert "OPENROUTER_API_KEY" in config.read_text()---def test_claude_env_preserves_small_fast_model_override(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setenv("ANTHROPIC_SMALL_FAST_MODEL", "background-route")-- env = _claude_env(4321, "agent-route")-- assert env["ANTHROPIC_MODEL"] == "agent-route"- assert env["ANTHROPIC_SMALL_FAST_MODEL"] == "background-route"---def test_forward_auth_does_not_replace_the_agent_login(- monkeypatch: pytest.MonkeyPatch,-) -> None:- monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "inherited-claude-token")- monkeypatch.setenv("OPENAI_API_KEY", "inherited-openai-key")-- claude_auth = _claude_env(4321, "agent-route", use_anthropic_auth=True)- claude_local = _claude_env(4321, "agent-route")- codex_auth = _codex_env(use_openai_auth=True)- codex_local = _codex_env()- codex_auth_config = " ".join(_provider_overrides(4321, use_openai_auth=True))-- assert "ANTHROPIC_AUTH_TOKEN" not in claude_auth- assert claude_local["ANTHROPIC_AUTH_TOKEN"] == "switchyard"- assert codex_auth["OPENAI_API_KEY"] == "inherited-openai-key"- assert codex_local["OPENAI_API_KEY"] == "switchyard"- assert "requires_openai_auth=true" in codex_auth_config- assert "env_key" not in codex_auth_config---def test_native_server_passes_config_directly_to_binding(- monkeypatch: pytest.MonkeyPatch,- tmp_path: Path,-) -> None:- config = tmp_path / "routes.toml"- config.write_text("schema_version = 1\n")- captured: dict[str, object] = {}-- class FakeServer:- port = 4321- base_url = "http://127.0.0.1:4321"-- def __init__(self, path: Path, port: int) -> None:- captured["path"] = path- captured["port"] = port-- def close(self) -> None:- captured["closed"] = True-- def caller_auth_kind(self, model: str) -> str | None:- captured["model"] = model- return "anthropic"-- import switchyard_rust.server-- monkeypatch.setattr(switchyard_rust.server, "Server", FakeServer)- server = NativeServer(config)- assert server.caller_auth_kind("switchyard/route") == "anthropic"- server.close()-- assert captured == {- "path": config,- "port": 0,- "model": "switchyard/route",- "closed": True,- }- assert server.port == 4321- assert config.exists()---def test_missing_explicit_config_is_a_cli_error(tmp_path: Path) -> None:- missing = tmp_path / "missing.toml"- with pytest.raises(SystemExit, match="config file not found"):- _config_path(str(missing))diff --git a/tests/test_live_stats_footer.py b/tests/test_live_stats_footer.pydeleted file mode 100644index d28e74377..000000000--- a/tests/test_live_stats_footer.py+++ /dev/null@@ -1,155 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Tests for the unified ``LiveStatsFooter``.--One layout for every routing strategy: an aggregate row + one indented row-per active outbound model tier.-"""--from __future__ import annotations--from collections.abc import Mapping--from switchyard.cli.launchers.live_stats_footer import FOOTER_ROWS, LiveStatsFooter---def _strip_ansi(text: str) -> str:- out: list[str] = []- i = 0- while i < len(text):- if text[i] == "\x1b" and i + 1 < len(text) and text[i + 1] == "[":- j = i + 2- while j < len(text) and not text[j].isalpha():- j += 1- i = j + 1- else:- out.append(text[i])- i += 1- return "".join(out)---class _StubHealth:- def poll(self) -> None:- return None-- @property- def indicator(self) -> tuple[str, int]:- return ("●", 1)---class _Stats:- def __init__(self, snapshot: Mapping[str, object] | None = None) -> None:- self.snapshot = snapshot or {- "total_requests": 0,- "total_errors": 0,- "total_tokens": {},- "models": {},- }-- def snapshot_sync(self) -> Mapping[str, object]:- return self.snapshot---def _stats_with_model_call(- model: str,- *,- prompt: int = 1234,- completion: int = 567,- cached: int = 200,-) -> _Stats:- return _Stats({- "total_requests": 1,- "total_errors": 0,- "total_tokens": {- "prompt": prompt,- "completion": completion,- "cached": cached,- },- "models": {- model: {- "calls": 1,- "errors": 0,- "prompt_tokens": prompt,- "completion_tokens": completion,- "cached_tokens": cached,- }- },- })---def _footer(stats: _Stats, *, model: str = "nvidia/some/default") -> LiveStatsFooter:- return LiveStatsFooter(stats, model=model, health=_StubHealth()) # type: ignore[arg-type]---def test_footer_height_at_zero_traffic() -> None:- """Before any traffic: aggregate + 1 fallback row = 2 rows."""- footer = _footer(_Stats())- assert footer.height == FOOTER_ROWS == 2- rows = footer.render(cols=80)- assert len(rows) == 2---def test_aggregate_row_shows_totals_without_model_name() -> None:- stats = _stats_with_model_call("vendor/some-model")- rows = _footer(stats).render(cols=80)- agg = _strip_ansi(rows[0][0])- assert "switchyard" in agg- assert "1 req" in agg- assert "1,234 in" in agg- assert "567 out" in agg- # The aggregate row never names a model — that's the active row's job.- assert "some-model" not in agg---def test_active_row_shows_model_with_recent_traffic() -> None:- stats = _stats_with_model_call("vendor/winner-model")- rows = _footer(stats).render(cols=80)- active = _strip_ansi(rows[1][0])- assert "winner-model" in active- assert "1 req" in active- assert "1,234 in" in active- assert "567 out" in active- assert "200 cached" in active---def test_active_row_falls_back_to_default_when_no_traffic() -> None:- """Before any backend call lands, the row labels with the launch default."""- rows = _footer(_Stats(), model="vendor/launch-default").render(cols=80)- active = _strip_ansi(rows[1][0])- assert "launch-default" in active- assert "0 req" in active---def test_new_tier_adds_a_row_on_next_render() -> None:- """A new model in traffic adds a row; height grows from 2 to 3."""- stats = _stats_with_model_call("vendor/first", prompt=10, completion=20, cached=0)- footer = _footer(stats)- rows = footer.render(cols=80)- assert len(rows) == 2- assert footer.height == 2- assert "first" in _strip_ansi(rows[1][0])-- stats.snapshot = {- "total_requests": 2,- "total_errors": 0,- "total_tokens": {"prompt": 40, "completion": 60, "cached": 0},- "models": {- "vendor/first": {- "calls": 1,- "prompt_tokens": 10,- "completion_tokens": 20,- },- "vendor/second": {- "calls": 1,- "prompt_tokens": 30,- "completion_tokens": 40,- },- },- }- rows = footer.render(cols=80)- assert len(rows) == 3- assert footer.height == 3- tier_texts = " ".join(_strip_ansi(r[0]) for r in rows[1:])- assert "first" in tier_texts- assert "second" in tier_textsdiff --git a/tests/test_session_summary.py b/tests/test_session_summary.pydeleted file mode 100644index 1523b1367..000000000--- a/tests/test_session_summary.py+++ /dev/null@@ -1,115 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Unit tests for session_summary._format_summary."""--from switchyard.cli.launchers.session_summary import _format_summary---def _snapshot(- total_requests: int = 0,- total_errors: int = 0,- prompt: int = 0,- completion: int = 0,- cached: int = 0,- models: dict | None = None,-) -> dict:- return {- "total_requests": total_requests,- "total_errors": total_errors,- "total_tokens": {"prompt": prompt, "completion": completion, "cached": cached},- "models": models or {},- }---def test_empty_snapshot_returns_empty_string():- assert _format_summary(_snapshot()) == ""---def test_summary_shows_request_and_token_counts():- snap = _snapshot(total_requests=5, prompt=1000, completion=200)- out = _format_summary(snap)- assert "5" in out- assert "1,000" in out- assert "200" in out---def test_summary_shows_errors_when_present():- snap = _snapshot(total_requests=3, total_errors=1, prompt=100, completion=50)- out = _format_summary(snap)- assert "1 error" in out---def test_summary_omits_errors_when_zero():- snap = _snapshot(total_requests=3, prompt=100, completion=50)- out = _format_summary(snap)- assert "error" not in out---def test_summary_shows_cached_tokens_when_nonzero():- snap = _snapshot(total_requests=1, prompt=500, completion=100, cached=200)- out = _format_summary(snap)- assert "200" in out- assert "cached" in out---def test_summary_omits_cached_line_when_zero():- snap = _snapshot(total_requests=1, prompt=500, completion=100, cached=0)- out = _format_summary(snap)- assert "cached" not in out---def test_summary_shows_per_model_row():- snap = _snapshot(- total_requests=2,- prompt=800,- completion=300,- models={- "nvidia/some-provider/my-model": {- "calls": 2,- "prompt_tokens": 800,- "completion_tokens": 300,- "cached_tokens": 0,- }- },- )- out = _format_summary(snap)- assert "my-model" in out- assert "2 req" in out---def test_summary_shows_cost_for_known_model():- snap = _snapshot(- total_requests=1,- prompt=1_000_000,- completion=1_000_000,- models={- "openai/openai/gpt-5.2": {- "calls": 1,- "prompt_tokens": 1_000_000,- "completion_tokens": 1_000_000,- "cached_tokens": 0,- }- },- )- out = _format_summary(snap)- # gpt-5.2: $1.75 input + $14.00 output = $15.75 per 1M tokens each- assert "$15.75" in out---def test_summary_omits_cost_for_unknown_model():- snap = _snapshot(- total_requests=1,- prompt=100,- completion=50,- models={- "unknown-provider/unknown-model": {- "calls": 1,- "prompt_tokens": 100,- "completion_tokens": 50,- "cached_tokens": 0,- }- },- )- out = _format_summary(snap)- assert "$" not in outdiff --git a/tests/test_shell_tui.py b/tests/test_shell_tui.pydeleted file mode 100644index 6904e5f9e..000000000--- a/tests/test_shell_tui.py+++ /dev/null@@ -1,546 +0,0 @@-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-# SPDX-License-Identifier: Apache-2.0--"""Tests for ``ShellTUI`` drain + debounced footer painting + resize handling.--The visible failure mode these tests guard against: Claude Code's Ink-renderer emits each in-place update as a burst of small ``write()`` calls-— cursor move, SGR colour, partial line text, clear-to-EOL, repeat — and-between any two of those the kernel buffer can be empty. If we paint the-footer in that gap, our paint's leading ESC resets the terminal's CSI-parser and the child's continuation bytes (``[3A``, ``M s``, parameter-digits, …) render naked as visible text. The fix is to debounce footer-paints away from active write bursts.--These tests pin three contracts:--* ``_drain`` writes child bytes only; it does NOT inline the footer- (which would put the paint in the worst possible place — right after- whatever fragmentary tail the child happened to have flushed).-* ``_maybe_paint_footer`` skips while the child has written within- ``_FOOTER_QUIET_THRESHOLD_S`` and paints only after the burst settles.-* ``_on_winch`` does no I/O — it only sets a pending flag, so the main- thread cannot deadlock against itself by re-acquiring ``_out_lock``- in a signal handler. ``_handle_winch`` performs the deferred resize- work from the main loop, where the lock is uncontended.-"""--from __future__ import annotations--import fcntl-import os-import pty-import signal-import struct-import sys-import termios-import tty--import pytest--from switchyard.cli.launchers.shell_tui import CSI, ShellTUI---def _make_tui(- footer_lines: list[tuple[str, int]] | None = None,- footer_height: int = 1,-) -> ShellTUI:- _h = footer_height- return ShellTUI(- command=["true"],- footer_fn=lambda _cols: footer_lines or [("FOOTER-MARKER", len("FOOTER-MARKER"))],- footer_height=lambda: _h,- )---def fixed_winsize(monkeypatch: pytest.MonkeyPatch) -> None:- monkeypatch.setattr(- "switchyard.cli.launchers.shell_tui._get_winsize",- lambda _fd: (24, 80),- )---def test_build_footer_bytes_reapplies_decstbm_after_decsc() -> None:- """Footer paint must save cursor BEFORE reapplying the scroll region.-- The child enters the alt screen with ``\\x1b[?1049h``, which (per xterm- spec) resets DECSTBM. Reapplying ``CSI 1;<shell_rows> r`` on every- paint keeps the scroll region in force so the child's natural scroll- can't clobber the footer area. DECSC must come first because DECSTBM- moves the cursor to home as a side effect; if DECSC ran second it- would save (1,1) and DECRC would drop the child's cursor there.- """- tui = _make_tui(footer_lines=[("X", 1)], footer_height=2)- blob = tui._build_footer_bytes(rows=30, cols=80)-- decsc = b"\x1b7"- decrc = b"\x1b8"- decstbm = b"\x1b[1;28r" # 30 rows total - 2 footer rows = 28 shell rows-- assert decsc in blob- assert decstbm in blob- assert decrc in blob- assert blob.index(decsc) < blob.index(decstbm), (- "DECSC must precede DECSTBM so the child's cursor is saved before "- "DECSTBM's home-cursor side effect clobbers it"- )- assert blob.endswith(decrc), "DECRC must be the last byte sequence"--[email protected]("fixed_winsize")-def test_drain_writes_payload_only_no_footer(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """``_drain`` must NOT inline the footer.-- Inlining the footer right after the child's bytes is exactly the failure- mode the debounce design is meant to avoid: the child's last burst can- end mid-CSI (kernel buffer happens to be empty between two of Ink's- short ``write()`` calls), and a footer paint emitted "right after" lands- on top of an unfinished sequence whose continuation the terminal then- renders naked. Drain emits child bytes only; ``_maybe_paint_footer``- decides separately when the moment is safe.- """- master_fd, slave_fd = pty.openpty()- tty.setraw(slave_fd, when=termios.TCSANOW)-- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)-- payload = b"FRAME-CONTENT-" * 64- os.write(slave_fd, payload)-- write_calls: list[bytes] = []- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- write_calls.append(bytes(data))- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)- try:- tui = _make_tui()- result = tui._drain(master_fd)- finally:- monkeypatch.setattr(os, "write", real_write)- os.close(slave_fd)- os.close(master_fd)-- assert result is True, "slave still open at drain time → must not signal EOF"-- stream = b"".join(write_calls)- assert stream == payload, (- "drain must write the child payload verbatim — nothing else, "- "and in particular no footer escape sequences"- )- assert b"FOOTER-MARKER" not in stream, (- "drain must not inline the footer; if it does, it lands inside Ink "- "frame bursts and breaks the child's escape sequences"- )--[email protected]("fixed_winsize")-def test_drain_returns_false_on_child_eof(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """Closed slave → master read raises EIO (Linux) or returns b'' (BSD); both → False."""- master_fd, slave_fd = pty.openpty()- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)- os.close(slave_fd)-- real_write = os.write- stdout_fd = sys.stdout.fileno()- leaked: list[bytes] = []-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- leaked.append(bytes(data))- return len(data)- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)- try:- tui = _make_tui()- result = tui._drain(master_fd)- finally:- monkeypatch.setattr(os, "write", real_write)- try:- os.close(master_fd)- except OSError:- pass-- assert result is False, "EOF on master must signal child-closed → caller breaks"- assert leaked == [], "no chunks read → no stdout writes"--[email protected]("fixed_winsize")-def test_drain_coalesces_back_to_back_writes(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """Two slave writes still produce ONE coalesced stdout write."""- master_fd, slave_fd = pty.openpty()- tty.setraw(slave_fd, when=termios.TCSANOW)- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)-- chunk_a = b"A" * 256- chunk_b = b"B" * 256- os.write(slave_fd, chunk_a)- os.write(slave_fd, chunk_b)-- write_calls: list[bytes] = []- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- write_calls.append(bytes(data))- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)- try:- tui = _make_tui()- tui._drain(master_fd)- finally:- monkeypatch.setattr(os, "write", real_write)- os.close(slave_fd)- os.close(master_fd)-- assert len(write_calls) == 1, (- f"two slave writes must coalesce into one stdout write; "- f"got {len(write_calls)}"- )- assert write_calls[0] == chunk_a + chunk_b--[email protected]("fixed_winsize")-def test_maybe_paint_footer_skips_when_child_recently_active(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """Within the quiet window, the footer must not paint.-- The bug reproduced by the screenshot was the footer painting in the- middle of an Ink burst. This test pins the inverse: when the child has- written within ``_FOOTER_QUIET_THRESHOLD_S`` (simulated by stamping- ``_last_activity_ts`` to right now), ``_maybe_paint_footer`` must- return ``False`` and emit nothing.- """- import time as _time-- write_calls: list[bytes] = []- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- write_calls.append(bytes(data))- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)-- tui = _make_tui()- tui._last_activity_ts = _time.monotonic() # child wrote "right now"-- painted = tui._maybe_paint_footer()-- monkeypatch.setattr(os, "write", real_write)-- assert painted is False, (- "footer must defer while the child is still in an active write burst"- )- assert write_calls == [], "no stdout writes during the quiet window"--[email protected]("fixed_winsize")-def test_maybe_paint_footer_paints_after_quiet_window(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """Once the quiet window has elapsed, the footer paints.-- Stamping ``_last_activity_ts`` in the far past (and ``_last_paint_ts``- likewise so the rate-limit isn't what blocks the paint) simulates "the- child has been silent long enough — safe to paint". Asserts a single- stdout write whose contents are the footer blob (DECSC … DECRC,- DECSTBM reapply, marker text).- """- write_calls: list[bytes] = []- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- write_calls.append(bytes(data))- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)-- tui = _make_tui()- # _last_activity_ts and _last_paint_ts default to -inf, so the first- # _maybe_paint_footer call satisfies both gates without further setup.- painted = tui._maybe_paint_footer()-- monkeypatch.setattr(os, "write", real_write)-- assert painted is True, "quiet window elapsed → paint must happen"- assert len(write_calls) == 1- blob = write_calls[0]- assert blob.startswith(b"\x1b7"), "DECSC opens the paint"- assert blob.endswith(b"\x1b8"), "DECRC closes the paint"- assert b"\x1b[1;23r" in blob, "DECSTBM reapply (24 rows - 1 footer = 23)"- assert b"FOOTER-MARKER" in blob---def test_on_winch_only_sets_pending_flag_does_no_io(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """SIGWINCH handler must do no I/O — just flip ``_winch_pending``.-- CPython delivers signals to the main thread between bytecodes, including- bytecodes inside the main thread's ``with self._out_lock:`` block in- ``_drain``. If the handler tries to re-acquire ``_out_lock`` (non-reentrant)- or do any blocking I/O, the main thread deadlocks against itself —- freezing the input-forwarding loop. That's the "stops accepting input"- half of the deadlock.-- The handler's only allowed effect is setting ``_winch_pending``. The- deferred work happens from the main loop in ``_handle_winch``, where- the lock is uncontended.- """- tui = _make_tui()- tui._master_fd = 999 # non-None so the handler doesn't early-return on no-pty-- write_calls: list[tuple[int, bytes]] = []- real_write = os.write-- def tracking_write(fd: int, data: bytes) -> int:- write_calls.append((fd, bytes(data)))- return real_write(fd, data)-- ioctl_calls: list[int] = []-- def tracking_ioctl(fd: int, *_args: object, **_kwargs: object) -> bytes:- # The handler must not reach this — record and return a- # zero-filled winsize struct in case it does, so the test- # fails on the count assertion rather than on a kernel error.- ioctl_calls.append(fd)- return b"\x00" * 8-- monkeypatch.setattr(os, "write", tracking_write)- monkeypatch.setattr(fcntl, "ioctl", tracking_ioctl)-- assert tui._winch_pending is False- tui._on_winch(signal.SIGWINCH, None)-- assert tui._winch_pending is True, "handler must mark a resize as pending"- assert write_calls == [], (- "SIGWINCH handler must not write to any fd — that would risk grabbing "- "_out_lock from the same thread that already holds it inside _drain"- )- assert ioctl_calls == [], (- "SIGWINCH handler must not issue ioctls — defer ALL I/O to _handle_winch"- )---def test_handle_winch_propagates_size_and_repaints(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """``_handle_winch`` does the deferred resize work the signal handler used to do.-- Required steps:-- * Re-query the outer terminal size.- * Forward the new size to the child PTY (``TIOCSWINSZ`` on master_fd) so- the child receives its own SIGWINCH and redraws the upper region itself.- * Reapply DECSTBM for the new shell-rows count.- * Repaint the footer.-- Test uses a real PTY pair so the ``TIOCSWINSZ`` ioctl on the master fd- actually succeeds.-- Deliberately does NOT issue ``CSI 2J``: clearing the user's screen on- resize would wipe primary-screen content visible in scrollback. The- child's own SIGWINCH redraw repaints the in-region content.- """- master_fd, slave_fd = pty.openpty()- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)-- monkeypatch.setattr(- "switchyard.cli.launchers.shell_tui._get_winsize",- lambda _fd: (40, 100),- )-- write_calls: list[bytes] = []- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def tracking_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- write_calls.append(bytes(data))- return len(data)- return real_write(fd, data)-- monkeypatch.setattr(os, "write", tracking_write)-- try:- tui = _make_tui(footer_height=1)- tui._master_fd = master_fd- tui._winch_pending = True-- tui._handle_winch()-- # Master winsize must be propagated. shell_rows = 40 - 1 footer = 39.- ws = fcntl.ioctl(master_fd, termios.TIOCGWINSZ, b"\x00" * 8)- rows, cols, _, _ = struct.unpack("HHHH", ws)- assert rows == 39, f"child PTY rows = total - footer_height; got {rows}"- assert cols == 100, f"child PTY cols = outer cols; got {cols}"- finally:- monkeypatch.setattr(os, "write", real_write)- os.close(slave_fd)- os.close(master_fd)-- stream = b"".join(write_calls)- assert CSI + b"2J" not in stream, (- "must NOT clear the screen — that would wipe primary-screen content "- "the user could otherwise scroll back to. The child's own SIGWINCH "- "redraw covers the in-region content."- )- assert CSI + b"1;39r" in stream, (- "must reapply DECSTBM for the new shell-rows count (40 - 1 footer = 39)"- )- assert b"FOOTER-MARKER" in stream, "footer must be repainted at the new geometry"---def test_handle_winch_bumps_activity_ts_to_block_footer_thread_barge(- monkeypatch: pytest.MonkeyPatch,-) -> None:- """After a resize, the footer thread must not paint until the child redraws.-- The child gets its own SIGWINCH (via ``TIOCSWINSZ`` on the master) and- will emit a redraw burst over the next several ms. If the footer thread's- next poll lands in the middle of that burst — which is overwhelmingly- likely for a 50 ms poll interval — its paint resets the terminal's CSI- parser mid-frame and produces the visible-fragments corruption the- existing ``_FOOTER_QUIET_THRESHOLD_S`` design exists to prevent.-- ``_handle_winch`` must therefore stamp ``_last_activity_ts`` to "now" so- the footer thread's debounce defers paints for at least the quiet window.- """- import time as _time-- master_fd, slave_fd = pty.openpty()- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)-- monkeypatch.setattr(- "switchyard.cli.launchers.shell_tui._get_winsize",- lambda _fd: (24, 80),- )-- real_write = os.write- stdout_fd = sys.stdout.fileno()-- def swallow_write(fd: int, data: bytes) -> int:- if fd == stdout_fd:- return len(data)- return real_write(fd, data)-- monkeypatch.setattr(os, "write", swallow_write)-- try:- tui = _make_tui()- tui._master_fd = master_fd- tui._last_activity_ts = float("-inf")-- before = _time.monotonic()- tui._handle_winch()- after = _time.monotonic()- finally:- monkeypatch.setattr(os, "write", real_write)- os.close(slave_fd)- os.close(master_fd)-- assert before <= tui._last_activity_ts <= after, (- "_handle_winch must stamp _last_activity_ts to 'now' so the footer "- "thread's quiet-window debounce blocks paints during the child's "- "post-resize redraw burst"- )---def test_pty_echo_path_does_not_round_trip_after_cbreak() -> None:- """``tty.setcbreak`` on the master fd must turn off echo on the PTY.-- Reproduces the leak that produced ``[3;153R``-style fragments on the- user's screen: when the user's terminal answers a DSR/DA query the- child issued, the response arrives via stdin; the launcher forwards- it to the child by writing into ``master_fd``; with the line discipline- in default (echo + canonical) mode that write would be echoed back to- the master's read side and re-emitted on stdout.-- Test setup mirrors what ``run()`` does after ``pty.fork``:-- * Open a PTY, drain any startup boilerplate.- * Take a baseline by writing into the master with default modes and- reading what comes back — the kernel echoes it (proves the failure- mode is real and our test setup observes it).- * Apply ``tty.setcbreak(master_fd)`` and verify a fresh write produces- *no* echoed bytes within a short window.-- The baseline write also sanity-checks that we'd otherwise see the leak,- so a regression that made cbreak a no-op (e.g. wrong fd, swallowed- error) would fail this test rather than silently passing.- """- master_fd, slave_fd = pty.openpty()- try:- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)-- # Drain whatever junk the kernel may have buffered on open.- try:- os.read(master_fd, 65536)- except BlockingIOError:- pass-- # Baseline: default mode echoes our writes back through master read.- os.write(master_fd, b"baseline\n")- echoed = b""- for _ in range(50): # up to ~250 ms for the line discipline to flush- try:- echoed += os.read(master_fd, 65536)- break- except BlockingIOError:- import time- time.sleep(0.005)- assert b"baseline" in echoed, (- "baseline check: PTY in default mode is supposed to echo writes back; "- "if this assertion fails the test environment is unusual and the "- "negative assertion below is meaningless"- )-- # Apply the fix and confirm no echo.- tty.setcbreak(master_fd, when=termios.TCSANOW)- # Drain any in-flight state.- try:- while True:- os.read(master_fd, 65536)- except BlockingIOError:- pass-- os.write(master_fd, b"after-cbreak\n")- leaked = b""- import time- for _ in range(50):- try:- leaked += os.read(master_fd, 65536)- except BlockingIOError:- time.sleep(0.005)- assert b"after-cbreak" not in leaked, (- f"cbreak must disable echo; got leaked bytes: {leaked!r}"- )- finally:- os.close(slave_fd)- os.close(master_fd)diff --git a/uv.lock b/uv.lockindex db6c42460..cc5403a9f 100644--- a/uv.lock+++ b/uv.lock@@ -1871,17 +1871,11 @@ name = "nemo-switchyard"version = "0.2.0"source = { editable = "." }-[package.optional-dependencies]-cli = [- { name = "prompt-toolkit" },-]-[package.dev-dependencies]dev = [{ name = "harbor", marker = "python_full_version >= '3.12'" },{ name = "maturin" },{ name = "mypy" },- { name = "nemo-switchyard", extra = ["cli"] },{ name = "pytest" },{ name = "pytest-asyncio" },{ name = "pytest-markdown-docs" },@@ -1897,15 +1891,12 @@ docs = [][package.metadata]-requires-dist = [{ name = "prompt-toolkit", marker = "extra == 'cli'", specifier = ">=3.0.52,<4.0" }]-provides-extras = ["cli"][package.metadata.requires-dev]dev = [{ name = "harbor", marker = "python_full_version >= '3.12'", git = "https://github.com/harbor-framework/harbor.git?rev=v0.6.4" },{ name = "maturin", specifier = ">=1.9,<2.0" },{ name = "mypy", specifier = ">=1.20.2,<2.0" },- { name = "nemo-switchyard", extras = ["cli"] },{ name = "pytest", specifier = ">=9.0.3,<10.0" },{ name = "pytest-asyncio", specifier = ">=1.3.0,<2.0" },{ name = "pytest-markdown-docs", specifier = ">=0.9.2" },@@ -2138,18 +2129,6 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/22/aa/ff2e09f99f95ea96fddeb373646bf907dd89a24fc00b5d38e5674ca7c9ca/postgrest-2.30.0-py3-none-any.whl", hash = "sha256:30631e7993da542419f4217cf3b60aa641084731ea15e66a18526a3a52e40a7d", size = 23108, upload-time = "2026-05-06T17:35:20.531Z" },]-[[package]]-name = "prompt-toolkit"-version = "3.0.52"-source = { registry = "https://pypi.org/simple" }-dependencies = [- { name = "wcwidth" },-]-sdist = { url = "https://files.pythonhosted.org/packages/a1/96/06e01a7b38dce6fe1db213e061a4602dd6032a8a97ef6c1a862537732421/prompt_toolkit-3.0.52.tar.gz", hash = "sha256:28cde192929c8e7321de85de1ddbe736f1375148b02f2e17edd840042b1be855", size = 434198, upload-time = "2025-08-27T15:24:02.057Z" }-wheels = [- { url = "https://files.pythonhosted.org/packages/84/03/0d3ce49e2505ae70cf43bc5bb3033955d2fc9f932163e84dc0779cc47f48/prompt_toolkit-3.0.52-py3-none-any.whl", hash = "sha256:9aac639a3bbd33284347de5ad8d68ecc044b91a762dc39b7c21095fcd6a19955", size = 391431, upload-time = "2025-08-27T15:23:59.498Z" },-]-[[package]]name = "propcache"version = "0.4.1"@@ -3591,15 +3570,6 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/b0/0b/43b96a9ecdd65ff5545b1b13b687ca486da5c6249475b1a45f24d63a1858/watchdog-4.0.2-py3-none-win_ia64.whl", hash = "sha256:baececaa8edff42cd16558a639a9b0ddf425f93d892e8392a56bf904f5eff22c", size = 82933, upload-time = "2024-08-11T07:37:59.573Z" },]-[[package]]-name = "wcwidth"-version = "0.7.0"-source = { registry = "https://pypi.org/simple" }-sdist = { url = "https://files.pythonhosted.org/packages/2c/ee/afaf0f85a9a18fe47a67f1e4422ed6cf1fe642f0ae0a2f81166231303c52/wcwidth-0.7.0.tar.gz", hash = "sha256:90e3a7ea092341c44b99562e75d09e4d5160fe7a3974c6fb842a101a95e7eed0", size = 182132, upload-time = "2026-05-02T16:04:12.653Z" }-wheels = [- { url = "https://files.pythonhosted.org/packages/41/52/e465037f5375f43533d1a80b6923955201596a99142ed524d77b571a1418/wcwidth-0.7.0-py3-none-any.whl", hash = "sha256:5d69154c429a82910e241c738cd0e2976fac8a2dd47a1a805f4afed1c0f136f2", size = 110825, upload-time = "2026-05-02T16:04:11.033Z" },-]-[[package]]name = "websockets"version = "15.0.1"