switchyard_libsy/algorithms/util/
escalation.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Trajectory-judge components for the escalation router — the judge, its verdict policy, and
5//! the transcript condenser they read.
6//!
7//! [`build_judge`] is the whole surface; the confirmation policy that consumes its verdicts
8//! lives with the assembled algorithm in [`crate::algorithms::escalation`].
9
10use serde::Deserialize;
11use switchyard_protocol::{ContentBlock, Message, Role};
12
13use super::classifier_contract::{ClassifierContract, ClassifierContractConfig};
14use super::llm_judge::{
15    ClassifierInput, JudgeClassifier, JudgePolicy, JudgeRuntimeConfig, SerdeDecoder,
16    StructuredJudge,
17};
18use crate::core::algorithm::LlmTarget;
19use crate::core::classifier::{Classification, Score};
20use crate::core::state::State;
21use crate::{LibsyError, Result};
22use switchyard_protocol::Request;
23
24const PROMPT_TEMPLATE: &str = include_str!("../../prompts/escalation/prompt.md");
25const SCHEMA_TEMPLATE: &str = include_str!("../../prompts/escalation/schema.json");
26
27/// Separator marking where [`truncate_middle`] dropped a message's interior.
28const TRIM_MARKER: &str = " ...[trimmed] ";
29
30/// Suffix marking a transcript cut off by [`MAX_REQUEST_CHARS`].
31const TRUNCATION_SUFFIX: &str = "...<truncated>";
32
33/// Per-message cap for system and developer anchors, which carry no trajectory signal but
34/// which coding-agent harnesses make very large.
35const SYSTEM_CHARS: usize = 1_000;
36
37/// Cap for the first user message — the task statement, so it gets the widest anchor budget.
38const FIRST_USER_CHARS: usize = 2_000;
39
40/// Backstop on the assembled transcript; the per-message caps normally bind first.
41const MAX_REQUEST_CHARS: usize = 18_000;
42
43/// The tuning surface for the trajectory judge.
44///
45/// The routing settings retain their benchmarked defaults. Everything else is a fixed invariant
46/// (the constants above).
47#[derive(Clone, Debug, Deserialize)]
48#[serde(default, deny_unknown_fields)]
49pub struct EscalationJudgeConfig {
50    /// Consecutive escalate verdicts required before a turn moves to the capable tier, which
51    /// is also the turn that latches the session. Any decline clears the streak.
52    /// `1` escalates on the first verdict; the router's main cost dial.
53    /// `2` or higher needs a session id, since the streak is retained per session.
54    pub confirmations: u32,
55    /// Trailing messages shown on top of the anchors. A loop longer than this is invisible.
56    pub recent_turn_window: usize,
57    /// Per-message cap inside the trailing window.
58    pub window_message_chars: usize,
59}
60
61impl EscalationJudgeConfig {
62    /// Rejects settings that would leave the judge with nothing useful to read.
63    fn validate(&self) -> Result<()> {
64        let reject = |message: String| Err(LibsyError::AlgorithmError { message });
65        if self.confirmations == 0 {
66            return reject("confirmations must be at least 1".to_string());
67        }
68        if self.recent_turn_window == 0 {
69            return reject("recent_turn_window must be at least 1".to_string());
70        }
71        if self.window_message_chars < 50 {
72            return reject(format!(
73                "window_message_chars must be at least 50, got {}",
74                self.window_message_chars
75            ));
76        }
77        Ok(())
78    }
79}
80
81impl Default for EscalationJudgeConfig {
82    fn default() -> Self {
83        Self {
84            confirmations: 2,
85            recent_turn_window: 28,
86            window_message_chars: 500,
87        }
88    }
89}
90
91/// The judge's verdict. The schema also requires a `reason`, which makes the judge state its
92/// case and measurably sharpens the verdict — routing reads only the boolean, so it is
93/// deserialized away rather than carried.
94#[derive(Deserialize)]
95pub(crate) struct EscalationVerdict {
96    escalate: bool,
97}
98
99/// Builds the condensed trajectory presented to the escalation judge.
100pub(crate) struct EscalationInput {
101    config: EscalationJudgeConfig,
102}
103
104impl ClassifierInput for EscalationInput {
105    fn build_messages(&self, _state: &State, request: &Request) -> Vec<Message> {
106        let messages = &request.llm_request.messages;
107        let summary = summarize_for_judge(messages, conversation_turn(request), &self.config);
108        vec![Message::text(Role::User, summary)]
109    }
110}
111
112/// Structured trajectory judge with a typed escalation verdict.
113pub(crate) type EscalationJudge = StructuredJudge<EscalationInput, SerdeDecoder<EscalationVerdict>>;
114
115/// Maps the judge's verdict to a classification. A verdict names the tier to serve — capable
116/// on escalate, efficient on decline — so the caller reads it straight off the winning score.
117/// [`Classification::Ambiguous`] carries the unavailable case, which names no tier: both a
118/// decline and an outage stay efficient, but only a decline is evidence, so only a decline
119/// clears the streak.
120pub(crate) struct EscalationPolicy {
121    capable: String,
122    efficient: String,
123}
124
125impl JudgePolicy for EscalationPolicy {
126    type Verdict = EscalationVerdict;
127
128    fn to_classification(&self, verdict: Option<&EscalationVerdict>) -> Classification {
129        match verdict {
130            Some(verdict) if verdict.escalate => Classification::Scores(vec![Score {
131                target: self.capable.clone(),
132                confidence: 1.0,
133            }]),
134            Some(_) => Classification::Scores(vec![Score {
135                target: self.efficient.clone(),
136                confidence: 1.0,
137            }]),
138            None => Classification::Ambiguous(Vec::new()),
139        }
140    }
141}
142
143/// Builds the trajectory judge over `judge_target`, scoring `capable` when it escalates.
144///
145/// Loads the packaged prompt and schema, so an unusable asset or an unusable `config` value
146/// fails here rather than on the first request.
147pub(crate) fn build_judge(
148    judge_target: LlmTarget,
149    capable: String,
150    efficient: String,
151    contract_config: &ClassifierContractConfig,
152    config: EscalationJudgeConfig,
153    max_output_tokens: u64,
154) -> Result<JudgeClassifier<EscalationJudge, EscalationPolicy>> {
155    config.validate()?;
156    let contract =
157        ClassifierContract::from_config(contract_config, PROMPT_TEMPLATE, SCHEMA_TEMPLATE)?;
158    Ok(JudgeClassifier::new(
159        StructuredJudge::new(
160            EscalationInput { config },
161            contract,
162            SerdeDecoder::new(),
163            JudgeRuntimeConfig::new(max_output_tokens)?,
164        ),
165        judge_target,
166        EscalationPolicy { capable, efficient },
167    ))
168}
169
170/// The 1-indexed model invocation the transcript ends on: one per assistant reply.
171///
172/// The judge reads the turn *including* the reply it is judging, so the newest assistant
173/// message is this turn — no `+ 1`. Counting the caller's request instead would report the
174/// turn after the one under judgement.
175///
176/// Messages are already normalized by `switchyard-protocol`, so this needs no
177/// per-format branching.
178pub(crate) fn conversation_turn(request: &Request) -> usize {
179    request
180        .llm_request
181        .messages
182        .iter()
183        .filter(|message| message.role == Role::Assistant)
184        .count()
185}
186
187/// Flattens a message to plain text, tool calls and tool results included.
188///
189/// [`Message::text_content`] is deliberately not used here: it keeps only text and refusal
190/// blocks, which would erase exactly the repeated-command signal the judge's loop detection
191/// relies on.
192fn message_text(message: &Message) -> String {
193    let mut parts = Vec::new();
194    collect_text(&message.content, &mut parts);
195    parts.join(" ")
196}
197
198/// Appends the judge-relevant text of each block, descending into tool results.
199fn collect_text(content: &[ContentBlock], parts: &mut Vec<String>) {
200    for block in content {
201        match block {
202            ContentBlock::Text { text } | ContentBlock::Refusal { text } => {
203                parts.push(text.clone());
204            }
205            ContentBlock::ToolCall(call) => {
206                parts.push(format!("tool_call {}({})", call.name, call.arguments));
207            }
208            ContentBlock::ToolResult(result) => collect_text(&result.content, parts),
209            _ => {}
210        }
211    }
212}
213
214/// Keeps the head and tail of `text` within `limit` characters.
215///
216/// The head gets two thirds of the surviving budget: for a trajectory judge the command or
217/// error signature that opens a message carries more signal than its trailing output.
218fn truncate_middle(text: &str, limit: usize) -> String {
219    let chars: Vec<char> = text.chars().collect();
220    if chars.len() <= limit {
221        return text.to_string();
222    }
223    let keep = limit
224        .saturating_sub(TRIM_MARKER.chars().count())
225        .max(20)
226        .min(chars.len());
227    let head = keep * 2 / 3;
228    let tail = keep - head;
229    let mut out: String = chars[..head].iter().collect();
230    out.push_str(TRIM_MARKER);
231    out.extend(chars[chars.len() - tail..].iter());
232    out
233}
234
235/// Renders a compact role-labelled transcript for the judge.
236///
237/// The framing anchors — system/developer messages and the first user message, where agent
238/// harnesses put the task statement — are kept unconditionally and capped individually. The
239/// trailing window carries recent activity. A coverage header states how much history is not
240/// shown, so the judge can reason about pace rather than assuming it sees everything.
241///
242/// When the assembled text still exceeds `max_request_chars`, the oldest window lines go
243/// first: for a trajectory judge the newest evidence is strictly the most valuable.
244fn summarize_for_judge(
245    messages: &[Message],
246    turn: usize,
247    config: &EscalationJudgeConfig,
248) -> String {
249    let mut anchors: Vec<String> = Vec::new();
250    let mut window: Vec<String> = Vec::new();
251    let mut first_user_seen = false;
252
253    for message in messages {
254        let text = message_text(message);
255        match message.role {
256            Role::System | Role::Developer => anchors.push(format!(
257                "[{}] {}",
258                role_label(message.role),
259                truncate_middle(&text, SYSTEM_CHARS)
260            )),
261            Role::User if !first_user_seen => {
262                first_user_seen = true;
263                anchors.push(format!(
264                    "[user (task)] {}",
265                    truncate_middle(&text, FIRST_USER_CHARS)
266                ));
267            }
268            role => window.push(format!(
269                "[{}] {}",
270                role_label(role),
271                truncate_middle(&text, config.window_message_chars)
272            )),
273        }
274    }
275
276    if window.len() > config.recent_turn_window {
277        window.drain(..window.len() - config.recent_turn_window);
278    }
279
280    let assemble = |window: &[String]| {
281        let header = format!(
282            "Conversation turn {turn}; showing the last {} of {} messages after the task framing.",
283            window.len(),
284            messages.len(),
285        );
286        std::iter::once(header)
287            .chain(anchors.iter().cloned())
288            .chain(window.iter().cloned())
289            .collect::<Vec<_>>()
290            .join("\n")
291    };
292
293    let mut text = assemble(&window);
294    while text.chars().count() > MAX_REQUEST_CHARS && !window.is_empty() {
295        window.remove(0);
296        text = assemble(&window);
297    }
298    if text.chars().count() > MAX_REQUEST_CHARS {
299        let keep = MAX_REQUEST_CHARS.saturating_sub(TRUNCATION_SUFFIX.chars().count() + 1);
300        text = text.chars().take(keep).collect::<String>() + TRUNCATION_SUFFIX;
301    }
302    text
303}
304
305/// The transcript label for a role.
306fn role_label(role: Role) -> &'static str {
307    match role {
308        Role::System => "system",
309        Role::Developer => "developer",
310        Role::User => "user",
311        Role::Assistant => "assistant",
312        Role::Tool => "tool",
313    }
314}
315
316/// A request whose conversation sits at `turn`: `turn - 1` prior assistant replies, each
317/// answered by a further user message.
318///
319/// Shared with the assembled router's tests, which drive the same conversation shape.
320#[cfg(test)]
321pub(crate) fn request_at_turn(session_id: Option<&str>, turn: usize) -> Request {
322    use switchyard_protocol::{LlmRequest, Metadata};
323
324    let mut messages = vec![Message::text(Role::User, "What is 2+2?")];
325    for attempt in 1..turn {
326        messages.push(Message::text(Role::Assistant, format!("attempt {attempt}")));
327        messages.push(Message::text(Role::User, format!("still wrong {attempt}")));
328    }
329    Request {
330        llm_request: LlmRequest {
331            model: Some("auto".to_string()),
332            messages,
333            ..LlmRequest::default()
334        },
335        raw_request: None,
336        metadata: session_id.map(|id| Metadata {
337            session_id: Some(id.to_string()),
338            ..Metadata::default()
339        }),
340    }
341}
342
343#[cfg(test)]
344mod tests {
345    use serde_json::json;
346    use switchyard_protocol::{ContentBlock, Message, Role, ToolCall, ToolResult};
347
348    use super::*;
349    use crate::algorithms::util::llm_judge::Judge;
350
351    fn escalation_judge(max_output_tokens: u64) -> Result<EscalationJudge> {
352        Ok(StructuredJudge::new(
353            EscalationInput {
354                config: EscalationJudgeConfig::default(),
355            },
356            ClassifierContract::from_config(
357                &ClassifierContractConfig::default(),
358                PROMPT_TEMPLATE,
359                SCHEMA_TEMPLATE,
360            )?,
361            SerdeDecoder::new(),
362            JudgeRuntimeConfig::new(max_output_tokens)?,
363        ))
364    }
365
366    #[test]
367    fn judge_request_is_rubric_plus_summary_under_a_completion_cap() -> Result<()> {
368        let judge = escalation_judge(super::super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS)?;
369
370        // As the classifier calls it: the turn's reply is already on the transcript.
371        let mut judged = request_at_turn(None, 4);
372        judged
373            .llm_request
374            .messages
375            .push(Message::text(Role::Assistant, "this turn's reply"));
376        let built = judge.build_request(&State::default(), &judged);
377
378        // Two messages: the rubric as system, the condensed trajectory as user.
379        assert_eq!(built.llm_request.messages.len(), 2);
380        assert_eq!(built.llm_request.messages[0].role, Role::System);
381        assert_eq!(built.llm_request.messages[1].role, Role::User);
382        assert!(
383            built.llm_request.messages[1]
384                .text_content("")
385                .is_some_and(|text| text.contains("Conversation turn 4"))
386        );
387        // Bounded output, so a reasoning judge cannot run away mid-verdict.
388        assert_eq!(
389            built.llm_request.output.max_output_tokens,
390            Some(super::super::DEFAULT_JUDGE_MAX_OUTPUT_TOKENS)
391        );
392        assert!(built.llm_request.output.response_format.is_some());
393        Ok(())
394    }
395
396    #[test]
397    fn judge_request_uses_the_configured_completion_cap() -> Result<()> {
398        let judge = escalation_judge(512)?;
399
400        let built = judge.build_request(&State::default(), &request_at_turn(None, 1));
401
402        assert_eq!(built.llm_request.output.max_output_tokens, Some(512));
403        Ok(())
404    }
405
406    #[test]
407    fn conversation_turn_counts_assistant_replies() {
408        // The judge is handed the transcript with this turn's reply already appended, which
409        // is the shape asserted here: a request entering turn N plus its reply *is* turn N.
410        for turn in [1, 5] {
411            let mut judged = request_at_turn(None, turn);
412            judged
413                .llm_request
414                .messages
415                .push(Message::text(Role::Assistant, "this turn's reply"));
416            assert_eq!(conversation_turn(&judged), turn);
417        }
418    }
419
420    #[test]
421    fn message_text_keeps_tool_calls_and_results() {
422        let call = Message {
423            role: Role::Assistant,
424            content: vec![
425                ContentBlock::Text {
426                    text: "running it".to_string(),
427                },
428                ContentBlock::ToolCall(ToolCall {
429                    id: "call-1".to_string(),
430                    name: "bash".to_string(),
431                    arguments: json!({"cmd": "ls"}),
432                }),
433            ],
434        };
435        let text = message_text(&call);
436        assert!(text.contains("running it"), "{text}");
437        assert!(text.contains(r#"tool_call bash({"cmd":"ls"})"#), "{text}");
438
439        let result = Message {
440            role: Role::Tool,
441            content: vec![ContentBlock::ToolResult(ToolResult {
442                tool_call_id: "call-1".to_string(),
443                content: vec![ContentBlock::Text {
444                    text: "no such file".to_string(),
445                }],
446                is_error: Some(true),
447            })],
448        };
449        assert_eq!(message_text(&result), "no such file");
450    }
451
452    #[test]
453    fn truncate_middle_keeps_head_and_tail() {
454        let text = "a".repeat(40) + &"z".repeat(40);
455        let trimmed = truncate_middle(&text, 50);
456        assert!(trimmed.chars().count() <= 50, "{trimmed}");
457        assert!(trimmed.starts_with('a'));
458        assert!(trimmed.ends_with('z'));
459        assert!(trimmed.contains("[trimmed]"));
460
461        // Under the limit the text is returned untouched.
462        assert_eq!(truncate_middle("short", 50), "short");
463    }
464
465    #[test]
466    fn summary_keeps_anchors_and_the_recent_window() {
467        let mut messages = vec![
468            Message::text(Role::System, "you are a coding agent"),
469            Message::text(Role::User, "fix the failing test"),
470        ];
471        for i in 0..10 {
472            messages.push(Message::text(Role::Assistant, format!("step {i}")));
473        }
474        let config = EscalationJudgeConfig {
475            recent_turn_window: 3,
476            ..EscalationJudgeConfig::default()
477        };
478
479        let summary = summarize_for_judge(&messages, 11, &config);
480
481        assert!(
482            summary.contains("[system] you are a coding agent"),
483            "{summary}"
484        );
485        assert!(
486            summary.contains("[user (task)] fix the failing test"),
487            "{summary}"
488        );
489        assert!(summary.contains("Conversation turn 11; showing the last 3 of 12 messages"));
490        // Only the newest window entries survive.
491        assert!(summary.contains("step 9"), "{summary}");
492        assert!(summary.contains("step 7"), "{summary}");
493        assert!(!summary.contains("step 6"), "{summary}");
494    }
495
496    #[test]
497    fn summary_drops_oldest_window_lines_under_the_char_cap() {
498        // MAX_REQUEST_CHARS is a backstop, not a dial: at default settings the window caps
499        // bind first (28 x 500 plus anchors sits under it), so reaching it takes an unusually
500        // wide per-message cap. That is the point — it only fires on pathological input.
501        let mut messages = vec![
502            Message::text(Role::System, "framing"),
503            Message::text(Role::User, "task"),
504        ];
505        for i in 0..20 {
506            messages.push(Message::text(
507                Role::Assistant,
508                format!("{i} {}", "x".repeat(2_000)),
509            ));
510        }
511        let config = EscalationJudgeConfig {
512            window_message_chars: 2_000,
513            ..EscalationJudgeConfig::default()
514        };
515
516        let summary = summarize_for_judge(&messages, 21, &config);
517
518        assert!(
519            summary.chars().count() <= MAX_REQUEST_CHARS,
520            "{}",
521            summary.chars().count()
522        );
523        // Anchors are never dropped, and the newest activity outlives the oldest.
524        assert!(summary.contains("[system] framing"), "{summary}");
525        assert!(summary.contains("[user (task)] task"), "{summary}");
526        assert!(summary.contains("19 xxx"), "{summary}");
527        assert!(!summary.contains("0 xxx"), "{summary}");
528    }
529}
switchyard_libsy/algorithms/util/escalation.rs

switchyard_libsy/algorithms/util/
escalation.rs
