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(vgr): add bounded verification runtime (#718)
GDRSf106ed2e76dc
diff --git a/crates/libsy/src/algorithms/vgr.rs b/crates/libsy/src/algorithms/vgr.rsindex 7e6d5eab2..0244ad297 100644--- a/crates/libsy/src/algorithms/vgr.rs+++ b/crates/libsy/src/algorithms/vgr.rs@@ -9,21 +9,75 @@//! a weaker regime than the default one; unsupported content and missing//! evidence select [`Branch::Unknown`], which never commits.-#![allow(dead_code)]+use std::sync::Arc;use switchyard_protocol::Request;use self::text::ToolRecord;+use crate::Result;+use crate::algorithms::fall_through::FallThrough;+use crate::algorithms::util::affinity::AffinityRouter;+use crate::core::algorithm::{Algorithm, Driver, RoutingOutcome};+mod config;mod decide;mod readout;mod render;mod rungs;+mod runtime;+mod safety;mod text;+pub use config::{ACTIVE_APPROVAL, ServingMode, Targets, VgrConfig};+pub use safety::{BreakerConfig, KillSwitch};+#[cfg(test)]mod tests;+/// A verification-gated route between a local and a capable tier.+pub struct Vgr {+ route: FallThrough<runtime::VgrState>,+}++impl Vgr {+ /// Validates and constructs a verification-gated route.+ pub fn new(config: VgrConfig) -> Result<Self> {+ config.validate()?;+ let cloud = config.targets.cloud.clone();+ // Every local turn re-enters verification; an escalation holds until the+ // next user turn.+ let turn_affinity = Arc::new(+ AffinityRouter::new()+ .with_release_on_user_turn()+ .with_latch_only([cloud.clone()]),+ );+ let classifier = Arc::new(runtime::VgrClassifier {+ breaker: safety::CircuitBreaker::new(config.breaker),+ config,+ });+ let route = FallThrough::new_with_state()+ .with_name("vgr")+ .with_processor(turn_affinity.clone())+ .with_classifier(turn_affinity)+ .with_classifier(classifier);+ Ok(Self { route })+ }+}++#[async_trait::async_trait]+impl Algorithm for Vgr {+ fn name(&self) -> &str {+ "vgr"+ }++ async fn route(self: Arc<Self>, driver: Driver, request: Request) -> Result<RoutingOutcome> {+ let mut outcome = self.route.execute(driver, request).await?;+ // Local answers are already buffered; cloud decisions cannot fall back to local.+ outcome.selected_model_ids.truncate(1);+ Ok(outcome)+ }+}+/// The verification regime a request's capabilities license.#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]enum Branch {diff --git a/crates/libsy/src/algorithms/vgr/config.rs b/crates/libsy/src/algorithms/vgr/config.rsnew file mode 100644index 000000000..d171a3913--- /dev/null+++ b/crates/libsy/src/algorithms/vgr/config.rs@@ -0,0 +1,112 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++use std::time::Duration;++use switchyard_protocol::ModelId;++use super::safety::{BreakerConfig, KillSwitch};+use crate::{LibsyError, Result};++/// Required attestation for live local commits.+pub const ACTIVE_APPROVAL: &str = "prospective-validation-and-canary-approved";++/// Authority granted to VGR decisions.+#[derive(Clone, Debug, Default, Eq, PartialEq)]+pub enum ServingMode {+ /// Always serves cloud without producing an attempt.+ #[default]+ Off,+ /// Serves decisions, for isolated measurement.+ Evaluate,+ /// Decides but always serves cloud.+ Shadow,+ /// Serves decisions after operator approval.+ Active {+ /// Operator approval attestation.+ approval: String,+ },+}++/// Targets used by a VGR route.+#[derive(Clone, Debug)]+pub struct Targets {+ /// Tier that produces the candidate attempt.+ pub local: ModelId,+ /// Tier used when the candidate is not licensed.+ pub cloud: ModelId,+ /// Local verifier, defaulting to `local`.+ pub judge: Option<ModelId>,+ /// Capable-tier verifier; unset removes the cloud confirmation rungs.+ pub cloud_judge: Option<ModelId>,+}++/// VGR runtime configuration.+#[derive(Clone, Debug)]+pub struct VgrConfig {+ /// Completion and verifier targets.+ pub targets: Targets,+ /// Authority granted to routing decisions.+ pub mode: ServingMode,+ /// Budget for one turn's attempt and verification.+ pub deadline: Duration,+ /// Optional live stop controlled by the operator.+ pub kill_switch: Option<KillSwitch>,+ /// Local endpoint breaker tuning.+ pub breaker: BreakerConfig,+ /// Whether a cheap typing call selects a verification regime.+ pub task_typing: bool,+ /// Whether the local tier accepts image content.+ pub local_supports_images: bool,+ /// Lets a long agentic run with earlier tool errors commit on a capable-tier+ /// confirmation once it ends in this many consecutive clean tool results.+ pub confirmed_recovery_min_clean_tail: Option<u32>,+}++impl VgrConfig {+ /// Creates an off-by-default route between local and capable tiers.+ pub fn new(local: ModelId, cloud: ModelId) -> Self {+ Self {+ targets: Targets {+ local,+ cloud,+ judge: None,+ cloud_judge: None,+ },+ mode: ServingMode::Off,+ deadline: Duration::from_secs(30),+ kill_switch: None,+ breaker: BreakerConfig::default(),+ task_typing: true,+ local_supports_images: false,+ confirmed_recovery_min_clean_tail: None,+ }+ }++ pub(super) fn validate(&self) -> Result<()> {+ if self.deadline.is_zero() || self.breaker.threshold == 0 {+ return Err(LibsyError::AlgorithmError {+ message: "vgr deadline and breaker threshold must be non-zero".into(),+ });+ }+ if let ServingMode::Active { approval } = &self.mode+ && approval != ACTIVE_APPROVAL+ {+ return Err(LibsyError::AlgorithmError {+ message: format!(+ "vgr active mode requires approval attestation {ACTIVE_APPROVAL:?}"+ ),+ });+ }+ Ok(())+ }++ pub(super) fn judge(&self) -> &ModelId {+ self.targets.judge.as_ref().unwrap_or(&self.targets.local)+ }++ pub(super) fn confirmed_min_clean_tail(&self) -> Option<i32> {+ self.confirmed_recovery_min_clean_tail+ .map(|tail| i32::try_from(tail.max(1)).unwrap_or(i32::MAX))+ }+}diff --git a/crates/libsy/src/algorithms/vgr/runtime.rs b/crates/libsy/src/algorithms/vgr/runtime.rsnew file mode 100644index 000000000..706af49d1--- /dev/null+++ b/crates/libsy/src/algorithms/vgr/runtime.rs@@ -0,0 +1,372 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! The classifier that runs one verification-gated turn.+//!+//! A proposed tool call is judged against the session's trajectory; a final+//! answer is typed, judged by rungs that run cheapest-first and stop once the+//! decision is settled, and then committed or escalated. Every call is bounded+//! by what is left of the turn's deadline, and a call that fails or times out+//! is evidence never gathered, which does not commit.++use std::time::{Duration, Instant};++use async_trait::async_trait;+use switchyard_protocol::{AggLlmResponse, ContentBlock, ModelId, Request, Response, StopReason};++use super::config::{ServingMode, VgrConfig};+use super::decide::{self, AgenticRun, Route, Signals, Tri};+use super::rungs::{self, Question};+use super::safety::{CircuitBreaker, endpoint_failure, fallback_eligible};+use super::{Branch, Capabilities, TaskType, derive_capabilities, readout, text};+use crate::algorithms::util::buffered_response::buffer_response;+use crate::algorithms::util::decisive;+use crate::core::algorithm::Driver;+use crate::core::classifier::{Classification, Classifier};+use crate::{LibsyError, Result};++#[derive(Default)]+pub(super) struct VgrState {+ pub(super) turn_streak: u32,+ pub(super) turn_latched: bool,+}++struct RequestContext<'a> {+ driver: &'a Driver,+ request: &'a Request,+ started: Instant,+}++/// Consecutive escalation votes that latch a session to the capable tier.+const TURN_CONFIRMATIONS: u32 = 2;+const TURN_ESCALATE_AT: f64 = 0.5;++type Scored = (Classification, Option<Response>);++pub(super) struct VgrClassifier {+ pub(super) config: VgrConfig,+ pub(super) breaker: CircuitBreaker,+}++#[async_trait]+impl Classifier<VgrState> for VgrClassifier {+ async fn score(+ &self,+ state: &mut VgrState,+ request: &mut Request,+ driver: &Driver,+ ) -> Result<Scored> {+ let started = Instant::now();+ let local = &self.config.targets.local;+ let short_circuit = if self.config.mode == ServingMode::Off {+ Some("mode_off")+ } else if self+ .config+ .kill_switch+ .as_ref()+ .is_some_and(|switch| switch.is_engaged())+ {+ Some("kill_switch")+ } else if state.turn_latched {+ Some("turn_verification_latched")+ } else if !self.config.local_supports_images && request_has_image(request) {+ Some("local_image_unsupported")+ } else {+ None+ };+ if let Some(reason) = short_circuit {+ return Ok(self.escalate(driver, reason, None));+ }++ let Some(budget) = self.remaining(started) else {+ return Ok(self.escalate(driver, "local_timed_out", None));+ };+ let Some(trial) = self.breaker.attempt() else {+ return Ok(self.escalate(driver, "breaker_open", None));+ };+ let attempted = tokio::time::timeout(budget, async {+ let response = driver+ .call_model(request.clone(), vec![local.clone()])+ .await?;+ buffer_response(local.as_str(), response).await+ })+ .await;+ let buffered = match attempted {+ Ok(Ok(buffered)) => {+ trial.success();+ buffered+ }+ Ok(Err(error)) => {+ if endpoint_failure(&error) {+ trial.failure();+ }+ if !fallback_eligible(&error) {+ return Err(error);+ }+ return Ok(self.escalate(driver, "local_unavailable", None));+ }+ Err(_) => {+ trial.failure();+ return Ok(self.escalate(driver, "local_timed_out", None));+ }+ };++ let context = RequestContext {+ driver,+ request,+ started,+ };+ if rungs::has_tool_call(&buffered.agg) {+ if !tool_use_is_complete(&buffered.agg) {+ return Ok(self.escalate(driver, "malformed_tool_call", None));+ }+ if self.verify_turn(&context, &buffered.agg, state).await {+ return Ok(self.escalate(driver, "turn_verification_escalated", None));+ }+ if self.config.mode == ServingMode::Shadow {+ return Ok(self.escalate(driver, "turn_verification_complete", None));+ }+ log(driver, "turn_verification_complete", None, Route::Local);+ return Ok((decisive(local), Some(buffered.into_response())));+ }++ let attempt = rungs::response_text(&buffered.agg).unwrap_or_default();+ let task_type = self.type_task(&context).await;+ let caps = derive_capabilities(request, &attempt, task_type);+ let signals = self.gather(&context, &caps).await;+ let route = decide::decide(&caps, &signals, self.config.confirmed_min_clean_tail());+ if route == Route::Cloud || self.config.mode == ServingMode::Shadow {+ return Ok(self.escalate(driver, "decided", Some(caps.branch)));+ }+ log(driver, "decided", Some(caps.branch), Route::Local);+ Ok((decisive(local), Some(buffered.into_response())))+ }+}++impl VgrClassifier {+ fn escalate(&self, driver: &Driver, reason: &'static str, branch: Option<Branch>) -> Scored {+ log(driver, reason, branch, Route::Cloud);+ (decisive(&self.config.targets.cloud), None)+ }++ /// Judges one proposed tool call; `true` escalates the rest of the session.+ async fn verify_turn(+ &self,+ context: &RequestContext<'_>,+ proposed: &AggLlmResponse,+ state: &mut VgrState,+ ) -> bool {+ let mut call = rungs::build_request(+ Question::TurnTrajectory,+ &rungs::turn_view(context.request, proposed),+ readout::MAX_OUTPUT_TOKENS,+ context.request.metadata.clone(),+ );+ readout::request_logprobs(&mut call);+ let judge = self.config.judge();+ let probability = match self.call(context, call, judge).await {+ None => return false,+ Some(Ok(agg)) => readout::p_yes(&agg),+ // Verification fails open, unless the local endpoint itself is down.+ Some(Err(error)) => {+ if *judge == self.config.targets.local && endpoint_failure(&error) {+ self.breaker.failure();+ state.turn_latched = true;+ return true;+ }+ return false;+ }+ };+ let Some(probability) = probability else {+ return false;+ };+ if probability < TURN_ESCALATE_AT {+ state.turn_streak = 0;+ return false;+ }+ state.turn_streak = state.turn_streak.saturating_add(1);+ let streak = state.turn_streak;+ if streak >= TURN_CONFIRMATIONS {+ state.turn_latched = true;+ }+ streak >= TURN_CONFIRMATIONS+ }++ /// Types the request; abstains, selecting the default regime, on any failure.+ async fn type_task(&self, context: &RequestContext<'_>) -> Option<TaskType> {+ if !self.config.task_typing {+ return None;+ }+ let (turns, _) = text::turns(context.request);+ let task = text::user_task_text(&turns);+ if task.trim().is_empty() {+ return None;+ }+ let call = rungs::build_typing_request(task, context.request.metadata.clone());+ let agg = self.call(context, call, self.config.judge()).await?.ok()?;+ rungs::parse_task_type(&agg)+ }++ /// Gathers evidence cheapest-first, stopping once the decision commits.+ async fn gather(&self, context: &RequestContext<'_>, caps: &Capabilities) -> Signals {+ let mut signals = Signals::default();+ let branch = caps.branch;+ let confirmed = self.config.confirmed_min_clean_tail();+ let run = (branch == Branch::Agentic).then(|| decide::agentic_run(caps, confirmed));+ let (Some(judged), false) = (+ caps.transcript.as_deref(),+ matches!(branch, Branch::Coding | Branch::Unknown) || run == Some(AgenticRun::Vetoed),+ ) else {+ return signals;+ };+ let settled = |signals: &Signals| decide::decide(caps, signals, confirmed) == Route::Local;+ let cloud_confirms = run == Some(AgenticRun::ConfirmedRecovery);+ let local = self.config.judge();+ let ask = |target, question, max_output_tokens| {+ self.ask(context, target, question, judged, max_output_tokens)+ };++ signals.readout = self.readout(context, judged).await;+ if settled(&signals) {+ return signals;+ }+ if !(cloud_confirms && decide::locally_verified(branch, &signals)) {+ signals.deliberation = Some(+ ask(+ local,+ Question::Deliberation,+ rungs::LOCAL_DELIBERATION_MAX_OUTPUT_TOKENS,+ )+ .await,+ );+ if settled(&signals) {+ return signals;+ }+ }+ let Some(cloud) = self.config.targets.cloud_judge.as_ref() else {+ return signals;+ };+ let cloud_ask = |question| ask(cloud, question, rungs::DELIBERATION_MAX_OUTPUT_TOKENS);+ if cloud_confirms {+ if decide::locally_verified(branch, &signals) {+ signals.cloud_judge = Some(cloud_ask(Question::Evidence).await);+ }+ return signals;+ }+ match branch {+ Branch::Answer => {+ signals.answer_verifier = Some(cloud_ask(Question::Answer).await);+ if !settled(&signals) {+ signals.evidence_verifier = Some(cloud_ask(Question::Evidence).await);+ }+ }+ Branch::Chat => {+ signals.cloud_judge = Some(cloud_ask(Question::Evidence).await);+ // Asked only once the first affirms, so a refutation costs one call.+ if signals.cloud_judge == Some(Tri::Yes) {+ signals.evidence_confirm = Some(cloud_ask(Question::Answer).await);+ }+ }+ _ => {}+ }+ signals+ }++ async fn readout(&self, context: &RequestContext<'_>, judged: &str) -> Option<f64> {+ let mut call = rungs::build_request(+ Question::Evidence,+ judged,+ readout::MAX_OUTPUT_TOKENS,+ context.request.metadata.clone(),+ );+ readout::request_logprobs(&mut call);+ let agg = self.call(context, call, self.config.judge()).await?.ok()?;+ readout::p_yes(&agg)+ }++ async fn ask(+ &self,+ context: &RequestContext<'_>,+ target: &ModelId,+ question: Question,+ judged: &str,+ max_output_tokens: u64,+ ) -> Tri {+ let call = rungs::build_request(+ question,+ judged,+ max_output_tokens,+ context.request.metadata.clone(),+ );+ match self.call(context, call, target).await {+ Some(Ok(agg)) => rungs::parse_verdict(&agg),+ _ => Tri::Unknown,+ }+ }++ /// One verifier call inside the remaining budget; `None` once it is spent.+ async fn call(+ &self,+ context: &RequestContext<'_>,+ call: Request,+ target: &ModelId,+ ) -> Option<Result<AggLlmResponse>> {+ let budget = self.remaining(context.started)?;+ let outcome = tokio::time::timeout(budget, async {+ let response = context+ .driver+ .call_model(call, vec![target.clone()])+ .await?;+ response+ .llm_response+ .into_agg()+ .await+ .map_err(|source| LibsyError::client_call(target.clone(), source))+ })+ .await;+ outcome.ok()+ }++ fn remaining(&self, started: Instant) -> Option<Duration> {+ self.config.deadline.checked_sub(started.elapsed())+ }+}++fn log(driver: &Driver, reason: &'static str, branch: Option<Branch>, served: Route) {+ driver.set_evidence(serde_json::json!({+ "source": "vgr",+ "reason_code": reason,+ "verdict": if served == Route::Local { "local" } else { "cloud" },+ "branch": branch.map(|branch| format!("{branch:?}")),+ }));+ tracing::info!(target: "libsy", reason, branch = ?branch, served = ?served, "vgr decision");+}++fn tool_use_is_complete(response: &AggLlmResponse) -> bool {+ response.outputs.iter().all(|output| {+ output.stop_reason != Some(StopReason::MaxTokens)+ && output.content.iter().all(|block| {+ !matches!(block, ContentBlock::ToolCall(call) if call.arguments.is_string())+ })+ })+}++/// Whether a request carries image content directly or inside a tool result.+fn request_has_image(request: &Request) -> bool {+ fn has_image(block: &ContentBlock) -> bool {+ match block {+ ContentBlock::Image { .. } => true,+ ContentBlock::ToolResult(result) => result.content.iter().any(has_image),+ _ => false,+ }+ }+ let llm = &request.llm_request;+ llm.instructions+ .iter()+ .flat_map(|instruction| &instruction.content)+ .chain(llm.messages.iter().flat_map(|message| &message.content))+ .any(has_image)+}++#[cfg(test)]+mod tests;diff --git a/crates/libsy/src/algorithms/vgr/runtime/tests.rs b/crates/libsy/src/algorithms/vgr/runtime/tests.rsnew file mode 100644index 000000000..9a5a45cfb--- /dev/null+++ b/crates/libsy/src/algorithms/vgr/runtime/tests.rs@@ -0,0 +1,400 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++use std::sync::Arc;+use std::sync::atomic::{AtomicUsize, Ordering};++use serde_json::json;+use switchyard_protocol::{+ AggLlmResponse, Category, ContentBlock, FormatId, LlmClientError, LlmResponse, Message,+ Metadata, ModelId, Request, Response, ResponseOutput, Role, StopReason, ToolCall, WireFormat,+};++use super::super::config::{ACTIVE_APPROVAL, ServingMode, VgrConfig};+use super::super::tests::{call, request, result};+use crate::Result;+use crate::algorithms::vgr::Vgr;+use crate::core::algorithm::Algorithm;+use crate::core::testing::{category_models, reply, test_drive_with_models};++fn route(configure: impl FnOnce(&mut VgrConfig)) -> Result<Arc<dyn Algorithm>> {+ let mut config = VgrConfig::new(ModelId::new("local"), ModelId::new("cloud"));+ config.targets.judge = Some(ModelId::new("judge"));+ config.targets.cloud_judge = Some(ModelId::new("cloud-judge"));+ config.mode = ServingMode::Active {+ approval: ACTIVE_APPROVAL.into(),+ };+ config.task_typing = false;+ configure(&mut config);+ Ok(Arc::new(Vgr::new(config)?))+}++fn session(messages: Vec<Message>) -> Request {+ let mut request = request(messages);+ request.metadata = Some(Metadata {+ session_id: Some("session-1".into()),+ ..Metadata::default()+ });+ request+}++fn agg(response: AggLlmResponse) -> Response {+ Response {+ llm_response: LlmResponse::Agg(response),+ metadata: None,+ upstream_headers: http::HeaderMap::new(),+ }+}++fn tool_call(arguments: serde_json::Value, stop_reason: StopReason) -> Response {+ agg(AggLlmResponse {+ outputs: vec![ResponseOutput {+ role: Role::Assistant,+ content: vec![ContentBlock::ToolCall(ToolCall {+ id: "next".into(),+ name: "bash".into(),+ arguments,+ })],+ url_citations: Vec::new(),+ stop_reason: Some(stop_reason),+ }],+ ..Default::default()+ })+}++/// A verifier reply whose first token puts probability `p` on "yes".+fn scored(p: f64) -> Response {+ let mut response = AggLlmResponse::default();+ response.preservation.responses.insert(+ FormatId::from(WireFormat::OpenAiChat),+ json!({"choices": [{"logprobs": {"content": [{"top_logprobs": [+ {"token": "yes", "logprob": p.ln()},+ {"token": "no", "logprob": (1.0 - p).ln()}+ ]}]}}]}),+ );+ agg(response)+}++#[derive(Default)]+struct Calls(AtomicUsize, AtomicUsize);++async fn drive(+ route: &Arc<dyn Algorithm>,+ request: Request,+ calls: Arc<Calls>,+ local: fn() -> Response,+ judge_p: f64,+) -> Result<String> {+ let (selected, _) = test_drive_with_models(+ Arc::clone(route),+ request,+ category_models(Category::Any, &["local", "cloud"]),+ move |target: ModelId, _| {+ let calls = Arc::clone(&calls);+ async move {+ match target.as_str() {+ "local" => calls.0.fetch_add(1, Ordering::Relaxed),+ "cloud-judge" => calls.1.fetch_add(1, Ordering::Relaxed),+ _ => 0,+ };+ Ok(match target.as_str() {+ "local" => local(),+ "judge" => scored(judge_p),+ "cloud-judge" => reply("yes"),+ _ => reply("cloud answer"),+ })+ }+ },+ )+ .await?;+ Ok(selected.to_string())+}++fn complete_call() -> Response {+ tool_call(json!({"command": "ls"}), StopReason::ToolUse)+}++#[tokio::test]+async fn malformed_tool_calls_escalate_and_complete_ones_are_judged() -> Result<()> {+ let route = route(|_| {})?;+ let calls = Arc::new(Calls::default());+ let truncated = || tool_call(json!(r#"{"command":"l"#), StopReason::MaxTokens);+ let task = || session(vec![Message::text(Role::User, "list files")]);+ assert_eq!(+ drive(&route, task(), calls.clone(), truncated, 0.0).await?,+ "cloud"+ );+ assert_eq!(+ drive(&route, task(), calls, complete_call, 0.1).await?,+ "local"+ );+ Ok(())+}++#[tokio::test]+async fn a_truncated_local_attempt_is_judged_before_it_escalates() -> Result<()> {+ let route = route(|config| config.targets.judge = None)?;+ let calls = Arc::new(Calls::default());+ let task = session(vec![Message::text(Role::User, "explain quicksort")]);+ let cut_off = || {+ let mut response = reply("Quicksort picks a pivot, then recurses because");+ if let LlmResponse::Agg(agg) = &mut response.llm_response {+ agg.outputs[0].stop_reason = Some(StopReason::MaxTokens);+ }+ response+ };+ let selected = drive(&route, task, calls.clone(), cut_off, 0.0).await?;+ assert_eq!(selected, "cloud");+ // Attempt, readout and deliberation; read as absent, only the attempt runs.+ assert_eq!(calls.0.load(Ordering::Relaxed), 3);+ Ok(())+}++#[tokio::test]+async fn two_consecutive_escalation_votes_latch_the_session() -> Result<()> {+ let route = route(|_| {})?;+ let calls = Arc::new(Calls::default());+ let task = || session(vec![Message::text(Role::User, "fix the build")]);+ assert_eq!(+ drive(&route, task(), calls.clone(), complete_call, 0.9).await?,+ "local"+ );+ assert_eq!(+ drive(&route, task(), calls.clone(), complete_call, 0.9).await?,+ "cloud"+ );+ assert_eq!(calls.0.load(Ordering::Relaxed), 2);++ // Latched past the user turn: no further local attempt is produced.+ assert_eq!(+ drive(&route, task(), calls.clone(), complete_call, 0.0).await?,+ "cloud"+ );+ assert_eq!(calls.0.load(Ordering::Relaxed), 2);+ Ok(())+}++#[tokio::test]+async fn final_answers_commit_only_on_a_verified_clean_record() -> Result<()> {+ let answer = || reply("the build passes");+ let run = |tool_output: &str| {+ session(vec![+ Message::text(Role::User, "fix the build"),+ call("c1"),+ result("c1", tool_output),+ ])+ };+ let calls = Arc::new(Calls::default());+ let clean = route(|_| {})?;+ assert_eq!(+ drive(&clean, run("ok"), calls.clone(), answer, 0.3).await?,+ "local"+ );+ assert_eq!(+ drive(&clean, run("ok"), calls.clone(), answer, 0.1).await?,+ "cloud"+ );++ // A failure longer ago than the clean tail is forgiven only on the capable judge.+ let mut long = vec![Message::text(Role::User, "fix the build")];+ long.extend([call("e"), result("e", r#"{"error": "missing file"}"#)]);+ for index in 0..101 {+ let id = format!("c{index}");+ long.extend([call(&id), result(&id, "ok")]);+ }+ assert_eq!(+ drive(&clean, session(long.clone()), calls.clone(), answer, 1.0).await?,+ "cloud"+ );+ assert_eq!(calls.1.load(Ordering::Relaxed), 0);+ let confirmed = route(|config| config.confirmed_recovery_min_clean_tail = Some(1))?;+ assert_eq!(+ drive(&confirmed, session(long), calls.clone(), answer, 1.0).await?,+ "local"+ );+ assert_eq!(calls.1.load(Ordering::Relaxed), 1);+ Ok(())+}++#[tokio::test]+async fn an_unavailable_local_tier_escalates_and_other_failures_surface() -> Result<()> {+ let route = route(|_| {})?;+ for (status, escalates) in [(503, true), (400, false)] {+ let outcome = test_drive_with_models(+ Arc::clone(&route),+ session(vec![Message::text(Role::User, "task")]),+ category_models(Category::Any, &["local", "cloud"]),+ move |target: ModelId, _| async move {+ match target.as_str() {+ "local" => Err(LlmClientError::UpstreamHttp {+ status: http::StatusCode::from_u16(status).unwrap_or_default(),+ body: String::new(),+ }),+ _ => Ok(reply("cloud answer")),+ }+ },+ )+ .await;+ assert_eq!(+ outcome.is_ok_and(|(selected, _)| selected == "cloud"),+ escalates+ );+ }+ Ok(())+}++fn recovering_classifier() -> super::VgrClassifier {+ let mut config = VgrConfig::new(ModelId::new("local"), ModelId::new("cloud"));+ config.mode = ServingMode::Evaluate;+ config.breaker.threshold = 1;+ config.breaker.cooldown = std::time::Duration::ZERO;+ let classifier = super::VgrClassifier {+ breaker: super::CircuitBreaker::new(config.breaker),+ config,+ };+ classifier.breaker.failure();+ classifier+}++#[tokio::test]+async fn verifier_budget_exhaustion_is_not_an_endpoint_failure() -> Result<()> {+ use std::time::{Duration, Instant};++ use crate::core::algorithm::{Driver, RuntimeModels, Step};++ let mut config = VgrConfig::new(ModelId::new("local"), ModelId::new("cloud"));+ config.deadline = Duration::from_millis(100);+ config.breaker.threshold = 1;+ config.breaker.cooldown = Duration::from_secs(60);+ assert!(config.targets.judge.is_none());+ let classifier = super::VgrClassifier {+ breaker: super::CircuitBreaker::new(config.breaker),+ config,+ };+ let mut state = super::VgrState::default();+ let task = session(vec![Message::text(Role::User, "list files")]);+ let LlmResponse::Agg(proposed) = complete_call().llm_response else {+ unreachable!();+ };+ let (driver, mut steps) = Driver::new("vgr", Arc::new(RuntimeModels::default()));+ let context = super::RequestContext {+ driver: &driver,+ request: &task,+ started: Instant::now(),+ };+ let mut judging = Box::pin(classifier.verify_turn(&context, &proposed, &mut state));+ assert!(futures::poll!(&mut judging).is_pending());+ let Step::CallModel(pending_call) = steps.try_recv().expect("judge call should be queued")?+ else {+ unreachable!();+ };+ assert_eq!(pending_call.models, vec![ModelId::new("local")]);+ let escalates = judging.await;+ drop(pending_call);+ assert!(!escalates);+ assert!(!state.turn_latched);+ assert!(classifier.breaker.attempt().is_some());+ Ok(())+}++#[tokio::test]+async fn skipped_requests_leave_the_recovery_trial_available() -> Result<()> {+ use crate::core::classifier::Classifier;+ use crate::core::testing::empty_driver;+ use switchyard_protocol::ImageSource;++ for skip in ["image", "latched", "off", "kill", "deadline"] {+ let mut classifier = recovering_classifier();+ let mut state = super::VgrState::default();+ let mut task = request(vec![Message::text(Role::User, "task")]);+ match skip {+ "image" => {+ task.llm_request.messages[0].content = vec![ContentBlock::Image {+ source: ImageSource::Url {+ url: "https://example.test/image.png".into(),+ detail: None,+ },+ }]+ }+ "latched" => state.turn_latched = true,+ "off" => classifier.config.mode = ServingMode::Off,+ "kill" => {+ let switch = super::super::KillSwitch::new();+ switch.engage();+ classifier.config.kill_switch = Some(switch);+ }+ "deadline" => classifier.config.deadline = std::time::Duration::ZERO,+ _ => unreachable!(),+ }+ classifier+ .score(&mut state, &mut task, &empty_driver())+ .await?;+ assert!(+ classifier.breaker.attempt().is_some(),+ "{skip} reserved the recovery trial"+ );+ }+ Ok(())+}++#[tokio::test]+async fn cancelling_local_generation_releases_the_recovery_trial() -> Result<()> {+ use crate::core::algorithm::{Driver, RuntimeModels};+ use crate::core::classifier::Classifier;++ let classifier = recovering_classifier();+ let mut state = super::VgrState::default();+ let mut task = request(vec![Message::text(Role::User, "task")]);+ let (driver, _steps) = Driver::new("vgr", Arc::new(RuntimeModels::default()));+ let mut pending = classifier.score(&mut state, &mut task, &driver);+ assert!(futures::poll!(&mut pending).is_pending());+ assert!(classifier.breaker.attempt().is_none());+ drop(pending);+ assert!(classifier.breaker.attempt().is_some());+ Ok(())+}++#[tokio::test]+async fn decisions_attach_the_reason_and_exclude_local_cloud_fallbacks() -> Result<()> {+ use crate::core::algorithm::Call;+ use crate::core::testing::serve_decision;++ for (mode, reason, served) in [+ (ServingMode::Off, "mode_off", "cloud"),+ (ServingMode::Evaluate, "decided", "local"),+ (ServingMode::Shadow, "decided", "cloud"),+ ] {+ let algorithm = route(|config| config.mode = mode)?;+ let outcome = crate::drive(+ algorithm,+ request(vec![Message::text(Role::User, "task")]),+ Arc::new(category_models(Category::Any, &["local", "cloud"]).into()),+ |call| async move {+ match call {+ Call::Model(call) => {+ let response = if call.models[0] == ModelId::new("local") {+ reply("done")+ } else {+ scored(0.9)+ };+ call.respond(std::future::ready(Ok(response))).await+ }+ Call::Decision(call) => serve_decision(*call).await,+ }+ },+ )+ .await?;+ assert_eq!(outcome.selected_model_ids, vec![ModelId::new(served)]);+ let evidence = outcome+ .metadata+ .and_then(|metadata| metadata.evidence)+ .unwrap_or_default();+ assert_eq!(evidence["source"], "vgr");+ assert_eq!(evidence["reason_code"], reason);+ assert_eq!(evidence["verdict"], served);+ if reason == "decided" {+ assert_eq!(evidence["branch"], "DefaultVerified");+ }+ }+ Ok(())+}diff --git a/crates/libsy/src/algorithms/vgr/safety.rs b/crates/libsy/src/algorithms/vgr/safety.rsnew file mode 100644index 000000000..f14f0b362--- /dev/null+++ b/crates/libsy/src/algorithms/vgr/safety.rs@@ -0,0 +1,203 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++use std::sync::Arc;+use std::sync::atomic::{AtomicBool, Ordering};+use std::time::{Duration, Instant};++use http::StatusCode;+use parking_lot::Mutex;+use switchyard_protocol::LlmClientError;++use crate::LibsyError;++/// Operator-controlled stop for local attempts.+#[derive(Clone, Debug, Default)]+pub struct KillSwitch(Arc<AtomicBool>);++impl KillSwitch {+ /// Creates a released switch.+ pub fn new() -> Self {+ Self::default()+ }++ /// Stops local attempts for subsequent requests.+ pub fn engage(&self) {+ self.0.store(true, Ordering::Relaxed);+ }++ /// Allows local attempts again.+ pub fn release(&self) {+ self.0.store(false, Ordering::Relaxed);+ }++ /// Reports whether local attempts are stopped.+ pub fn is_engaged(&self) -> bool {+ self.0.load(Ordering::Relaxed)+ }+}++/// Circuit-breaker configuration.+#[derive(Clone, Copy, Debug)]+pub struct BreakerConfig {+ /// Consecutive endpoint failures required to open.+ pub threshold: u32,+ /// Delay before one half-open trial is admitted.+ pub cooldown: Duration,+}++impl Default for BreakerConfig {+ fn default() -> Self {+ Self {+ threshold: 5,+ cooldown: Duration::from_secs(30),+ }+ }+}++#[derive(Default)]+struct BreakerState {+ failures: u32,+ opened_at: Option<Instant>,+ trial_in_flight: bool,+}++pub(super) struct CircuitBreaker {+ config: BreakerConfig,+ state: Mutex<BreakerState>,+}++impl CircuitBreaker {+ pub(super) fn new(config: BreakerConfig) -> Self {+ Self {+ config,+ state: Mutex::new(BreakerState::default()),+ }+ }++ pub(super) fn attempt(&self) -> Option<Attempt<'_>> {+ let mut state = self.state.lock();+ let recovery = if let Some(opened_at) = state.opened_at {+ if state.trial_in_flight || opened_at.elapsed() < self.config.cooldown {+ return None;+ }+ state.trial_in_flight = true;+ true+ } else {+ false+ };+ Some(Attempt {+ breaker: self,+ recovery,+ completed: false,+ })+ }++ pub(super) fn success(&self) {+ *self.state.lock() = BreakerState::default();+ }++ pub(super) fn failure(&self) {+ let mut state = self.state.lock();+ state.failures = state.failures.saturating_add(1);+ state.trial_in_flight = false;+ if state.failures >= self.config.threshold {+ state.opened_at = Some(Instant::now());+ }+ }+}++/// Releases a recovery trial if its local call is cancelled or abandoned.+pub(super) struct Attempt<'a> {+ breaker: &'a CircuitBreaker,+ recovery: bool,+ completed: bool,+}++impl Attempt<'_> {+ pub(super) fn success(mut self) {+ self.completed = true;+ self.breaker.success();+ }++ pub(super) fn failure(mut self) {+ self.completed = true;+ self.breaker.failure();+ }+}++impl Drop for Attempt<'_> {+ fn drop(&mut self) {+ if self.recovery && !self.completed {+ self.breaker.state.lock().trial_in_flight = false;+ }+ }+}++/// Errors for which retrying on the capable tier is safe.+pub(super) fn fallback_eligible(error: &LibsyError) -> bool {+ matches!(+ error,+ LibsyError::ClientCall { source, .. } if match source {+ LlmClientError::ContextWindowExceeded { .. }+ | LlmClientError::Transport { .. }+ | LlmClientError::Timeout { .. } => true,+ LlmClientError::UpstreamHttp { status, .. } =>+ matches!(+ *status,+ StatusCode::FORBIDDEN+ | StatusCode::REQUEST_TIMEOUT+ | StatusCode::TOO_MANY_REQUESTS+ ) || status.is_server_error(),+ _ => false,+ }+ )+}++/// Only endpoint unavailability contributes to breaker health.+pub(super) fn endpoint_failure(error: &LibsyError) -> bool {+ matches!(+ error,+ LibsyError::ClientCall { source, .. } if match source {+ LlmClientError::Transport { .. } | LlmClientError::Timeout { .. } => true,+ LlmClientError::UpstreamHttp { status, .. } => matches!(+ *status,+ StatusCode::BAD_GATEWAY+ | StatusCode::SERVICE_UNAVAILABLE+ | StatusCode::GATEWAY_TIMEOUT+ ),+ _ => false,+ }+ )+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn recovery_trials_are_exclusive_and_can_be_retried_after_failure_or_drop() {+ let breaker = CircuitBreaker::new(BreakerConfig {+ threshold: 1,+ cooldown: Duration::ZERO,+ });+ breaker.failure();+ let trial = breaker.attempt().expect("recovery trial");+ assert!(breaker.attempt().is_none());+ drop(trial);+ breaker.attempt().expect("released trial").failure();+ breaker.attempt().expect("retry after failure").success();+ assert!(breaker.state.lock().opened_at.is_none());+ assert!(breaker.attempt().is_some());+ }++ #[test]+ fn recovery_waits_for_the_cooldown() {+ let breaker = CircuitBreaker::new(BreakerConfig {+ threshold: 1,+ cooldown: Duration::from_secs(30),+ });+ breaker.failure();+ assert!(breaker.attempt().is_none());+ }+}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex 055496eb6..efd61f63a 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -38,6 +38,9 @@ pub use algorithms::util::escalation::{DeescalationConfig, EscalationJudgeConfigpub use algorithms::util::prompts::append_note;pub use algorithms::util::subagent::{SubagentGate, SubagentOverride};pub use algorithms::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSemantics, ToolSignals};+pub use algorithms::vgr::{+ ACTIVE_APPROVAL, BreakerConfig, KillSwitch, ServingMode, Targets as VgrTargets, Vgr, VgrConfig,+};// Stage-router scoring and tier selection — the shared signal-driven routing// core (scorer, picker, and the `StageClassifier`).