switchyard_libsy/algorithms/
plan_execute.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Plans coding tasks on a capable model, then hands execution to an efficient model.
5
6use std::collections::HashSet;
7use std::sync::Arc;
8
9use parking_lot::Mutex;
10use switchyard_protocol::{Category, ContentBlock, Request};
11
12use super::util::prompts::{append_note, drop_exact_replay, prepend_system_prompt};
13use super::util::tool_signals::ToolSignals;
14use crate::core::algorithm::{Algorithm, Driver, RoutingIdentity};
15use crate::{LibsyError, Result, RoutingOutcome};
16
17/// Default instruction added while the capable model is planning.
18pub const DEFAULT_PLANNING_PROMPT: &str =
19    include_str!("../prompts/plan-execute/planning-system-prompt.md");
20
21const MAX_EXECUTING_SESSIONS: usize = 4_096;
22
23/// Configuration for [`PlanExecute`].
24#[derive(Clone, Debug)]
25pub struct PlanExecuteConfig {
26    /// System instruction added until the first edit or write tool call.
27    pub planning_prompt: String,
28    /// Optional instruction appended to the handoff request.
29    pub handoff_prompt: Option<String>,
30    /// Replays visible planner reasoning summaries as assistant text at handoff.
31    pub planner_reasoning_as_text: bool,
32}
33
34impl Default for PlanExecuteConfig {
35    fn default() -> Self {
36        Self {
37            planning_prompt: DEFAULT_PLANNING_PROMPT.trim().to_string(),
38            handoff_prompt: None,
39            planner_reasoning_as_text: false,
40        }
41    }
42}
43
44#[derive(Clone, Copy, Debug, Eq, PartialEq)]
45enum Phase {
46    Plan,
47    Handoff,
48    Execute,
49}
50
51/// Routes planning turns to the runtime capable model, then latches execution
52/// to the runtime efficient model after the first recorded mutation.
53pub struct PlanExecute {
54    config: PlanExecuteConfig,
55    executing_sessions: Mutex<HashSet<RoutingIdentity>>,
56}
57
58impl PlanExecute {
59    /// Creates a plan/execute router.
60    ///
61    /// Returns an error when either configured prompt is blank.
62    pub fn new(config: PlanExecuteConfig) -> Result<Self> {
63        if config.planning_prompt.trim().is_empty() {
64            return Err(LibsyError::AlgorithmError {
65                message: "planning_prompt must not be empty".to_string(),
66            });
67        }
68        if config
69            .handoff_prompt
70            .as_deref()
71            .is_some_and(|prompt| prompt.trim().is_empty())
72        {
73            return Err(LibsyError::AlgorithmError {
74                message: "handoff_prompt must not be empty".to_string(),
75            });
76        }
77        Ok(Self {
78            config,
79            executing_sessions: Mutex::new(HashSet::new()),
80        })
81    }
82
83    fn phase(&self, request: &Request) -> Phase {
84        let signals = ToolSignals::from_request(request, None);
85        let mutation_seen = signals.edit_count > 0 || signals.write_count > 0;
86        let Some(identity) = RoutingIdentity::from_request(request) else {
87            return if mutation_seen {
88                Phase::Handoff
89            } else {
90                Phase::Plan
91            };
92        };
93
94        let mut sessions = self.executing_sessions.lock();
95        let phase = if sessions.contains(&identity) {
96            Phase::Execute
97        } else if mutation_seen {
98            if sessions.len() >= MAX_EXECUTING_SESSIONS
99                && let Some(evicted) = sessions.iter().next().cloned()
100            {
101                sessions.remove(&evicted);
102            }
103            sessions.insert(identity.clone());
104            Phase::Handoff
105        } else {
106            Phase::Plan
107        };
108        if request
109            .metadata
110            .as_ref()
111            .and_then(|metadata| metadata.session_final)
112            == Some(true)
113        {
114            sessions.remove(&identity);
115        }
116        phase
117    }
118
119    fn replay_planner_reasoning_as_text(request: &mut Request) -> usize {
120        let mut converted = 0;
121        for message in &mut request.llm_request.messages {
122            message.content = std::mem::take(&mut message.content)
123                .into_iter()
124                .filter_map(|block| match block {
125                    ContentBlock::Reasoning { text, .. } => {
126                        converted += 1;
127                        (!text.is_empty()).then_some(ContentBlock::Text { text })
128                    }
129                    other => Some(other),
130                })
131                .collect();
132        }
133        request
134            .llm_request
135            .messages
136            .retain(|message| !message.content.is_empty());
137        if converted > 0 {
138            drop_exact_replay(request);
139        }
140        converted
141    }
142
143    fn route_to(driver: &Driver, category: Category, request: Request) -> Result<RoutingOutcome> {
144        let models = driver.models_for(&category);
145        let Some((selected, fallbacks)) = models.split_first() else {
146            return Err(LibsyError::AlgorithmError {
147                message: format!("no models available for category {}", category.as_str()),
148            });
149        };
150        Ok(RoutingOutcome::route_to(
151            selected.clone(),
152            fallbacks.to_vec(),
153            request,
154        ))
155    }
156}
157
158#[async_trait::async_trait]
159impl Algorithm for PlanExecute {
160    fn name(&self) -> &str {
161        "plan_execute"
162    }
163
164    async fn route(
165        self: Arc<Self>,
166        driver: Driver,
167        mut request: Request,
168    ) -> Result<RoutingOutcome> {
169        match self.phase(&request) {
170            Phase::Plan => {
171                prepend_system_prompt(&mut request, &self.config.planning_prompt);
172                tracing::debug!(phase = "plan", "plan-execute selected capable tier");
173                Self::route_to(&driver, Category::Capable, request)
174            }
175            Phase::Handoff => {
176                let reasoning_converted = if self.config.planner_reasoning_as_text {
177                    Self::replay_planner_reasoning_as_text(&mut request)
178                } else {
179                    0
180                };
181                let prompt_applied = if let Some(prompt) = &self.config.handoff_prompt {
182                    append_note(&mut request, prompt);
183                    true
184                } else {
185                    false
186                };
187                tracing::debug!(
188                    phase = "handoff",
189                    handoff_prompt_applied = prompt_applied,
190                    planner_reasoning_converted = reasoning_converted,
191                    "plan-execute selected efficient tier"
192                );
193                Self::route_to(&driver, Category::Efficient, request)
194            }
195            Phase::Execute => {
196                tracing::debug!(phase = "execute", "plan-execute selected efficient tier");
197                Self::route_to(&driver, Category::Efficient, request)
198            }
199        }
200    }
201}
202
203#[cfg(test)]
204mod tests {
205    use std::collections::HashMap;
206    use std::sync::Arc;
207
208    use serde_json::json;
209    use switchyard_protocol::{
210        ContentBlock, LlmRequest, Message, Metadata, ModelId, Request, Role, ToolCall,
211    };
212
213    use super::*;
214    use crate::RuntimeModels;
215    use crate::core::testing::{reply, test_drive_with_models};
216
217    const CAPABLE: &str = "model/capable";
218    const EFFICIENT: &str = "model/efficient";
219
220    fn algorithm(config: PlanExecuteConfig) -> Arc<dyn Algorithm> {
221        Arc::new(PlanExecute::new(config).expect("config should be valid"))
222    }
223
224    fn request(messages: Vec<Message>, session_id: Option<&str>) -> Request {
225        Request {
226            llm_request: LlmRequest {
227                model: Some("switchyard/plan-execute".to_string()),
228                messages,
229                ..LlmRequest::default()
230            },
231            metadata: session_id.map(|session_id| Metadata {
232                session_id: Some(session_id.to_string()),
233                ..Metadata::default()
234            }),
235            ..Request::default()
236        }
237    }
238
239    fn tool_call(name: &str, arguments: serde_json::Value) -> Message {
240        Message {
241            role: Role::Assistant,
242            content: vec![ContentBlock::ToolCall(ToolCall {
243                id: "call-1".to_string(),
244                name: name.to_string(),
245                arguments,
246            })],
247        }
248    }
249
250    fn models() -> RuntimeModels {
251        RuntimeModels::new(HashMap::from([
252            (Category::Capable, vec![ModelId::from(CAPABLE)]),
253            (Category::Efficient, vec![ModelId::from(EFFICIENT)]),
254        ]))
255    }
256
257    async fn route_and_capture(
258        algorithm: Arc<dyn Algorithm>,
259        request: Request,
260    ) -> (ModelId, Request) {
261        let captured = Arc::new(Mutex::new(None));
262        let capture = Arc::clone(&captured);
263        let (selected, _) =
264            test_drive_with_models(algorithm, request, models(), move |_target, request| {
265                let capture = Arc::clone(&capture);
266                async move {
267                    *capture.lock() = Some(request);
268                    Ok(reply("ok"))
269                }
270            })
271            .await
272            .expect("routing should succeed");
273        let request = captured
274            .lock()
275            .take()
276            .expect("answer request should be captured");
277        (selected, request)
278    }
279
280    #[tokio::test]
281    async fn plans_then_hands_off_and_latches_execution() {
282        const HANDOFF: &str = "Continue from the plan and repository evidence.";
283        let algorithm = algorithm(PlanExecuteConfig {
284            handoff_prompt: Some(HANDOFF.to_string()),
285            planner_reasoning_as_text: true,
286            ..PlanExecuteConfig::default()
287        });
288
289        let read_only = request(
290            vec![tool_call(
291                "exec_command",
292                json!({"cmd": "rg parser crates"}),
293            )],
294            Some("task-1"),
295        );
296        let (selected, routed) = route_and_capture(Arc::clone(&algorithm), read_only).await;
297        assert_eq!(selected, CAPABLE);
298        assert_eq!(routed.llm_request.instructions.len(), 1);
299
300        let first_edit = request(
301            vec![Message {
302                role: Role::Assistant,
303                content: vec![
304                    ContentBlock::Reasoning {
305                        text: "The parser needs a boundary check.".to_string(),
306                        signature: Some("planner-signature".to_string()),
307                        details: vec![json!({"type": "reasoning.encrypted", "data": "opaque"})],
308                    },
309                    ContentBlock::ToolCall(ToolCall {
310                        id: "call-1".to_string(),
311                        name: "apply_patch".to_string(),
312                        arguments: json!({"patch": "*** Begin Patch"}),
313                    }),
314                ],
315            }],
316            Some("task-1"),
317        );
318        let (selected, routed) = route_and_capture(Arc::clone(&algorithm), first_edit).await;
319        assert_eq!(selected, EFFICIENT);
320        assert_eq!(
321            routed.llm_request.messages[0].content[0],
322            ContentBlock::Text {
323                text: "The parser needs a boundary check.".to_string()
324            }
325        );
326        assert_eq!(
327            routed.llm_request.messages.last(),
328            Some(&Message::text(Role::User, HANDOFF))
329        );
330
331        let mut final_request = request(
332            vec![Message::text(Role::User, "Continue after compaction")],
333            Some("task-1"),
334        );
335        final_request
336            .metadata
337            .as_mut()
338            .expect("session metadata should exist")
339            .session_final = Some(true);
340        let (selected, routed) = route_and_capture(Arc::clone(&algorithm), final_request).await;
341        assert_eq!(selected, EFFICIENT);
342        assert!(routed.llm_request.instructions.is_empty());
343        assert_eq!(routed.llm_request.messages.len(), 1);
344
345        let reused = request(vec![Message::text(Role::User, "New task")], Some("task-1"));
346        let (selected, _) = route_and_capture(algorithm, reused).await;
347        assert_eq!(selected, CAPABLE);
348    }
349
350    #[tokio::test]
351    async fn mutation_without_a_session_uses_the_efficient_tier() {
352        let messages = vec![tool_call(
353            "exec_command",
354            json!({"cmd": "printf 'done\\n' > task.txt"}),
355        )];
356
357        let (selected, routed) = route_and_capture(
358            algorithm(PlanExecuteConfig::default()),
359            request(messages.clone(), None),
360        )
361        .await;
362
363        assert_eq!(selected, EFFICIENT);
364        assert_eq!(routed.llm_request.messages, messages);
365        assert!(routed.llm_request.instructions.is_empty());
366    }
367
368    #[test]
369    fn rejects_blank_prompts() {
370        for config in [
371            PlanExecuteConfig {
372                planning_prompt: "  ".to_string(),
373                ..PlanExecuteConfig::default()
374            },
375            PlanExecuteConfig {
376                handoff_prompt: Some("  ".to_string()),
377                ..PlanExecuteConfig::default()
378            },
379        ] {
380            assert!(matches!(
381                PlanExecute::new(config),
382                Err(LibsyError::AlgorithmError { .. })
383            ));
384        }
385    }
386}
switchyard_libsy/algorithms/plan_execute.rs

switchyard_libsy/algorithms/
plan_execute.rs
