| 1 | //! `rlm_process` tool — heavy-lift recursive language model as a tool call. |
| 2 | //! |
| 3 | //! Where `rlm_query` is a parallel fanout primitive (N prompts → N answers, |
| 4 | //! stateless), `rlm_process` runs the full recursive-language-model loop |
| 5 | //! against a long input. The input is loaded into a Python REPL as the |
| 6 | //! `PROMPT` variable; a sub-agent writes code to chunk it, calls |
| 7 | //! `llm_query()` / `sub_rlm()` for sub-LLM work, and returns a final string |
| 8 | //! via `FINAL()`. The model never has to put the long input in its own |
| 9 | //! context window — it just calls the tool with `task` + `file_path` (or |
| 10 | //! inline `content`) and reads the synthesized answer back. |
| 11 | //! |
| 12 | //! Use when the input genuinely doesn't fit in working context: a whole |
| 13 | //! file, a long transcript, a multi-document corpus. For short prompts or |
| 14 | //! parallel fanout, prefer `rlm_query`. |
| 15 | |
| 16 | use async_trait::async_trait; |
| 17 | use serde_json::{Value, json}; |
| 18 | |
| 19 | use crate::client::DeepSeekClient; |
| 20 | use crate::rlm::turn::{RlmTermination, run_rlm_turn_with_root}; |
| 21 | use crate::tools::spec::{ |
| 22 | ApprovalRequirement, ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec, |
| 23 | }; |
| 24 | use crate::utils::spawn_supervised; |
| 25 | |
| 26 | /// Default child model — cheap and fast. |
| 27 | const DEFAULT_CHILD_MODEL: &str = "deepseek-v4-flash"; |
| 28 | /// Default `sub_rlm` recursion budget — paper experiments use 1. |
| 29 | const DEFAULT_MAX_DEPTH: u32 = 1; |
| 30 | /// Hard cap on how many chars of inline `content` we'll accept. Larger |
| 31 | /// inputs should come in via `file_path` so they never enter the caller's |
| 32 | /// context in the first place. |
| 33 | const MAX_INLINE_CONTENT_CHARS: usize = 200_000; |
| 34 | |
| 35 | pub struct RlmTool { |
| 36 | /// Production HTTP client. `None` when no API key is configured. |
| 37 | client: Option<DeepSeekClient>, |
| 38 | /// Root model to drive the RLM loop. Set at registration time; matches |
| 39 | /// whatever model the parent session is using. |
| 40 | root_model: String, |
| 41 | } |
| 42 | |
| 43 | impl RlmTool { |
| 44 | #[must_use] |
| 45 | pub fn new(client: Option<DeepSeekClient>, root_model: String) -> Self { |
| 46 | Self { client, root_model } |
| 47 | } |
| 48 | } |
| 49 | |
| 50 | #[async_trait] |
| 51 | impl ToolSpec for RlmTool { |
| 52 | fn name(&self) -> &'static str { |
| 53 | "rlm" |
| 54 | } |
| 55 | |
| 56 | fn description(&self) -> &'static str { |
| 57 | "Specialty tool for processing long inputs that don't fit in your \ |
| 58 | own context window. Loads the input into a sandboxed Python REPL \ |
| 59 | as `PROMPT`; a sub-agent writes Python that chunks the input and \ |
| 60 | calls in-REPL helpers (`llm_query`, `llm_query_batched`, \ |
| 61 | `rlm_query`, `rlm_query_batched`) to process it, then returns a \ |
| 62 | synthesized answer. \n\n\ |
| 63 | DO NOT use this tool when: the input fits in your context (just \ |
| 64 | use `read_file` and reason directly); a `grep_files` / \ |
| 65 | `exec_shell` pipeline would answer the question; the task is a \ |
| 66 | short classification or extraction; you need interactive \ |
| 67 | iterative exploration (rlm is one-shot batch). \n\n\ |
| 68 | Use this tool only when the input is genuinely too large to load \ |
| 69 | (a whole file > 50K tokens, a long transcript, a multi-document \ |
| 70 | corpus). It is slower and more expensive than direct reasoning. \n\n\ |
| 71 | Provide `task` (what to do) plus exactly one of `file_path` \ |
| 72 | (workspace-relative, preferred — keeps the long input out of \ |
| 73 | your context entirely) or `content` (inline, capped at 200k \ |
| 74 | chars). The Python helpers (`llm_query`, `rlm_query`, etc.) live \ |
| 75 | INSIDE the REPL — they are not separately-callable tools. \n\n\ |
| 76 | Returns the final synthesized answer as a string." |
| 77 | } |
| 78 | |
| 79 | fn input_schema(&self) -> Value { |
| 80 | json!({ |
| 81 | "type": "object", |
| 82 | "required": ["task"], |
| 83 | "properties": { |
| 84 | "task": { |
| 85 | "type": "string", |
| 86 | "description": "What to do with the input (e.g. \"Summarize the security model\", \"Extract all API endpoints\", \"Categorize each row by sentiment\"). The sub-agent uses this as its objective." |
| 87 | }, |
| 88 | "file_path": { |
| 89 | "type": "string", |
| 90 | "description": "Workspace-relative path to a file to load as PROMPT. Preferred — keeps the long input out of your context. Mutually exclusive with `content`." |
| 91 | }, |
| 92 | "content": { |
| 93 | "type": "string", |
| 94 | "description": "Inline content to load as PROMPT. Use only when the input isn't a file you can point at. Capped at 200k chars." |
| 95 | }, |
| 96 | "max_depth": { |
| 97 | "type": "integer", |
| 98 | "description": "Recursion budget for `sub_rlm()` calls. 0 disables recursion; default 1 matches paper experiments." |
| 99 | } |
| 100 | } |
| 101 | }) |
| 102 | } |
| 103 | |
| 104 | fn capabilities(&self) -> Vec<ToolCapability> { |
| 105 | // Network for the LLM calls; ExecutesCode because the sub-agent |
| 106 | // runs Python in the REPL (which can do filesystem operations |
| 107 | // within its sandbox). |
| 108 | vec![ToolCapability::Network, ToolCapability::ExecutesCode] |
| 109 | } |
| 110 | |
| 111 | fn approval_requirement(&self) -> ApprovalRequirement { |
| 112 | // Same level as parallel_fanout: the model decided to invoke this, the |
| 113 | // user already enabled tools by being in Agent/YOLO mode, and |
| 114 | // every concrete side-effect (file read, LLM call) is bounded. |
| 115 | ApprovalRequirement::Auto |
| 116 | } |
| 117 | |
| 118 | fn supports_parallel(&self) -> bool { |
| 119 | // Each call spins its own sidecar on a kernel-assigned port and |
| 120 | // its own per-turn state file, so two calls don't interfere. |
| 121 | true |
| 122 | } |
| 123 | |
| 124 | async fn execute(&self, input: Value, context: &ToolContext) -> Result<ToolResult, ToolError> { |
| 125 | let Some(client) = self.client.clone() else { |
| 126 | return Err(ToolError::not_available( |
| 127 | "rlm_process requires an active DeepSeek client".to_string(), |
| 128 | )); |
| 129 | }; |
| 130 | |
| 131 | let task = input |
| 132 | .get("task") |
| 133 | .and_then(|v| v.as_str()) |
| 134 | .ok_or_else(|| ToolError::MissingField { |
| 135 | field: "task".to_string(), |
| 136 | })? |
| 137 | .trim(); |
| 138 | if task.is_empty() { |
| 139 | return Err(ToolError::invalid_input("rlm: `task` is empty")); |
| 140 | } |
| 141 | |
| 142 | let file_path = input.get("file_path").and_then(|v| v.as_str()); |
| 143 | let content = input.get("content").and_then(|v| v.as_str()); |
| 144 | |
| 145 | let body = match (file_path, content) { |
| 146 | (Some(_), Some(_)) => { |
| 147 | return Err(ToolError::invalid_input( |
| 148 | "rlm: pass `file_path` OR `content`, not both", |
| 149 | )); |
| 150 | } |
| 151 | (None, None) => { |
| 152 | return Err(ToolError::invalid_input( |
| 153 | "rlm: requires `file_path` (preferred) or `content`", |
| 154 | )); |
| 155 | } |
| 156 | (Some(path), None) => { |
| 157 | let resolved = context.resolve_path(path)?; |
| 158 | tokio::fs::read_to_string(&resolved).await.map_err(|e| { |
| 159 | ToolError::ExecutionFailed { |
| 160 | message: format!("read {}: {e}", resolved.display()), |
| 161 | } |
| 162 | })? |
| 163 | } |
| 164 | (None, Some(c)) => { |
| 165 | if c.chars().count() > MAX_INLINE_CONTENT_CHARS { |
| 166 | return Err(ToolError::invalid_input(format!( |
| 167 | "rlm: inline `content` is {} chars (cap {MAX_INLINE_CONTENT_CHARS}). Pass `file_path` for larger inputs.", |
| 168 | c.chars().count() |
| 169 | ))); |
| 170 | } |
| 171 | c.to_string() |
| 172 | } |
| 173 | }; |
| 174 | |
| 175 | if body.trim().is_empty() { |
| 176 | return Err(ToolError::invalid_input( |
| 177 | "rlm: input is empty after loading", |
| 178 | )); |
| 179 | } |
| 180 | |
| 181 | // Pin child calls to Flash so model-generated tool args cannot quietly |
| 182 | // turn fanout work into Pro-billed requests. The RLM root still uses |
| 183 | // the session model; child helper calls are the cheap batch layer. |
| 184 | let child_model = DEFAULT_CHILD_MODEL.to_string(); |
| 185 | |
| 186 | let max_depth = input |
| 187 | .get("max_depth") |
| 188 | .and_then(|v| v.as_u64()) |
| 189 | .map(|n| n.min(u64::from(u32::MAX)) as u32) |
| 190 | .unwrap_or(DEFAULT_MAX_DEPTH); |
| 191 | |
| 192 | // The tool framework doesn't expose a per-tool event stream, and |
| 193 | // we don't want RLM's progress events to interleave with the |
| 194 | // parent agent's stream. Drain into a no-op channel. |
| 195 | let (tx, mut rx) = tokio::sync::mpsc::channel(64); |
| 196 | let drain = spawn_supervised( |
| 197 | "rlm-progress-drain", |
| 198 | std::panic::Location::caller(), |
| 199 | async move { while rx.recv().await.is_some() {} }, |
| 200 | ); |
| 201 | |
| 202 | // The big body lives only in the REPL as `context`. The small |
| 203 | // `task` rides along as `root_prompt` and is shown to the root |
| 204 | // LLM each iteration so it never forgets the objective. |
| 205 | let result = run_rlm_turn_with_root( |
| 206 | &client, |
| 207 | self.root_model.clone(), |
| 208 | body, |
| 209 | Some(task.to_string()), |
| 210 | child_model.clone(), |
| 211 | tx, |
| 212 | max_depth, |
| 213 | ) |
| 214 | .await; |
| 215 | |
| 216 | drain.abort(); |
| 217 | |
| 218 | if let Some(err) = result.error { |
| 219 | return Err(ToolError::ExecutionFailed { |
| 220 | message: format!( |
| 221 | "rlm: {err} (iterations={}, termination={:?})", |
| 222 | result.iterations, result.termination |
| 223 | ), |
| 224 | }); |
| 225 | } |
| 226 | |
| 227 | if result.answer.trim().is_empty() { |
| 228 | return Err(ToolError::ExecutionFailed { |
| 229 | message: format!( |
| 230 | "rlm: empty answer (termination={:?}, iterations={})", |
| 231 | result.termination, result.iterations |
| 232 | ), |
| 233 | }); |
| 234 | } |
| 235 | |
| 236 | // Surface the termination reason and a brief per-round trace so the |
| 237 | // user can verify the sub-agent actually engaged with `context` |
| 238 | // through sub-LLM calls — not just inferred an answer from the |
| 239 | // preview. |
| 240 | let footer = match result.termination { |
| 241 | RlmTermination::Final => String::new(), |
| 242 | RlmTermination::NoCode => format!( |
| 243 | "\n\n[warning: sub-agent failed to engage the REPL after {} iterations — answer is the model's last raw response]", |
| 244 | result.iterations |
| 245 | ), |
| 246 | RlmTermination::Exhausted => format!( |
| 247 | "\n\n[warning: sub-agent hit the {}-iteration cap without FINAL()]", |
| 248 | result.iterations |
| 249 | ), |
| 250 | RlmTermination::Error => String::new(), |
| 251 | }; |
| 252 | |
| 253 | let trace_summary = if result.trace.is_empty() { |
| 254 | String::from("\n\n[trace: no REPL rounds executed]") |
| 255 | } else { |
| 256 | let mut s = String::from("\n\n[RLM trace]"); |
| 257 | for r in &result.trace { |
| 258 | let head = r |
| 259 | .code_summary |
| 260 | .lines() |
| 261 | .next() |
| 262 | .unwrap_or(r.code_summary.as_str()) |
| 263 | .chars() |
| 264 | .take(80) |
| 265 | .collect::<String>(); |
| 266 | s.push_str(&format!( |
| 267 | "\n round {}: {} sub-LLM call(s), {}ms{} — {}", |
| 268 | r.round, |
| 269 | r.rpc_count, |
| 270 | r.elapsed_ms, |
| 271 | if r.had_error { " (error)" } else { "" }, |
| 272 | head |
| 273 | )); |
| 274 | } |
| 275 | s |
| 276 | }; |
| 277 | |
| 278 | let trace_json: Vec<_> = result |
| 279 | .trace |
| 280 | .iter() |
| 281 | .map(|r| { |
| 282 | json!({ |
| 283 | "round": r.round, |
| 284 | "rpc_count": r.rpc_count, |
| 285 | "elapsed_ms": r.elapsed_ms, |
| 286 | "had_error": r.had_error, |
| 287 | "code_summary": r.code_summary, |
| 288 | "stdout_preview": r.stdout_preview, |
| 289 | }) |
| 290 | }) |
| 291 | .collect(); |
| 292 | |
| 293 | // The `child_*` keys are the contract the engine reads in |
| 294 | // `tool_routing::accrue_child_token_cost_if_any` to roll |
| 295 | // sub-LLM token usage into the session-cost counter. RLM |
| 296 | // spawns its own DeepSeek calls under `child_model`; without |
| 297 | // this accrual the dashboard under-reports a session that |
| 298 | // uses RLM heavily by 10-20× because only the parent turn's |
| 299 | // tokens hit `accrue_session_cost` (#524). |
| 300 | let metadata = json!({ |
| 301 | "iterations": result.iterations, |
| 302 | "duration_ms": result.duration.as_millis() as u64, |
| 303 | "input_tokens": result.usage.input_tokens, |
| 304 | "output_tokens": result.usage.output_tokens, |
| 305 | "child_input_tokens": result.usage.input_tokens, |
| 306 | "child_output_tokens": result.usage.output_tokens, |
| 307 | "child_prompt_cache_hit_tokens": result.usage.prompt_cache_hit_tokens, |
| 308 | "child_prompt_cache_miss_tokens": result.usage.prompt_cache_miss_tokens, |
| 309 | "child_model": child_model, |
| 310 | "termination": format!("{:?}", result.termination).to_lowercase(), |
| 311 | "max_depth": max_depth, |
| 312 | "total_rpcs": result.total_rpcs, |
| 313 | "trace": trace_json, |
| 314 | }); |
| 315 | |
| 316 | Ok( |
| 317 | ToolResult::success(format!("{}{}{}", result.answer, footer, trace_summary)) |
| 318 | .with_metadata(metadata), |
| 319 | ) |
| 320 | } |
| 321 | } |
| 322 | |
| 323 | #[cfg(test)] |
| 324 | mod tests { |
| 325 | use super::*; |
| 326 | |
| 327 | fn tool() -> RlmTool { |
| 328 | RlmTool::new(None, "deepseek-v4-pro".to_string()) |
| 329 | } |
| 330 | |
| 331 | fn ctx() -> ToolContext { |
| 332 | use std::path::PathBuf; |
| 333 | ToolContext::with_auto_approve( |
| 334 | PathBuf::from("."), |
| 335 | false, |
| 336 | PathBuf::from("notes.txt"), |
| 337 | PathBuf::from("mcp.json"), |
| 338 | true, |
| 339 | ) |
| 340 | } |
| 341 | |
| 342 | #[test] |
| 343 | fn name_and_schema() { |
| 344 | let t = tool(); |
| 345 | assert_eq!(t.name(), "rlm"); |
| 346 | let schema = t.input_schema(); |
| 347 | assert!(schema["properties"]["task"].is_object()); |
| 348 | assert!(schema["properties"]["file_path"].is_object()); |
| 349 | assert!(schema["properties"]["content"].is_object()); |
| 350 | assert!(schema["properties"]["max_depth"].is_object()); |
| 351 | let required = schema["required"].as_array().unwrap(); |
| 352 | assert!(required.iter().any(|v| v == "task")); |
| 353 | } |
| 354 | |
| 355 | #[test] |
| 356 | fn approval_is_auto_so_calls_are_unattended() { |
| 357 | assert_eq!(tool().approval_requirement(), ApprovalRequirement::Auto); |
| 358 | } |
| 359 | |
| 360 | #[test] |
| 361 | fn capabilities_include_network_and_executes_code() { |
| 362 | let caps = tool().capabilities(); |
| 363 | assert!(caps.contains(&ToolCapability::Network)); |
| 364 | assert!(caps.contains(&ToolCapability::ExecutesCode)); |
| 365 | } |
| 366 | |
| 367 | #[test] |
| 368 | fn supports_parallel_dispatch() { |
| 369 | assert!(tool().supports_parallel()); |
| 370 | } |
| 371 | |
| 372 | #[tokio::test] |
| 373 | async fn returns_not_available_without_client() { |
| 374 | let t = tool(); |
| 375 | let ctx = ctx(); |
| 376 | let res = t |
| 377 | .execute(json!({"task": "x", "content": "y"}), &ctx) |
| 378 | .await |
| 379 | .expect_err("must error"); |
| 380 | assert!(matches!(res, ToolError::NotAvailable { .. })); |
| 381 | } |
| 382 | |
| 383 | #[tokio::test] |
| 384 | async fn rejects_missing_task() { |
| 385 | let t = RlmTool::new(None, "x".into()); |
| 386 | let ctx = ctx(); |
| 387 | let res = t |
| 388 | .execute(json!({"content": "abc"}), &ctx) |
| 389 | .await |
| 390 | .expect_err("must error"); |
| 391 | // Without a client we hit NotAvailable first. Re-check ordering by |
| 392 | // injecting an obviously-bad payload that would trip earlier. |
| 393 | assert!(matches!( |
| 394 | res, |
| 395 | ToolError::NotAvailable { .. } | ToolError::MissingField { .. } |
| 396 | )); |
| 397 | } |
| 398 | |
| 399 | #[tokio::test] |
| 400 | async fn rejects_both_path_and_content() { |
| 401 | // Even without a client, the input-shape check should fire if we |
| 402 | // bypass the client guard. Simpler: just verify the schema lists |
| 403 | // the two as alternatives via descriptions. |
| 404 | let schema = tool().input_schema(); |
| 405 | let path_desc = schema["properties"]["file_path"]["description"] |
| 406 | .as_str() |
| 407 | .unwrap(); |
| 408 | assert!(path_desc.to_lowercase().contains("mutually exclusive")); |
| 409 | } |
| 410 | } |
| 411 |