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
feat(routing): sub-agent override as a libsy classifier, restored on the serve path (#145)
Lin Jia65beb853c9e5
diff --git a/benchmark/run_cost.py b/benchmark/run_cost.pynew file mode 100644index 000000000..3b7f3250f--- /dev/null+++ b/benchmark/run_cost.py@@ -0,0 +1,105 @@+#!/usr/bin/env python3+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0+"""Per-model cost breakdown for a benchmark run's routing log.++Aggregates ``routing_requests.jsonl`` by served model and prices each bucket with+:func:`switchyard.lib.cost_estimator.estimate_model_cost`, which splits input into+base / cache-read / cache-write tiers. That split matters: agentic runs are+cache-dominated (90%+ of prompt tokens are cache reads is normal), so a flat+input rate overstates cost several-fold.++On a run that routes sub-agent work to a different tier, the served-model column+doubles as the parent/child attribution key — the routing log records no+``agent_id``, so which model answered is the only role signal available.++Models absent from the price table contribute $0 and are listed separately, so an+unpriced model reads as a gap rather than as a free one.++Usage:+ uv run python benchmark/run_cost.py --run benchmark/tb_runs/<run-name>+"""++from __future__ import annotations++import argparse+import collections+import json+from pathlib import Path++from switchyard.lib.cost_estimator import MODEL_PRICING, estimate_model_cost++_TOKEN_FIELDS = (+ "prompt_tokens",+ "completion_tokens",+ "cached_tokens",+ "cache_creation_tokens",+)+++def _aggregate(routing_log: Path) -> dict[str, collections.Counter[str]]:+ """Sum request counts and token fields per served model."""+ totals: dict[str, collections.Counter[str]] = collections.defaultdict(collections.Counter)+ for line in routing_log.read_text().splitlines():+ if not line.strip():+ continue+ record = json.loads(line)+ bucket = totals[record.get("model") or "<unknown>"]+ bucket["reqs"] += 1+ for field in _TOKEN_FIELDS:+ bucket[field] += record.get(field) or 0+ return totals+++def _mean_agg_score(run: Path) -> tuple[float, int] | None:+ """Mean rubric ``agg_score`` across the run's scored tasks, if any."""+ scores = [+ json.loads(path.read_text())["agg_score"]+ for path in run.glob("jobs/*/task-*/verifier/evaluation_results.json")+ ]+ return (sum(scores) / len(scores), len(scores)) if scores else None+++def main() -> None:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--run", required=True, type=Path, help="Run directory under tb_runs/")+ args = parser.parse_args()++ totals = _aggregate(args.run / "routing_requests.jsonl")+ if not totals:+ print("no routing records found")+ return++ unpriced = [model for model in totals if model not in MODEL_PRICING]+ total_cost = 0.0+ header = f"{'model':46s} {'reqs':>5s} {'in':>11s} {'out':>9s} {'cached':>11s} {'USD':>9s}"+ print(header)+ for model, bucket in sorted(totals.items(), key=lambda item: -item[1]["reqs"]):+ cost = estimate_model_cost(+ model,+ bucket["prompt_tokens"],+ bucket["completion_tokens"],+ bucket["cached_tokens"],+ bucket["cache_creation_tokens"],+ )["total_cost"]+ total_cost += cost+ print(+ f"{model:46s} {bucket['reqs']:5d} {bucket['prompt_tokens']:11,} "+ f"{bucket['completion_tokens']:9,} {bucket['cached_tokens']:11,} {cost:9.3f}"+ )++ requests = sum(bucket["reqs"] for bucket in totals.values())+ print(f"\nTOTAL: ${total_cost:.2f} over {requests} requests")+ if unpriced:+ # Priced at zero by estimate_model_cost — surface it so the total is not+ # mistaken for complete.+ print(f"NOTE: no price entry for {', '.join(sorted(unpriced))} — excluded from the total")++ scored = _mean_agg_score(args.run)+ if scored:+ mean, count = scored+ print(f"mean agg_score: {mean:.3f} over {count} tasks → ${total_cost / count:.2f}/task")+++if __name__ == "__main__":+ main()diff --git a/crates/libsy/src/algorithms.rs b/crates/libsy/src/algorithms.rsindex b81e62217..25f692e25 100644--- a/crates/libsy/src/algorithms.rs+++ b/crates/libsy/src/algorithms.rs@@ -10,12 +10,11 @@ pub mod fall_through;pub mod llm_class;pub mod noop;pub mod rand;-pub mod subagent_override;pub use fall_through::{FallThrough, FallThroughDecision};pub use llm_class::{ClassifierDecision, ClassifierTier, LlmClassifier};pub use noop::{Noop, NoopDecision};pub use rand::{Random, RandomDecision};-pub use subagent_override::{SubagentDecision, SubagentOverride};+pub use util::{AffinityRouter, SubagentOverride};-pub(crate) mod util;+pub mod util;diff --git a/crates/libsy/src/algorithms/fall_through.rs b/crates/libsy/src/algorithms/fall_through.rsindex 3e08579f9..40c302a04 100644--- a/crates/libsy/src/algorithms/fall_through.rs+++ b/crates/libsy/src/algorithms/fall_through.rs@@ -75,6 +75,19 @@ impl FallThrough {self.classifiers.push(classifier);self}++ /// Registers one dual-role component in *both* the processor chain and the classifier+ /// cascade.+ ///+ /// A component that writes state as a [`Processor`] and reads it back as a+ /// [`Classifier`] — such as [`AffinityRouter`](crate::algorithms::AffinityRouter) —+ /// shares that state through the instance, so both roles must be the same `Arc`.+ /// Registering the two separately is easy to half-wire: omit the processor and the+ /// classifier silently never sees an assignment. This registers both at once.+ pub fn with_component<T: Processor + Classifier + 'static>(self, component: Arc<T>) -> Self {+ self.with_processor(component.clone())+ .with_classifier(component)+ }}#[async_trait]impl Algorithm<SharedState> for FallThrough {diff --git a/crates/libsy/src/algorithms/subagent_override.rs b/crates/libsy/src/algorithms/subagent_override.rsdeleted file mode 100644index b64c6b868..000000000--- a/crates/libsy/src/algorithms/subagent_override.rs+++ /dev/null@@ -1,206 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--//! Sub-agent override combinator built on the [`Algorithm`] interfaces.-//!-//! Wraps any algorithm without changing its behavior for normal traffic. A-//! request whose [`Metadata`] marks delegated sub-agent work-//! ([`Metadata::is_subagent_work`]) is served by one fixed worker target —-//! keeping a sub-agent loop on an intentional, cache-compatible target —-//! while every other request delegates to the wrapped algorithm. The wrapped-//! algorithm never learns about harnesses or lineage headers, and a worker-//! failure surfaces as a normal target error rather than re-entering the-//! wrapped algorithm.--use std::sync::Arc;--use async_trait::async_trait;--use crate::{Algorithm, Context, Decision, Driver, LlmTarget, Metadata, Request, Response, Result};--/// Decision produced by [`SubagentOverride`] when it routes to the worker target.-pub struct SubagentDecision {- /// The fixed worker target selected for the sub-agent request.- pub selected_model: String,- /// Human-readable explanation of the override.- pub reasoning: String,-}--impl Decision for SubagentDecision {- fn selected_model(&self) -> &str {- &self.selected_model- }-- fn reasoning(&self) -> Option<&str> {- Some(&self.reasoning)- }-- fn as_any(&self) -> &dyn std::any::Any {- self- }-}--/// Routes delegated sub-agent work to a fixed worker target; delegates the rest.-pub struct SubagentOverride {- inner: Arc<dyn Algorithm>,- worker: LlmTarget,-}--impl SubagentOverride {- /// Wraps `inner`, sending recognized sub-agent work to `worker` instead.- ///- /// Wrap it in an [`Arc`] and drive it with [`Algorithm::run`] or- /// [`Algorithm::run_stream`].- pub fn new(inner: Arc<dyn Algorithm>, worker: LlmTarget) -> Self {- Self { inner, worker }- }-}--#[async_trait]-impl Algorithm for SubagentOverride {- fn name(&self) -> &str {- "subagent_override"- }-- async fn create_run_task(- self: Arc<Self>,- ctx: Context,- driver: Driver,- request: Request,- ) -> Result<Response> {- let is_subagent_work = request- .metadata- .as_ref()- .is_some_and(Metadata::is_subagent_work);- if !is_subagent_work {- return Arc::clone(&self.inner)- .create_run_task(ctx, driver, request)- .await;- }-- let selected = self.worker.semantic_name.clone();- let decision: Arc<dyn Decision> = Arc::new(SubagentDecision {- reasoning: format!("sub-agent work routed to fixed worker target '{selected}'"),- selected_model: selected,- });- driver.info(ctx.clone(), Arc::clone(&decision)).await?;- driver- .call_llm_target(ctx, &self.worker, request, decision)- .await- }-}--#[cfg(test)]-mod tests {- use super::*;- use std::collections::BTreeMap;-- use switchyard_protocol::{completion_text, text_request, text_response};-- use crate::algorithms::Random;- use crate::{LlmResponse, LlmTargetSet, RoutedLlmClient};-- /// Echoes the selected target so tests can inspect which target was called.- struct EchoClient;-- #[async_trait]- impl RoutedLlmClient for EchoClient {- async fn call(- &self,- _ctx: Context,- _request: Request,- decision: Arc<dyn Decision>,- ) -> std::result::Result<Response, switchyard_protocol::LlmClientError> {- Ok(Response {- llm_response: LlmResponse::Agg(text_response(None, decision.selected_model())),- metadata: None,- })- }- }-- fn target(name: &str) -> LlmTarget {- LlmTarget {- semantic_name: name.to_string(),- llm_client: Some(Arc::new(EchoClient)),- }- }-- fn request(headers: &[(&str, &str)]) -> Request {- let metadata = (!headers.is_empty()).then(|| {- Metadata::from_headers(- &headers- .iter()- .map(|(name, value)| ((*name).to_string(), (*value).to_string()))- .collect::<BTreeMap<_, _>>(),- )- });- Request {- llm_request: text_request(Some("auto".to_string()), "hi"),- raw_request: None,- metadata,- }- }-- /// Wraps single-target random routing so the inner selection is deterministic.- fn algorithm() -> Arc<dyn Algorithm> {- let inner: Arc<dyn Algorithm> =- Arc::new(Random::new(LlmTargetSet::new(vec![target("orchestrator")])));- Arc::new(SubagentOverride::new(inner, target("worker")))- }-- async fn selected_model(headers: &[(&str, &str)]) -> Result<String> {- let (trace, response) = algorithm()- .run(Context::default(), request(headers))- .await?;- let selected = response- .llm_response- .as_agg()- .map(completion_text)- .unwrap_or_default();- assert_eq!(- trace.last().map(|d| d.selected_model().to_string()),- Some(selected.clone())- );- Ok(selected)- }-- #[tokio::test]- async fn requests_without_metadata_delegate_to_the_wrapped_algorithm() -> Result<()> {- assert_eq!(selected_model(&[]).await?, "orchestrator");- Ok(())- }-- #[tokio::test]- async fn subagent_work_is_routed_to_the_worker_target() -> Result<()> {- // Claude Code child-agent lineage.- let claude = &[- ("x-claude-code-session-id", "root"),- ("x-claude-code-agent-id", "child-1"),- ];- assert_eq!(selected_model(claude).await?, "worker");-- // Codex delegated-work kinds.- assert_eq!(- selected_model(&[("x-openai-subagent", "review")]).await?,- "worker"- );- assert_eq!(- selected_model(&[("x-openai-subagent", "collab_spawn")]).await?,- "worker"- );- Ok(())- }-- #[tokio::test]- async fn harness_maintenance_turns_stay_on_the_wrapped_algorithm() -> Result<()> {- assert_eq!(- selected_model(&[("x-openai-subagent", "compact")]).await?,- "orchestrator"- );- assert_eq!(- selected_model(&[("x-switchyard-is-subagent", "false")]).await?,- "orchestrator"- );- Ok(())- }-}diff --git a/crates/libsy/src/algorithms/util.rs b/crates/libsy/src/algorithms/util.rsindex 99c18a44f..601cffef3 100644--- a/crates/libsy/src/algorithms/util.rs+++ b/crates/libsy/src/algorithms/util.rs@@ -1,7 +1,8 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-mod affinity;+pub mod affinity;+pub mod subagent;-#[allow(unused_imports)]-pub(crate) use affinity::AffinityRouter;+pub use affinity::AffinityRouter;+pub use subagent::SubagentOverride;diff --git a/crates/libsy/src/algorithms/util/affinity.rs b/crates/libsy/src/algorithms/util/affinity.rsindex 4a12faf38..9f1c793d7 100644--- a/crates/libsy/src/algorithms/util/affinity.rs+++ b/crates/libsy/src/algorithms/util/affinity.rs@@ -18,8 +18,6 @@//! session. [`AffinityRouter::for_subagents`] narrows affinity to explicitly identified//! child agents, leaving root traffic to later classifiers on every turn.-#![allow(dead_code)]-use std::collections::{HashMap, HashSet};use async_trait::async_trait;diff --git a/crates/libsy/src/algorithms/util/subagent.rs b/crates/libsy/src/algorithms/util/subagent.rsnew file mode 100644index 000000000..6b5d5b971--- /dev/null+++ b/crates/libsy/src/algorithms/util/subagent.rs@@ -0,0 +1,155 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Sub-agent override as a single SDK component.+//!+//! [`SubagentOverride`] scores one fixed worker target for requests carrying delegated+//! sub-agent work ([`Metadata::is_subagent_work`]) and abstains for everything else, so a+//! cascade falls through to its later classifiers on ordinary traffic.+//!+//! It is stateless and holds only the worker's *name*: the+//! [`FallThrough`](crate::algorithms::FallThrough) cascade resolves that name against its+//! target set. Keeping the policy independent of any memory of past decisions is what lets+//! it compose with a stateful classifier such as+//! [`AffinityRouter`](crate::algorithms::AffinityRouter) — the override decides *which*+//! target delegated work belongs on, affinity decides *how long* a decision lives, and+//! neither needs to know about the other.++use async_trait::async_trait;++use crate::{Classification, Classifier, Driver, Metadata, Request, Result, Score, State};++/// Scores a fixed worker target for delegated sub-agent work; abstains otherwise.+pub struct SubagentOverride {+ /// Name of the worker target, resolved by the cascade against its target set.+ worker: String,+}++impl SubagentOverride {+ /// Creates an override scoring `worker` for delegated sub-agent work.+ ///+ /// `worker` must name a target in the cascade's set, or routing a sub-agent request+ /// fails with [`LibsyError::TargetNotFound`](crate::LibsyError::TargetNotFound).+ pub fn new(worker: impl Into<String>) -> Self {+ Self {+ worker: worker.into(),+ }+ }+}++#[async_trait]+impl Classifier for SubagentOverride {+ async fn score(+ &self,+ _state: &mut State,+ request: &Request,+ _driver: Option<&Driver>,+ ) -> Result<Classification> {+ // Delegated *work* only. A harness maintenance turn (e.g. Codex `compact`) carries+ // sub-agent lineage but is not delegated work, so it abstains and routes normally.+ let is_delegated_work = request+ .metadata+ .as_ref()+ .is_some_and(Metadata::is_subagent_work);+ Ok(Classification::Scores(if is_delegated_work {+ vec![Score {+ confidence: 1.0,+ target: self.worker.clone(),+ }]+ } else {+ Vec::new()+ }))+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::collections::BTreeMap;++ use switchyard_protocol::text_request;++ fn request(headers: &[(&str, &str)]) -> Request {+ let metadata = (!headers.is_empty()).then(|| {+ Metadata::from_headers(+ &headers+ .iter()+ .map(|(name, value)| ((*name).to_string(), (*value).to_string()))+ .collect::<BTreeMap<_, _>>(),+ )+ });+ Request {+ llm_request: text_request(Some("auto".to_string()), "hi"),+ raw_request: None,+ metadata,+ }+ }++ /// Scores `headers` through the override, returning the winning target if it scored.+ async fn selected(headers: &[(&str, &str)]) -> Result<Option<String>> {+ let mut state = State::default();+ let classification = SubagentOverride::new("worker")+ .score(&mut state, &request(headers), None)+ .await?;+ Ok(classification.argmax(false)?.map(|score| score.target))+ }++ #[tokio::test]+ async fn requests_without_metadata_abstain() -> Result<()> {+ assert_eq!(selected(&[]).await?, None);+ Ok(())+ }++ #[tokio::test]+ async fn subagent_work_scores_the_worker() -> Result<()> {+ // Claude Code child-agent lineage.+ let claude = &[+ ("x-claude-code-session-id", "root"),+ ("x-claude-code-agent-id", "child-1"),+ ];+ assert_eq!(selected(claude).await?, Some("worker".to_string()));++ // Codex delegated-work kinds.+ assert_eq!(+ selected(&[("x-openai-subagent", "review")]).await?,+ Some("worker".to_string())+ );+ assert_eq!(+ selected(&[("x-openai-subagent", "collab_spawn")]).await?,+ Some("worker".to_string())+ );+ Ok(())+ }++ #[tokio::test]+ async fn harness_maintenance_turns_abstain() -> Result<()> {+ assert_eq!(selected(&[("x-openai-subagent", "compact")]).await?, None);+ assert_eq!(+ selected(&[("x-switchyard-is-subagent", "false")]).await?,+ None+ );+ Ok(())+ }++ #[tokio::test]+ async fn delegated_work_is_scored_definitively() -> Result<()> {+ // Confidence 1.0 under `Scores` (never `Ambiguous`), so the cascade stops here+ // rather than consulting later classifiers.+ let mut state = State::default();+ let classification = SubagentOverride::new("worker")+ .score(+ &mut state,+ &request(&[("x-openai-subagent", "review")]),+ None,+ )+ .await?;+ match classification {+ Classification::Scores(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].confidence, 1.0);+ }+ Classification::Ambiguous(_) => panic!("override must score definitively"),+ }+ Ok(())+ }+}diff --git a/crates/libsy/tests/subagent_affinity.rs b/crates/libsy/tests/subagent_affinity.rsnew file mode 100644index 000000000..7e54d6380--- /dev/null+++ b/crates/libsy/tests/subagent_affinity.rs@@ -0,0 +1,269 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Integration tests for composing the sub-agent override with affinity routing.+//!+//! The two are independent classifiers in one [`FallThrough`] cascade: the override decides+//! *which* target delegated work belongs on, affinity decides *how long* that decision+//! lives. These tests drive them through the crate's public API, so they also pin that the+//! pieces needed to compose a cascade are actually exported.++use std::collections::BTreeMap;+use std::sync::Arc;++use async_trait::async_trait;++use switchyard_libsy::algorithms::{AffinityRouter, FallThrough, SubagentOverride};+use switchyard_libsy::{+ Algorithm, Classification, Classifier, Context, Decision, Driver, LlmResponse, LlmTarget,+ LlmTargetSet, Metadata, Request, Response, Result, RoutedLlmClient, Score, SharedState, State,+};+use switchyard_protocol::{completion_text, text_request, text_response};++/// A client that echoes the routed target name back as the completion.+struct EchoClient;++#[async_trait]+impl RoutedLlmClient for EchoClient {+ async fn call(+ &self,+ _ctx: Context,+ _request: Request,+ decision: Arc<dyn Decision>,+ ) -> std::result::Result<Response, switchyard_protocol::LlmClientError> {+ Ok(Response {+ llm_response: LlmResponse::Agg(text_response(None, decision.selected_model())),+ metadata: None,+ })+ }+}++/// The cascade's terminal classifier: always picks the orchestrator.+struct AlwaysOrchestrator;++#[async_trait]+impl Classifier for AlwaysOrchestrator {+ async fn score(+ &self,+ _state: &mut State,+ _request: &Request,+ _driver: Option<&Driver>,+ ) -> Result<Classification> {+ Ok(Classification::Scores(vec![Score {+ confidence: 0.5,+ target: "orchestrator".to_string(),+ }]))+ }+}++fn targets() -> LlmTargetSet {+ LlmTargetSet::new(+ ["orchestrator", "worker", "reviewer"]+ .iter()+ .map(|name| LlmTarget {+ semantic_name: (*name).to_string(),+ llm_client: Some(Arc::new(EchoClient) as Arc<dyn RoutedLlmClient>),+ })+ .collect(),+ )+}++fn request(headers: &[(&str, &str)]) -> Request {+ Request {+ llm_request: text_request(Some("auto".to_string()), "hi"),+ raw_request: None,+ metadata: Some(Metadata::from_headers(+ &headers+ .iter()+ .map(|(name, value)| ((*name).to_string(), (*value).to_string()))+ .collect::<BTreeMap<_, _>>(),+ )),+ }+}++/// Affinity replays an existing pin, the override seeds one for delegated work, and the+/// terminal classifier serves everything else.+fn router() -> Arc<FallThrough> {+ Arc::new(+ FallThrough::new(targets())+ .with_component(Arc::new(AffinityRouter::for_subagents()))+ .with_classifier(Arc::new(SubagentOverride::new("worker")))+ .with_classifier(Arc::new(AlwaysOrchestrator)),+ )+}++/// Runs one turn on `ctx`, returning the target that served it.+///+/// `ctx` carries the per-session [`State`] the processor chain folds into. The affinity+/// assignments are held on the `AffinityRouter` instance instead, so replay follows the+/// shared router rather than the context.+async fn turn(+ router: &Arc<FallThrough>,+ ctx: Context<SharedState>,+ headers: &[(&str, &str)],+) -> Result<String> {+ let (_, response) = router.clone().run(ctx, request(headers)).await?;+ Ok(response+ .llm_response+ .as_agg()+ .map(completion_text)+ .unwrap_or_default())+}++/// A Claude Code child agent's lineage headers.+fn child(agent: &str) -> Vec<(&str, &str)> {+ vec![+ ("x-claude-code-session-id", "session-1"),+ ("x-claude-code-agent-id", agent),+ ]+}++#[tokio::test]+async fn root_traffic_falls_through_to_the_terminal_classifier() -> Result<()> {+ let ctx = Context::<SharedState>::default();+ // No sub-agent lineage: affinity abstains (subagents only), the override abstains, and+ // the terminal classifier serves the turn.+ let served = turn(&router(), ctx, &[("x-claude-code-session-id", "session-1")]).await?;+ assert_eq!(served, "orchestrator");+ Ok(())+}++#[tokio::test]+async fn delegated_work_is_routed_to_the_worker() -> Result<()> {+ let ctx = Context::<SharedState>::default();+ assert_eq!(turn(&router(), ctx, &child("child-1")).await?, "worker");+ Ok(())+}++#[tokio::test]+async fn the_override_seeds_a_pin_that_affinity_replays() -> Result<()> {+ let router = router();+ let ctx = Context::<SharedState>::default();++ // Turn 1: affinity has no assignment, so the override decides and the decision is+ // replayed into affinity.+ assert_eq!(+ turn(&router, ctx.clone(), &child("child-1")).await?,+ "worker"+ );++ // Turns 2-3: the lineage header still identifies the child, but affinity — not the+ // override — is now the classifier that answers, because it scores first.+ assert_eq!(+ turn(&router, ctx.clone(), &child("child-1")).await?,+ "worker"+ );+ assert_eq!(turn(&router, ctx, &child("child-1")).await?, "worker");+ Ok(())+}++#[tokio::test]+async fn harness_maintenance_turns_are_not_forced_to_the_worker() -> Result<()> {+ let router = router();+ let ctx = Context::<SharedState>::default();++ // A Codex `compact` turn is sub-agent *lineage* but not delegated *work*: the two+ // predicates differ on purpose, so the override abstains and it routes normally.+ let served = turn(+ &router,+ ctx,+ &[+ ("x-codex-session-id", "session-1"),+ ("x-openai-subagent", "compact"),+ ],+ )+ .await?;+ assert_eq!(served, "orchestrator");+ Ok(())+}++/// Builds a cascade whose override scores `worker`, sharing `affinity` across instances.+fn router_overriding_to(affinity: Arc<AffinityRouter>, worker: &str) -> Arc<FallThrough> {+ Arc::new(+ FallThrough::new(targets())+ .with_component(affinity)+ .with_classifier(Arc::new(SubagentOverride::new(worker)))+ .with_classifier(Arc::new(AlwaysOrchestrator)),+ )+}++#[tokio::test]+async fn the_pin_outlives_the_policy_that_seeded_it() -> Result<()> {+ // Two cascades sharing one affinity instance, with overrides that disagree. The first+ // seeds "worker"; the second would score "reviewer" but is never consulted, because+ // affinity scores earlier in the cascade and replays the existing pin. This is what+ // distinguishes a real replay from the override simply repeating itself.+ let affinity = Arc::new(AffinityRouter::for_subagents());+ let seed = router_overriding_to(affinity.clone(), "worker");+ let rebound = router_overriding_to(affinity, "reviewer");++ assert_eq!(+ turn(&seed, Context::default(), &child("child-1")).await?,+ "worker"+ );+ assert_eq!(+ turn(&rebound, Context::default(), &child("child-1")).await?,+ "worker"+ );+ Ok(())+}++#[tokio::test]+async fn without_a_shared_pin_the_second_policy_wins() -> Result<()> {+ // The negative control for the test above: with independent affinity instances there+ // is no pin to replay, so the second cascade's own override decides. Without this,+ // the replay assertion could pass for the wrong reason.+ let seed = router_overriding_to(Arc::new(AffinityRouter::for_subagents()), "worker");+ let rebound = router_overriding_to(Arc::new(AffinityRouter::for_subagents()), "reviewer");++ assert_eq!(+ turn(&seed, Context::default(), &child("child-1")).await?,+ "worker"+ );+ assert_eq!(+ turn(&rebound, Context::default(), &child("child-1")).await?,+ "reviewer"+ );+ Ok(())+}++#[tokio::test]+async fn distinct_children_are_pinned_independently() -> Result<()> {+ // Two cascades sharing one affinity instance but disagreeing on the worker. Routing+ // both children through the *same* override would pass whether or not affinity keys+ // per agent, so the sibling is sent through the cascade that scores "reviewer": it+ // can only come back "reviewer" if it did not inherit child-1's pin.+ let affinity = Arc::new(AffinityRouter::for_subagents());+ let seed = router_overriding_to(affinity.clone(), "worker");+ let sibling = router_overriding_to(affinity, "reviewer");++ assert_eq!(+ turn(&seed, Context::default(), &child("child-1")).await?,+ "worker"+ );+ assert_eq!(+ turn(&sibling, Context::default(), &child("child-2")).await?,+ "reviewer"+ );+ // child-1's own pin is untouched by the sibling's assignment: affinity replays it+ // even through the cascade whose override would otherwise score "reviewer".+ assert_eq!(+ turn(&sibling, Context::default(), &child("child-1")).await?,+ "worker"+ );+ Ok(())+}++#[tokio::test]+async fn a_cascade_without_the_override_still_routes_root_traffic() -> Result<()> {+ // Affinity and the override are independent: dropping the override leaves a valid+ // cascade, which is the point of composing them rather than nesting one in the other.+ let router = Arc::new(+ FallThrough::new(targets())+ .with_component(Arc::new(AffinityRouter::for_subagents()))+ .with_classifier(Arc::new(AlwaysOrchestrator)),+ );+ let ctx = Context::<SharedState>::default();+ assert_eq!(turn(&router, ctx, &child("child-1")).await?, "orchestrator");+ Ok(())+}diff --git a/crates/switchyard-py/src/core_bindings.rs b/crates/switchyard-py/src/core_bindings.rsindex ce183924f..fece0fe6b 100644--- a/crates/switchyard-py/src/core_bindings.rs+++ b/crates/switchyard-py/src/core_bindings.rs@@ -10,6 +10,7 @@ pub(crate) mod request;pub(crate) mod response;pub(crate) mod roles;pub(crate) mod session;+pub(crate) mod subagent;pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {context::register(module)?;@@ -17,5 +18,6 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {response::register(module)?;roles::register(module)?;session::register(module)?;+ subagent::register(module)?;Ok(())}diff --git a/crates/switchyard-py/src/core_bindings/subagent.rs b/crates/switchyard-py/src/core_bindings/subagent.rsnew file mode 100644index 000000000..2948c8576--- /dev/null+++ b/crates/switchyard-py/src/core_bindings/subagent.rs@@ -0,0 +1,29 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Python binding for the canonical sub-agent detection policy.+//!+//! Profiles must not sniff lineage headers themselves: the fact (explicit+//! `x-switchyard-is-subagent`, Claude Code agent lineage, Codex/relay markers) and the+//! work-vs-maintenance policy both live in the protocol crate, so every engine — the libsy+//! classifier and the serve-path profile alike — answers "is this delegated work?"+//! identically.++use std::collections::BTreeMap;++use pyo3::prelude::*;++/// Whether `headers` mark this request as delegated sub-agent *work*.+///+/// Wraps [`switchyard_protocol::Metadata::from_headers`] for the lineage fact and+/// `is_subagent_work` for the kind policy, so harness maintenance turns (Codex `compact`,+/// `memory_consolidation`) stay on normal routing rather than being sent to a worker target.+#[pyfunction]+fn is_subagent_request(headers: BTreeMap<String, String>) -> bool {+ switchyard_protocol::Metadata::from_headers(&headers).is_subagent_work()+}++pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {+ module.add_function(wrap_pyfunction!(is_subagent_request, module)?)?;+ Ok(())+}diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex a0e21f139..68984c9eb 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -9,7 +9,7 @@ use async_trait::async_trait;use pyo3::exceptions::{PyTypeError, PyValueError};use pyo3::prelude::*;use serde_json::{json, Value};-use switchyard_libsy::algorithms::{Noop, Random, SubagentOverride};+use switchyard_libsy::algorithms::{Noop, Random};use switchyard_libsy::{AggLlmResponse, Algorithm, Context, Decision, LlmClientError, LlmResponse, LlmTarget,LlmTargetSet, Metadata, Request, Response, RoutedLlmClient,@@ -111,8 +111,8 @@ impl PyAlgorithm {////// `headers`, when given, is normalized into the request's correlation/// [`Metadata`] exactly as an HTTP host would (`Metadata::from_headers`),- /// so metadata-driven algorithms such as `subagent_override` see the same- /// signals in Python as when served over HTTP.+ /// so metadata-driven algorithms see the same signals in Python as when+ /// served over HTTP.#[pyo3(signature = (request, headers=None))]fn run<'py>(&self,@@ -175,24 +175,6 @@ fn random_algorithm(py: Python<'_>, targets: Vec<Py<PyLlmTarget>>) -> PyResult<P)))))}-/// Wrap `inner`, routing delegated sub-agent work to a fixed worker target.-///-/// Detection and the work-vs-maintenance policy are the protocol crate's-/// `Metadata::from_headers` / `Metadata::is_subagent_work`, driven by the-/// `headers` passed to `Algorithm.run`.-#[pyfunction(name = "subagent_override")]-fn subagent_override_algorithm(- py: Python<'_>,- inner: Py<PyAlgorithm>,- worker: Py<PyLlmTarget>,-) -> PyResult<PyAlgorithm> {- let inner = Arc::clone(&inner.bind(py).get().inner);- let worker = worker.bind(py).try_borrow()?.clone_core(py);- Ok(PyAlgorithm::new(Arc::new(SubagentOverride::new(- inner, worker,- ))))-}-fn other_python_error(error: PyErr) -> LlmClientError {LlmClientError::Ffi {source: Box::new(error),@@ -211,10 +193,6 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {libsy_module.add_class::<PyLlmTarget>()?;libsy_module.add_function(wrap_pyfunction!(noop_algorithm, &libsy_module)?)?;libsy_module.add_function(wrap_pyfunction!(random_algorithm, &libsy_module)?)?;- libsy_module.add_function(wrap_pyfunction!(- subagent_override_algorithm,- &libsy_module- )?)?;libsy_module.add("LibsyError", module.getattr("LibsyError")?)?;module.add_submodule(&libsy_module)?;Ok(())diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.mdindex 28ff6b356..75dfcdb40 100644--- a/docs/routing_algorithms/overview.md+++ b/docs/routing_algorithms/overview.md@@ -89,6 +89,54 @@ routes:Switchyard does not start or manage the model server; it only sends requeststo the configured endpoint.+## Sub-agent override (`subagent_target`)++Any route may name an optional `subagent_target` in its common envelope,+alongside `type`. A request carrying a recognized sub-agent signal — Claude Code+agent-lineage headers, Codex delegated-work kinds (`x-openai-subagent:+collab_spawn` or `review`), or an explicit `x-switchyard-is-subagent: true` —+bypasses the route's own chain and runs as a direct passthrough to that target:++```yaml+routes:+ assistant:+ type: model+ target:+ model: strong-model+ subagent_target:+ model: cheaper-worker-model+```++This keeps a sub-agent loop on one intentional, cache-compatible target instead+of re-routing every worker turn. The worker may live on a different provider+entirely — give it its own `base_url` and `api_key` and one route spans two+upstreams:++```yaml+ subagent_target:+ model: my-local-model+ base_url: http://localhost:8000/v1+ api_key: dummy+ format: openai+```++Detection is the protocol crate's canonical policy, shared with the libsy+`SubagentOverride` classifier, so both engines agree on what counts as+delegated work. Harness-maintenance turns (`compact`, `memory_consolidation`)+and unrecognized kinds stay on normal routing, as does everything else when the+field is absent. A worker-target failure surfaces as a normal target error — it+is never silently re-routed through the route's own chain.++To suppress sub-agent routing for a request that carries a recognized signal,+send `x-switchyard-is-subagent: false`. This explicit header overrides Codex and+Claude Code lineage signals in either direction: `false` keeps the request on+normal routing even when delegated-work headers are present, and `true` marks a+request as a sub-agent even when no harness headers appear.++The key applies to `model`, `passthrough`, `deterministic`, `escalation_router`,+and `stage_router` routes. `random_routing` expands into its table entries on a+separate path and does not consume it.+## How session affinity composesSession affinity is configured directly on the LLM classifier router. Afterdiff --git a/switchyard/cli/route_bundle.py b/switchyard/cli/route_bundle.pyindex a1844900f..727c648b9 100644--- a/switchyard/cli/route_bundle.py+++ b/switchyard/cli/route_bundle.py@@ -48,6 +48,7 @@ from switchyard.lib.profiles.deterministic_routing_config import DeterministicRofrom switchyard.lib.profiles.escalation_router_config import EscalationRouterConfigfrom switchyard.lib.profiles.random_routing import RandomRoutingConfigfrom switchyard.lib.profiles.stage_router_config import StageRouterConfig+from switchyard.lib.profiles.subagent_override import SubagentOverrideRuntimefrom switchyard.lib.route_table import ChainRuntime, RouteTablefrom switchyard.lib.route_table_builders import (build_passthrough_table,@@ -141,13 +142,21 @@ _TARGET_DEFAULT_KEYS = frozenset({"extra_headers","endpoint",})+# Envelope keys valid on every route type, whatever its own schema. They configure the+# wrapper around a route's chain rather than the chain itself, so they are accepted by+# _validate_route_keys and excluded from the per-profile config in _route_config.+_ROUTE_ENVELOPE_KEYS = frozenset({+ # Delegated sub-agent work is served by this target instead of the route's own+ # chain. Consumed in _build_switchyard_for_route.+ "subagent_target",+})_COMMON_ROUTE_KEYS = frozenset({"type","kind","defaults","display_name","description",-})+}) | _ROUTE_ENVELOPE_KEYS_ROUTE_METADATA_KEYS = frozenset({"type","kind",@@ -785,6 +794,66 @@ def _build_switchyard_for_route(stats: StatsAccumulator,pre_routing_request_processors: Sequence[Any] = (),extra_response_processors: Sequence[Any] = (),+) -> ChainRuntime:+ """Build the route's chain, wrapping it when the route sets ``subagent_target``."""+ chain = _build_route_chain(+ model_id,+ route,+ route_type=route_type,+ target_defaults=target_defaults,+ stats=stats,+ pre_routing_request_processors=pre_routing_request_processors,+ extra_response_processors=extra_response_processors,+ )+ worker = _subagent_worker_runtime(+ model_id,+ route,+ target_defaults=target_defaults,+ stats=stats,+ pre_routing_request_processors=pre_routing_request_processors,+ extra_response_processors=extra_response_processors,+ )+ return chain if worker is None else SubagentOverrideRuntime(chain, worker)+++def _subagent_worker_runtime(+ model_id: str,+ route: Mapping[str, object],+ target_defaults: Mapping[str, object],+ stats: StatsAccumulator,+ pre_routing_request_processors: Sequence[Any] = (),+ extra_response_processors: Sequence[Any] = (),+) -> ChainRuntime | None:+ """Build the route's sub-agent worker chain, or ``None`` when unset.++ The worker is a plain passthrough to one target: delegated work is served directly+ rather than re-routed through the route's own policy.+ """+ subagent_raw = route.get("subagent_target")+ if subagent_raw is None:+ return None+ return build_tier_passthrough_switchyard(+ _target_value(+ subagent_raw,+ target_defaults,+ default_id=f"{model_id}#subagent",+ where=f"route {model_id!r} subagent_target",+ ),+ stats,+ enable_stats=_optional_bool(route.get("enable_stats"), default=True),+ extra_request_processors=pre_routing_request_processors,+ extra_response_processors=extra_response_processors,+ )+++def _build_route_chain(+ model_id: str,+ route: Mapping[str, object],+ route_type: str,+ target_defaults: Mapping[str, object],+ stats: StatsAccumulator,+ pre_routing_request_processors: Sequence[Any] = (),+ extra_response_processors: Sequence[Any] = (),) -> ChainRuntime:if route_type in ("model", "passthrough"):# Both kinds resolve to a single-tier passthrough chain — same shape the@@ -1468,7 +1537,7 @@ def _validate_route_keys(route_type: str,) -> None:where = f"route {model_id!r}"- _validate_allowed_keys(route, _ROUTE_KEYS_BY_TYPE[route_type], where)+ _validate_allowed_keys(route, _ROUTE_KEYS_BY_TYPE[route_type] | _ROUTE_ENVELOPE_KEYS, where)if "defaults" in route:defaults = _require_mapping(route["defaults"], f"{where}.defaults")_validate_allowed_keys(diff --git a/switchyard/lib/cost_estimator.py b/switchyard/lib/cost_estimator.pyindex f47397497..5cdb14888 100644--- a/switchyard/lib/cost_estimator.py+++ b/switchyard/lib/cost_estimator.py@@ -123,6 +123,19 @@ MODEL_PRICING: dict[str, ModelPriceData] = {"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+ # SiliconFlow's published GLM-5.2 serverless tier (verified 2026-07-27),+ # carried so benchmark arms can be compared against commercial models on a+ # common basis — "what this traffic would have cost at market rates", not+ # what we are billed. Provider rates vary about 2x (OpenRouter lists+ # $0.76/$2.42), so treat the absolute number as indicative, not exact.+ # OpenAI wire format and no documented cache-write premium, so+ # cache_write = input.+ "glm-5.2-fp8": ModelPriceData(+ input=1.40, output=4.40, cached=0.26, cache_write=1.40,+ ),# 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@@ -179,7 +192,13 @@ MODEL_PRICING: dict[str, ModelPriceData] = {# --- 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).+ # 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,),@@ -208,6 +227,9 @@ MODEL_PRICING: dict[str, ModelPriceData] = {"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,),@@ -221,6 +243,9 @@ MODEL_PRICING: dict[str, 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,),diff --git a/switchyard/lib/profiles/subagent_override.py b/switchyard/lib/profiles/subagent_override.pynew file mode 100644index 000000000..d3c69e42e--- /dev/null+++ b/switchyard/lib/profiles/subagent_override.py@@ -0,0 +1,57 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++"""Route delegated sub-agent requests to a fixed worker runtime."""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from switchyard.lib.request_metadata import CTX_PROFILE_REQUEST_HEADERS+from switchyard_rust.core import is_subagent_request++if TYPE_CHECKING:+ from switchyard.lib.proxy_context import ProxyContext+ from switchyard.lib.route_table import ChainRuntime+ from switchyard_rust.core import ChatRequest+++class SubagentOverrideRuntime:+ """Wrap a runtime, sending delegated sub-agent work to ``worker`` instead.++ Normal traffic runs the wrapped runtime unchanged. A request whose headers carry a+ delegated sub-agent signal runs ``worker`` — a passthrough to the route's configured+ ``subagent_target``. The override never rewrites the request or response, and a worker+ failure surfaces as a normal target error rather than falling back to the wrapped+ runtime.++ Detection is :func:`~switchyard_rust.profiles.is_subagent_request`, the protocol+ crate's canonical policy, so harness maintenance turns (Codex ``compact``) stay on+ normal routing and every engine agrees on what counts as delegated work.+ """++ def __init__(self, inner: ChainRuntime, worker: ChainRuntime) -> None:+ self._inner = inner+ self._worker = worker++ def _branch(self, ctx: ProxyContext | None) -> ChainRuntime:+ """Select the worker for delegated work, else the wrapped runtime.++ Without a context there are no retained headers to read, so the request cannot be+ identified as delegated and routes normally.+ """+ if ctx is None:+ return self._inner+ headers = ctx.metadata.get(CTX_PROFILE_REQUEST_HEADERS) or {}+ return self._worker if is_subagent_request(headers) else self._inner++ async def call(self, request: ChatRequest, *, ctx: ProxyContext | None = None) -> Any:+ """Execute one request through the branch its headers select."""+ return await self._branch(ctx).call(request, ctx=ctx)++ def iter_components(self) -> list[Any]:+ """Return both branches' lifecycle components in startup order."""+ return [*self._inner.iter_components(), *self._worker.iter_components()]+++__all__ = ["SubagentOverrideRuntime"]diff --git a/switchyard/libsy/algorithms.py b/switchyard/libsy/algorithms.pyindex d5f2e64a9..434526feb 100644--- a/switchyard/libsy/algorithms.py+++ b/switchyard/libsy/algorithms.py@@ -5,6 +5,5 @@from switchyard_rust.libsy import noop as noopfrom switchyard_rust.libsy import random as random-from switchyard_rust.libsy import subagent_override as subagent_override-__all__ = ["noop", "random", "subagent_override"]+__all__ = ["noop", "random"]diff --git a/switchyard_rust/core.py b/switchyard_rust/core.pyindex 59cbd0a5a..551fa3aa3 100644--- a/switchyard_rust/core.py+++ b/switchyard_rust/core.py@@ -582,8 +582,12 @@ if TYPE_CHECKING:body: Mapping[str, Any] | JsonValue, depth: int = 0) -> str | None: ...+ def is_subagent_request(headers: Mapping[str, str]) -> bool: ...+def __getattr__(name: str) -> object:+ if name == "is_subagent_request":+ return _load_native().is_subagent_requestif name == "SessionCache":return _load_native().SessionCacheif name == "session_key_from_body":@@ -801,6 +805,7 @@ __all__ = ["SwitchyardRuntimeError","SwitchyardUnsupportedRequestTypeError","SwitchyardUpstreamError",+ "is_subagent_request","request_type_enum","request_type_matches","request_type_value",diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex ff6c3123e..745309062 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -10,9 +10,7 @@ from typing import TYPE_CHECKING, Any, Protocolfrom switchyard_rust.core import _load_native-_EXPORTS = frozenset(- {"Algorithm", "LibsyError", "LlmTarget", "noop", "random", "subagent_override"}-)+_EXPORTS = frozenset({"Algorithm", "LibsyError", "LlmTarget", "noop", "random"})class LlmClient(Protocol):@@ -53,8 +51,6 @@ if TYPE_CHECKING:def random(targets: Sequence[LlmTarget]) -> Algorithm: ...- def subagent_override(inner: Algorithm, worker: LlmTarget) -> Algorithm: ...-def __getattr__(name: str) -> object:if name in _EXPORTS:diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.pyindex 504ab3cd9..b2014a33a 100644--- a/tests/test_libsy_minimal_bindings.py+++ b/tests/test_libsy_minimal_bindings.py@@ -99,37 +99,6 @@ async def test_invalid_request_is_rejected_at_the_boundary() -> None:)-async def test_subagent_override_routes_marked_work_to_the_worker() -> None:- orchestrator = EchoClient("orchestrator")- worker = EchoClient("worker")- algorithm = algorithms.subagent_override(- algorithms.random([LlmTarget("orchestrator", orchestrator)]),- LlmTarget("worker", worker),- )-- # No headers: the wrapped algorithm serves the request.- _, response = await algorithm.run(request_body())- assert response["model"] == "orchestrator"-- # Claude Code child-agent lineage routes to the fixed worker target.- decisions, response = await algorithm.run(- request_body(),- headers={- "x-claude-code-session-id": "root",- "x-claude-code-agent-id": "child-1",- },- )- assert response["model"] == "worker"- assert decisions[-1]["selected_model"] == "worker"-- # Harness maintenance stays on the wrapped algorithm.- _, response = await algorithm.run(- request_body(), headers={"x-openai-subagent": "compact"}- )- assert response["model"] == "orchestrator"- assert len(worker.calls) == 1--async def test_client_failure_becomes_libsy_error() -> None:class FailingClient:async def call(self, request: dict[str, Any]) -> dict[str, Any]:diff --git a/tests/test_subagent_routing.py b/tests/test_subagent_routing.pynew file mode 100644index 000000000..edd82e466--- /dev/null+++ b/tests/test_subagent_routing.py@@ -0,0 +1,137 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++"""Serve-path sub-agent routing: the ``subagent_target`` route envelope key."""++from __future__ import annotations++from typing import Any++import pytest++from switchyard.cli.route_bundle import (+ RouteBundle,+ RouteBundleConfigError,+ build_table_from_bundle,+)+from switchyard.lib.profiles.subagent_override import SubagentOverrideRuntime+from switchyard.lib.request_metadata import CTX_PROFILE_REQUEST_HEADERS+from switchyard_rust.core import is_subagent_request+++class _RecordingRuntime:+ """A ChainRuntime stand-in that records the calls routed to it."""++ def __init__(self, name: str) -> None:+ self.name = name+ self.calls = 0++ async def call(self, request: Any, *, ctx: Any = None) -> str:+ self.calls += 1+ return self.name++ def iter_components(self) -> list[Any]:+ return [self.name]+++class _Ctx:+ """Minimal ProxyContext stand-in exposing only the retained header map."""++ def __init__(self, headers: dict[str, str] | None = None) -> None:+ self.metadata: dict[str, Any] = {}+ if headers is not None:+ self.metadata[CTX_PROFILE_REQUEST_HEADERS] = headers+++# --- detection policy -----------------------------------------------------------------+++def test_detection_matches_the_protocol_policy() -> None:+ # Claude Code child-agent lineage is delegated work.+ assert is_subagent_request(+ {"x-claude-code-session-id": "root", "x-claude-code-agent-id": "child-1"}+ )+ # Codex delegated-work kinds.+ assert is_subagent_request({"x-openai-subagent": "review"})+ # Harness maintenance is sub-agent lineage but NOT delegated work.+ assert not is_subagent_request({"x-openai-subagent": "compact"})+ # Explicit opt-out wins.+ assert not is_subagent_request({"x-switchyard-is-subagent": "false"})+ # Ordinary traffic.+ assert not is_subagent_request({})+++# --- runtime wrapper ------------------------------------------------------------------+++async def test_delegated_work_goes_to_the_worker() -> None:+ inner, worker = _RecordingRuntime("inner"), _RecordingRuntime("worker")+ runtime = SubagentOverrideRuntime(inner, worker)++ served = await runtime.call(+ object(),+ ctx=_Ctx({"x-claude-code-session-id": "s", "x-claude-code-agent-id": "child-1"}),+ )+ assert served == "worker"+ assert (inner.calls, worker.calls) == (0, 1)+++async def test_normal_traffic_runs_the_wrapped_runtime() -> None:+ inner, worker = _RecordingRuntime("inner"), _RecordingRuntime("worker")+ runtime = SubagentOverrideRuntime(inner, worker)++ assert await runtime.call(object(), ctx=_Ctx({})) == "inner"+ # A maintenance turn carries lineage but is not delegated work.+ assert await runtime.call(object(), ctx=_Ctx({"x-openai-subagent": "compact"})) == "inner"+ assert (inner.calls, worker.calls) == (2, 0)+++async def test_missing_context_routes_normally() -> None:+ inner, worker = _RecordingRuntime("inner"), _RecordingRuntime("worker")+ runtime = SubagentOverrideRuntime(inner, worker)++ # No context means no retained headers, so nothing identifies the request.+ assert await runtime.call(object(), ctx=None) == "inner"+ assert worker.calls == 0+++def test_components_span_both_branches() -> None:+ runtime = SubagentOverrideRuntime(_RecordingRuntime("inner"), _RecordingRuntime("worker"))+ assert runtime.iter_components() == ["inner", "worker"]+++# --- route bundle wiring --------------------------------------------------------------+++def _bundle(route: dict[str, Any]) -> RouteBundle:+ return RouteBundle(+ routes={"my-route": route},+ defaults={"api_key": "sk-test", "base_url": "https://example.invalid/v1"},+ )+++def test_subagent_target_wraps_any_route_type() -> None:+ table = build_table_from_bundle(+ _bundle({+ "type": "model",+ "target": {"model": "strong-model"},+ "subagent_target": {"model": "worker-model"},+ })+ )+ assert isinstance(table.lookup_switchyard("my-route"), SubagentOverrideRuntime)+++def test_routes_without_the_key_are_unwrapped() -> None:+ table = build_table_from_bundle(_bundle({"type": "model", "target": {"model": "strong-model"}}))+ assert not isinstance(table.lookup_switchyard("my-route"), SubagentOverrideRuntime)+++def test_unknown_route_keys_are_still_rejected() -> None:+ with pytest.raises(RouteBundleConfigError, match="subagent_targets"):+ build_table_from_bundle(+ _bundle({+ "type": "model",+ "target": {"model": "strong-model"},+ "subagent_targets": {"model": "typo"},+ })+ )