feat(advisor): review-gate advisor backend and advisor route type

AGENTS.md

@@ -158,6 +158,21 @@ Direct Rust bindings for migrated concrete processors/backends are exposed from
 | Response component | Plain Python/Rust object | `async process(ctx, response) -> ChatResponse` | Post-process (logging, stats) |
 | `TranslationEngine` | `switchyard_rust.translation` | `async translate(ctx, request, response) -> Any` | Convert to client's wire format |
 
+### Multi-call backends
+
+`AdvisorLoopBackend` (`switchyard/lib/backends/advisor_loop_backend.py`) pairs the executor with a
+stronger advisor that reviews the executor's first no-tool-call turn once per session (APPROVE
+returns it; REDO feeds the advisor's plan back and re-invokes the executor). The trigger is
+proxy-side, so it fires even for executors that rarely call tools; advisor text goes into the
+first user message, never the newest turn, so the upstream cache prefix stays stable across a
+session. It is multi-call — one `call(...)` issues several upstream requests before returning one
+`ChatResponse`, so "exactly one `LLMBackend` per chain" holds at the chain level only — and it
+does its own stats accounting into the classifier bucket, so it must not be wrapped in
+`StatsLlmBackend` (which rejects Python-only backends); the route-bundle builder injects the
+accumulator through the constructor instead. Executor and advisor targets dispatch independently
+on `LlmTarget.format`; `responses` is rejected at `AdvisorConfig` validation. Compose with a
+`type: advisor` route (`switchyard/cli/route_bundle.py`) or an `AdvisorPresets` helper.
+
 ## Project Structure
 
 ```
@@ -181,6 +196,8 @@ switchyard/
 │   │   ├── openai_llm_backend.py           # OpenAiPassthroughBackend
 │   │   ├── openai_native_backend.py        # OpenAiNativeBackend
 │   │   ├── anthropic_native_llm_backend.py # AnthropicNativeBackend
+│   │   ├── advisor_loop_backend.py         # AdvisorLoopBackend (advisor review gate)
+│   │   ├── advisor_config.py               # AdvisorConfig (+ advisor_prompts, advisor_presets)
 │   │   ├── llm_target.py                   # LlmTarget, BackendFormat
 │   │   ├── multi_llm_backend.py            # MultiLlmBackend helpers
 │   │   ├── stats_llm_backend.py            # StatsLlmBackend
@@ -242,7 +259,7 @@ and their transitives never appear in downstream vulnerability scans.
 ```bash
 export OPENROUTER_API_KEY="sk-or-..."
 
-# Serve the minimal Python YAML bundle (noop and passthrough only).
+# Serve the minimal Python YAML bundle (noop, passthrough, and advisor routes).
 switchyard serve --routes examples/route.yaml --port 4000
 
 # Launch against the packaged OpenRouter deployment.

benchmark/run-baseline.sh

@@ -881,9 +881,21 @@ if [[ "\${SERVER_ENABLED}" == "1" ]]; then
     DOCKER_RUN_ARGS=(
         -d --rm
         --name "\${SWITCHYARD_DOCKER_CONTAINER}"
-        --network "\${SWITCHYARD_DOCKER_NETWORK}"
-        --network-alias "\${SWITCHYARD_DOCKER_SERVICE_NAME}"
-        -p "127.0.0.1:$(q "${PORT}"):$(q "${PORT}")"
+    )
+    if [[ "\${SWITCHYARD_DOCKER_NETWORK_MODE:-bridge}" == "host" ]]; then
+        # Host networking: for upstreams only routable from the host (VPN /
+        # corp-internal gateways that Docker bridge networks cannot reach).
+        # Pair with --harbor-server-url http://<host-ip>:<port> so task
+        # containers reach the server at the host address.
+        DOCKER_RUN_ARGS+=(--network host)
+    else
+        DOCKER_RUN_ARGS+=(
+            --network "\${SWITCHYARD_DOCKER_NETWORK}"
+            --network-alias "\${SWITCHYARD_DOCKER_SERVICE_NAME}"
+            -p "127.0.0.1:$(q "${PORT}"):$(q "${PORT}")"
+        )
+    fi
+    DOCKER_RUN_ARGS+=(
         -v "\${REPO_ROOT}:\${REPO_ROOT}:ro"
         -v "\${RUN_DIR}:\${RUN_DIR}"
     )

crates/switchyard-components/src/backends/anthropic.rs

@@ -80,24 +80,36 @@ impl AnthropicNativeBackend {
     }
 
     fn outbound_body(&self, request: &ChatRequest) -> Result<Value> {
-        let mut body = match request.request_type() {
-            ChatRequestType::Anthropic => request.body().clone(),
-            source => {
-                self.translation
-                    .translate_request(
-                        request_wire_format(source),
-                        WireFormat::AnthropicMessages,
-                        request.body(),
-                        &self.translation_policy,
-                    )
-                    .map_err(|error| {
-                        SwitchyardError::Backend(format!(
-                            "failed to translate {source:?} request to Anthropic Messages: {error}"
-                        ))
-                    })?
-                    .body
-            }
-        };
+        // Native Anthropic requests are a TRUE passthrough: forward the client's
+        // body verbatim, rewriting only the model id (routing) and merging any
+        // operator-configured `extra_body`. The strips/normalization in the
+        // translated branch below exist for OpenAI/Responses -> Anthropic bodies,
+        // which can carry fields/shapes the Anthropic API rejects. Applying them
+        // to a real Anthropic client (e.g. Claude Code) silently drops valid
+        // Anthropic features — `context_management` (context auto-compaction),
+        // signed thinking blocks, mid-conversation system turns, client tool ids
+        // — which a passthrough must never do.
+        if matches!(request.request_type(), ChatRequestType::Anthropic) {
+            let mut body = request.body().clone();
+            set_json_model(&mut body, self.target.model.as_str());
+            merge_target_extra_body(&mut body, self.target.extra_body.as_ref());
+            return Ok(body);
+        }
+        let mut body = self
+            .translation
+            .translate_request(
+                request_wire_format(request.request_type()),
+                WireFormat::AnthropicMessages,
+                request.body(),
+                &self.translation_policy,
+            )
+            .map_err(|error| {
+                SwitchyardError::Backend(format!(
+                    "failed to translate {:?} request to Anthropic Messages: {error}",
+                    request.request_type()
+                ))
+            })?
+            .body;
         set_json_model(&mut body, self.target.model.as_str());
         strip_anthropic_incompatible_fields(&mut body);
         normalize_anthropic_body(&mut body);

crates/switchyard-components/tests/adversarial_native_backends.rs

@@ -669,9 +669,9 @@ fn anthropic_backend_is_anthropic_only() -> Result<()> {
     Ok(())
 }
 
-// Non-streaming Anthropic calls should strip incompatible fields and stamp context.
+// Non-streaming native Anthropic calls forward the body verbatim and stamp context.
 #[tokio::test]
-async fn anthropic_non_streaming_strips_incompatible_fields_and_records_context() -> Result<()> {
+async fn anthropic_native_passthrough_forwards_body_verbatim() -> Result<()> {
     let server = OneShotServer::json(
         200,
         json!({
@@ -731,16 +731,22 @@ async fn anthropic_non_streaming_strips_incompatible_fields_and_records_context(
     );
     assert_eq!(request.body["model"], "target-claude");
     assert_eq!(request.body["messages"][0]["content"], "hello");
-    assert!(request.body.get("reasoning_effort").is_none());
-    assert!(request.body.get("context_management").is_none());
+    // Native Anthropic is a verbatim passthrough: client fields are preserved,
+    // not stripped (only the model id is rewritten for routing). Stripping these
+    // belongs to the translated path, not a real /v1/messages request.
+    assert_eq!(request.body["reasoning_effort"], "high");
+    assert_eq!(
+        request.body["context_management"],
+        json!({"strategy": "auto"})
+    );
     assert_eq!(request.body["made_up_beta_field"], json!({"kept": true}));
     assert_eq!(request.body["extra_body"], json!({"caller": "value"}));
     Ok(())
 }
 
-// Anthropic-native calls should downgrade Opus-4.8-style system turns for legacy targets.
+// Native Anthropic passthrough must NOT relocate message-level system/developer turns.
 #[tokio::test]
-async fn anthropic_lifts_message_level_system_roles_before_native_call() -> Result<()> {
+async fn anthropic_native_passthrough_does_not_lift_system_messages() -> Result<()> {
     let server = OneShotServer::json(200, json!({"id": "msg-test", "content": []}))?;
     let backend = AnthropicNativeBackend::new(anthropic_target(server.base_url().to_string())?)?;
     let mut ctx = ProxyContext::new();
@@ -767,28 +773,24 @@ async fn anthropic_lifts_message_level_system_roles_before_native_call() -> Resu
         .await?;
     let request = server.captured()?;
 
-    assert_eq!(request.body["system"], "System rules.\n\nDeveloper rules.");
-    let messages = request.body["messages"]
-        .as_array()
-        .ok_or_else(|| SwitchyardError::Other("messages should be an array".to_string()))?;
-    let roles = messages
-        .iter()
-        .map(|message| {
-            message
-                .get("role")
-                .and_then(Value::as_str)
-                .unwrap_or("<missing>")
-        })
-        .collect::<Vec<_>>();
-    assert_eq!(roles, vec!["user", "assistant"]);
-    assert_eq!(messages[0]["content"], "hello");
-    assert_eq!(messages[1]["content"], "ready");
+    // Verbatim: no top-level system is synthesized, and the system/developer
+    // turns stay exactly where the client put them.
+    assert!(request.body.get("system").is_none());
+    assert_eq!(
+        request.body["messages"],
+        json!([
+            {"role": "system", "content": "System rules."},
+            {"role": "user", "content": "hello"},
+            {"role": "developer", "content": [{"type": "text", "text": "Developer rules."}]},
+            {"role": "assistant", "content": "ready"}
+        ])
+    );
     Ok(())
 }
 
-// Interleaved system turns should preserve encounter order after lifting.
+// Interleaved system/developer turns are preserved in place (no lifting) on passthrough.
 #[tokio::test]
-async fn anthropic_lifts_multiple_interleaved_system_messages_in_order() -> Result<()> {
+async fn anthropic_native_passthrough_preserves_interleaved_system_messages() -> Result<()> {
     let server = OneShotServer::json(200, json!({"id": "msg-test", "content": []}))?;
     let backend = AnthropicNativeBackend::new(anthropic_target(server.base_url().to_string())?)?;
     let mut ctx = ProxyContext::new();
@@ -813,24 +815,25 @@ async fn anthropic_lifts_multiple_interleaved_system_messages_in_order() -> Resu
         .await?;
     let request = server.captured()?;
 
-    assert_eq!(
-        request.body["system"],
-        "Top-level rules.\n\nFirst lifted system.\n\nSecond lifted system.\n\nDeveloper lifted system."
-    );
+    // Verbatim: top-level system unchanged, all message-level turns preserved in place.
+    assert_eq!(request.body["system"], "Top-level rules.");
     assert_eq!(
         request.body["messages"],
         json!([
+            {"role": "system", "content": "First lifted system."},
             {"role": "user", "content": "first user"},
+            {"role": "system", "content": "Second lifted system."},
             {"role": "assistant", "content": "assistant reply"},
+            {"role": "developer", "content": "Developer lifted system."},
             {"role": "user", "content": "second user"}
         ])
     );
     Ok(())
 }
 
-// Existing structured Anthropic system prompts should keep their shape when lifted text is added.
+// Structured system prompt and message-level system (incl. non-text blocks) pass through untouched.
 #[tokio::test]
-async fn anthropic_lifts_message_level_system_into_existing_system_blocks() -> Result<()> {
+async fn anthropic_native_passthrough_preserves_structured_system_and_messages() -> Result<()> {
     let server = OneShotServer::json(200, json!({"id": "msg-test", "content": []}))?;
     let backend = AnthropicNativeBackend::new(anthropic_target(server.base_url().to_string())?)?;
     let mut ctx = ProxyContext::new();
@@ -858,16 +861,25 @@ async fn anthropic_lifts_message_level_system_into_existing_system_blocks() -> R
         .await?;
     let request = server.captured()?;
 
+    // Verbatim: structured system kept as-is; the message-level system turn
+    // (including its image block) is preserved, not downgraded into system.
     assert_eq!(
         request.body["system"],
-        json!([
-            {"type": "text", "text": "Existing system."},
-            {"type": "text", "text": "Lifted system.\n\nLifted input text."}
-        ])
+        json!([{"type": "text", "text": "Existing system."}])
     );
     assert_eq!(
         request.body["messages"],
-        json!([{"role": "user", "content": "hello"}])
+        json!([
+            {
+                "role": "system",
+                "content": [
+                    {"type": "text", "text": "Lifted system."},
+                    {"type": "image", "source": {"type": "url", "url": "https://example.test/a.png"}},
+                    {"type": "input_text", "text": "Lifted input text."}
+                ]
+            },
+            {"role": "user", "content": "hello"}
+        ])
     );
     Ok(())
 }
@@ -898,9 +910,9 @@ async fn anthropic_translates_responses_requests_with_default_max_tokens() -> Re
     Ok(())
 }
 
-// Invalid Anthropic tool-use IDs should be sanitized consistently with results.
+// Native Anthropic passthrough preserves client tool-use IDs verbatim (no sanitization).
 #[tokio::test]
-async fn anthropic_sanitizes_invalid_tool_use_ids_and_matching_results() -> Result<()> {
+async fn anthropic_native_passthrough_preserves_tool_use_ids() -> Result<()> {
     let server = OneShotServer::json(200, json!({"id": "msg-test", "content": []}))?;
     let backend = AnthropicNativeBackend::new(anthropic_target(server.base_url().to_string())?)?;
     let mut ctx = ProxyContext::new();
@@ -936,18 +948,20 @@ async fn anthropic_sanitizes_invalid_tool_use_ids_and_matching_results() -> Resu
         .await?;
     let request = server.captured()?;
 
+    // Verbatim: the client's tool-use id is forwarded unchanged (sanitization
+    // belongs to the translated path; a real Anthropic client sends valid ids).
     let tool_use_id = &request.body["messages"][1]["content"][0]["id"];
-    assert_eq!(tool_use_id, "toolu_01_bad_id");
+    assert_eq!(tool_use_id, "toolu_01*bad:id");
     assert_eq!(
         &request.body["messages"][2]["content"][0]["tool_use_id"],
         tool_use_id
     );
     Ok(())
 }
 
-// Unsigned synthetic thinking blocks should be removed before Anthropic replay.
+// Native Anthropic passthrough preserves thinking blocks verbatim (no stripping).
 #[tokio::test]
-async fn anthropic_strips_unsigned_thinking_blocks_before_native_call() -> Result<()> {
+async fn anthropic_native_passthrough_preserves_thinking_blocks() -> Result<()> {
     let server = OneShotServer::json(200, json!({"id": "msg-test", "content": []}))?;
     let backend = AnthropicNativeBackend::new(anthropic_target(server.base_url().to_string())?)?;
     let mut ctx = ProxyContext::new();
@@ -985,15 +999,22 @@ async fn anthropic_strips_unsigned_thinking_blocks_before_native_call() -> Resul
         .await?;
     let request = server.captured()?;
 
+    // Verbatim: thinking blocks (signed or not) are preserved; the upstream API
+    // decides what to accept. Stripping unsigned blocks belongs to the translated
+    // path, where they are synthetic translation artifacts.
     assert_eq!(
         request.body["messages"][0]["content"]
             .as_array()
             .ok_or_else(|| SwitchyardError::Other("content should be an array".to_string()))?
             .len(),
-        1
+        2
     );
     assert_eq!(
         request.body["messages"][0]["content"][0]["type"],
+        "thinking"
+    );
+    assert_eq!(
+        request.body["messages"][0]["content"][1]["type"],
         "tool_use"
     );
     assert_eq!(
@@ -1004,7 +1025,10 @@ async fn anthropic_strips_unsigned_thinking_blocks_before_native_call() -> Resul
         request.body["messages"][1]["content"][0]["thinking"],
         "real"
     );
-    assert_eq!(request.body["messages"][2]["content"], "");
+    assert_eq!(
+        request.body["messages"][2]["content"],
+        json!([{"type": "thinking", "thinking": "only synthetic"}])
+    );
     Ok(())
 }
 

examples/route.yaml

@@ -10,3 +10,13 @@ routes:
 
   smoke-test:
     type: noop
+
+  # Executor gated by a stronger advisor model: the advisor reviews the
+  # executor's first no-tool-call turn (APPROVE lets it stop; REDO sends it
+  # back with a plan). Tiers accept the same fields as passthrough targets.
+  # advisor-gate:
+  #   type: advisor
+  #   executor:
+  #     model: moonshotai/kimi-k2.6
+  #   advisor:
+  #     model: anthropic/claude-opus-4.8

switchyard/__init__.py

@@ -13,6 +13,9 @@
 from typing import TYPE_CHECKING, Any
 
 from switchyard.lib.backends import (
+    AdvisorConfig,
+    AdvisorLoopBackend,
+    AdvisorPresets,
     AnthropicNativeBackend,
     OpenAiNativeBackend,
 )
@@ -121,7 +124,10 @@ def __getattr__(name: str) -> Any:
     "BackendFormat",
     "RandomRoutingProcessorConfig",
     "LlmTarget",
-    # Deterministic (LLM-classifier) routing usage case
+    # Advisor review gate (executor gated by a stronger advisor model)
+    "AdvisorConfig",
+    "AdvisorLoopBackend",
+    "AdvisorPresets",
     # Translation engine
     "TranslationEngine",
     # ChatResponse types

switchyard/cli/launchers/launcher_runtime.py

@@ -132,6 +132,17 @@ def route_bundle_strategy_summary(route_bundle: str, default_model: str) -> str:
                     target = route.get("target")
                     model = target.get("model") if isinstance(target, _Mapping) else target
                     return f"passthrough: model={model or first_key}"
+                if route_type == "advisor":
+                    tiers = {}
+                    for field in ("executor", "advisor"):
+                        tier = route.get(field)
+                        tiers[field] = (
+                            tier.get("model") if isinstance(tier, _Mapping) else tier
+                        )
+                    return (
+                        f"advisor: executor={tiers['executor']}, "
+                        f"advisor={tiers['advisor']}"
+                    )
     except Exception:
         pass
     return f"route: {default_model}"