Skip to main content

orch/engine/runner/
direct.rs

1//! One-shot agent invocation without tmux.
2//!
3//! Used by the control session and the router LLM to run agents
4//! in a fire-and-forget mode without a persistent tmux session.
5
6use crate::engine::runner::agents::{
7    AgentError, PermissionRules, find_agent_result, get_runner, shell_single_quote,
8    supports_session,
9};
10use anyhow::Result;
11use std::error;
12use std::ffi::OsString;
13use std::fmt;
14use std::fmt::Display;
15use std::fmt::Formatter;
16use std::fmt::Write as _;
17use std::process::Output;
18use std::result;
19use std::time::Duration;
20use tokio::fs;
21use tokio::process::Command;
22use tokio::time;
23
24/// Result of a one-shot agent invocation.
25#[derive(Debug, Clone)]
26pub struct DirectResult {
27    pub text: String,
28    pub input_tokens: Option<u64>,
29    pub output_tokens: Option<u64>,
30    pub cost_usd: Option<f64>,
31}
32
33/// Error type for `run_direct_command_raw()` — carries stdout on non-zero exit
34/// so callers can inspect it for rate-limit detection.
35#[derive(Debug)]
36pub enum DirectCommandError {
37    Timeout {
38        secs: u64,
39    },
40    Spawn {
41        message: String,
42    },
43    NonZeroExit {
44        exit_code: i32,
45        stdout: String,
46        stderr: String,
47    },
48    EmptyResponse {
49        stderr: String,
50    },
51}
52
53impl Display for DirectCommandError {
54    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
55        match self {
56            Self::Timeout { secs } => write!(f, "agent timed out after {secs}s"),
57            Self::Spawn { message } => write!(f, "spawning agent: {message}"),
58            Self::NonZeroExit {
59                exit_code, stderr, ..
60            } => {
61                write!(f, "agent failed (exit {exit_code}): {stderr}")
62            }
63            Self::EmptyResponse { .. } => write!(f, "agent returned empty response"),
64        }
65    }
66}
67
68impl error::Error for DirectCommandError {}
69
70/// Run an agent one-shot without tmux.
71///
72/// Writes temp files to `work_dir`, builds the CLI command via
73/// `get_runner(agent).build_command()`, executes with `timeout`,
74/// then parses with `parse_response()`.
75///
76/// `work_dir` should be an isolated directory (e.g., `~/.orch/state/control/{pid}/`).
77pub async fn run_direct(
78    agent: &str,
79    model: Option<&str>,
80    system_prompt: &str,
81    message: &str,
82    timeout: Duration,
83    work_dir: &str,
84) -> Result<DirectResult> {
85    run_direct_with_session(
86        agent,
87        model,
88        system_prompt,
89        message,
90        timeout,
91        work_dir,
92        None,
93    )
94    .await
95}
96
97/// Configuration for continuing an agent session.
98#[derive(Debug, Clone, Copy)]
99pub struct SessionContinuation<'a> {
100    pub session_id: &'a str,
101    pub resume: bool,
102}
103
104/// Run an agent one-shot with an optional `--session-id` or `--resume` for conversation continuity.
105///
106/// For agents that support sessions (claude, kimi, minimax, grok), appends
107/// `--session-id <uuid>` when starting a new session, or `--resume <uuid>` when
108/// continuing one. Other agents ignore the parameter.
109pub async fn run_direct_with_session(
110    agent: &str,
111    model: Option<&str>,
112    system_prompt: &str,
113    message: &str,
114    timeout: Duration,
115    work_dir: &str,
116    session: Option<SessionContinuation<'_>>,
117) -> Result<DirectResult> {
118    let place = DirectPlace {
119        files_dir: work_dir.to_string(),
120        cwd: work_dir.to_string(),
121        permissions: PermissionRules::deny_read_only(),
122        sandbox: Vec::new(),
123        env: Vec::new(),
124        unset: Vec::new(),
125    };
126    run_direct_at(
127        agent,
128        model,
129        system_prompt,
130        message,
131        timeout,
132        &place,
133        session,
134    )
135    .await
136}
137
138/// Where a direct call runs, what its agent may do, and the sandbox around it
139#[derive(Debug, Clone)]
140pub struct DirectPlace {
141    /// Where the prompt files go, kept out of `cwd` so a checkout gets nothing written to it
142    pub files_dir: String,
143    /// The folder the agent works in
144    pub cwd: String,
145    pub permissions: PermissionRules,
146    /// A sandbox-jail prefix for the command, empty to run without one
147    pub sandbox: Vec<OsString>,
148    /// Extra environment for the agent
149    pub env: Vec<(String, String)>,
150    /// Variables taken out of the daemon's environment, such as tokens the agent must not see
151    pub unset: Vec<String>,
152}
153
154/// Like [`run_direct_with_session`], in the place `place` describes
155pub async fn run_direct_at(
156    agent: &str,
157    model: Option<&str>,
158    system_prompt: &str,
159    message: &str,
160    timeout: Duration,
161    place: &DirectPlace,
162    session: Option<SessionContinuation<'_>>,
163) -> Result<DirectResult> {
164    let work_dir = place.files_dir.as_str();
165    let sys_file = format!("{work_dir}/system.md");
166    let msg_file = format!("{work_dir}/message.txt");
167
168    fs::write(&sys_file, system_prompt).await?;
169    fs::write(&msg_file, message).await?;
170
171    let runner = get_runner(agent);
172    let timeout_cmd = format!("timeout {}", timeout.as_secs());
173
174    let mut shell_cmd = runner.build_command(
175        model,
176        &timeout_cmd,
177        &sys_file,
178        &msg_file,
179        &place.permissions,
180    );
181
182    if let Some(s) = session {
183        shell_cmd = insert_session_flag(agent, shell_cmd, s);
184    }
185
186    run_shell_command(&shell_cmd, place, timeout, agent).await
187}
188
189/// Append `--session-id` or `--resume` for agents that keep a conversation.
190///
191/// Claude-family commands redirect the prompt with `< "file"`, so the flag is
192/// inserted before that redirect. Grok takes `--prompt-file` and has no
193/// redirect, so the flag is appended.
194fn insert_session_flag(
195    agent: &str,
196    mut shell_cmd: String,
197    session: SessionContinuation<'_>,
198) -> String {
199    if !supports_session(agent) {
200        return shell_cmd;
201    }
202    let flag = if session.resume {
203        "--resume"
204    } else {
205        "--session-id"
206    };
207    let quoted = shell_single_quote(session.session_id);
208    if let Some(pos) = shell_cmd.rfind("< \"") {
209        shell_cmd.insert_str(pos, &format!("{flag} {quoted} \\\n  "));
210    } else if agent == "grok" {
211        let _ = write!(shell_cmd, " \\\n  {flag} {quoted}");
212    } else {
213        tracing::warn!(
214            agent,
215            flag,
216            session_id = session.session_id,
217            "could not insert session flag: '< \"' pattern not found in shell command"
218        );
219    }
220    shell_cmd
221}
222
223/// Execute an already-built `tokio::process::Command` one-shot, returning raw stdout.
224///
225/// Unlike `run_direct_command()`, this does NOT call `parse_response()`.
226/// Use this when the caller needs the raw stdout to parse itself (e.g., router).
227/// Returns `Err(DirectCommandError::NonZeroExit { stdout, .. })` so callers can
228/// inspect stdout for rate-limit messages even on failure.
229pub async fn run_direct_command_raw(
230    cmd: &mut Command,
231    timeout: Duration,
232) -> result::Result<String, DirectCommandError> {
233    cmd.kill_on_drop(true);
234    let output = time::timeout(timeout + Duration::from_secs(5), cmd.output())
235        .await
236        .map_err(|_| DirectCommandError::Timeout {
237            secs: timeout.as_secs(),
238        })?
239        .map_err(|e| DirectCommandError::Spawn {
240            message: e.to_string(),
241        })?;
242
243    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
244    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
245    let exit_code = output.status.code().unwrap_or(-1);
246
247    if !output.status.success() {
248        return Err(DirectCommandError::NonZeroExit {
249            exit_code,
250            stdout,
251            stderr,
252        });
253    }
254    if stdout.is_empty() {
255        return Err(DirectCommandError::EmptyResponse { stderr });
256    }
257    Ok(stdout)
258}
259
260/// Shared output-handling logic: parse stdout, classify errors.
261fn finish_output(output: &Output, agent: &str) -> Result<DirectResult> {
262    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
263    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
264    let exit_code = output.status.code().unwrap_or(-1);
265
266    let runner = get_runner(agent);
267
268    if !output.status.success() {
269        let err = runner.classify_error(exit_code, &stdout, &stderr);
270        anyhow::bail!("{err}");
271    }
272
273    match runner.parse_response(&stdout) {
274        Ok(parsed) => {
275            let text = reply_text(&stdout, &parsed.response.summary);
276            Ok(DirectResult {
277                text,
278                input_tokens: parsed.input_tokens,
279                output_tokens: parsed.output_tokens,
280                cost_usd: parsed.cost_usd,
281            })
282        }
283        Err(AgentError::InvalidResponse { .. }) => {
284            let (text, input_tokens, output_tokens) = extract_from_envelope(&stdout);
285            Ok(DirectResult {
286                text,
287                input_tokens,
288                output_tokens,
289                cost_usd: find_agent_result(agent, &stdout).and_then(|r| r.cost_usd),
290            })
291        }
292        Err(err) => anyhow::bail!("{err}"),
293    }
294}
295
296async fn run_shell_command(
297    shell_cmd: &str,
298    place: &DirectPlace,
299    timeout: Duration,
300    agent: &str,
301) -> Result<DirectResult> {
302    let mut cmd = match place.sandbox.split_first() {
303        Some((program, args)) => {
304            // The agent's temp files go to a dir the sandbox lets it write, and no SSH agent is offered
305            let mut c = Command::new(program);
306            c.args(args)
307                .arg("/bin/bash")
308                .env_remove("SSH_AUTH_SOCK")
309                .env("TMPDIR", &place.files_dir);
310            c
311        }
312        None => Command::new("bash"),
313    };
314    for name in &place.unset {
315        cmd.env_remove(name);
316    }
317
318    cmd.arg("-c")
319        .arg(shell_cmd)
320        .envs(place.env.iter().map(|(k, v)| (k, v)))
321        .current_dir(&place.cwd)
322        .kill_on_drop(true);
323    let output = time::timeout(timeout + Duration::from_secs(5), cmd.output())
324        .await
325        .map_err(|_| anyhow::anyhow!("agent timed out after {}s", timeout.as_secs()))?
326        .map_err(|e| anyhow::anyhow!("spawning agent: {e}"))?;
327
328    finish_output(&output, agent)
329}
330
331/**
332 * The text a direct call answers with. A summary synthesized from free text holds only its start,
333 * so a reply in a result envelope comes back whole, and the summary stays for an agent that
334 * answered with the JSON task response
335 **/
336fn reply_text(stdout: &str, summary: &str) -> String {
337    let (text, _, _) = extract_from_envelope(stdout);
338    let in_envelope = text != stdout;
339    let head = text.trim_start();
340    let task_json = head.starts_with('{') || head.starts_with("```json");
341    if in_envelope && !text.trim().is_empty() && !task_json {
342        return text;
343    }
344
345    if summary.is_empty() {
346        stdout.to_string()
347    } else {
348        summary.to_string()
349    }
350}
351
352/// Extract text and token usage from a Claude JSON envelope or raw output.
353///
354/// Handles both single JSON blobs (`--output-format json`) and NDJSON streams
355/// (`--output-format stream-json`): finds the last line with `"type":"result"`.
356pub(crate) fn extract_from_envelope(raw: &str) -> (String, Option<u64>, Option<u64>) {
357    // Find the result line: last NDJSON line with "type":"result", or the full string
358    let candidate = raw
359        .lines()
360        .filter(|l| !l.trim().is_empty())
361        .rev()
362        .find(|line| {
363            serde_json::from_str::<serde_json::Value>(line)
364                .ok()
365                .and_then(|v| {
366                    v.get("type")
367                        .and_then(|t| t.as_str())
368                        .map(|t| t == "result")
369                })
370                .unwrap_or(false)
371        })
372        .unwrap_or(raw);
373
374    if let Ok(value) = serde_json::from_str::<serde_json::Value>(candidate)
375        && let Some(obj) = value.as_object()
376        && obj.get("type").and_then(|v| v.as_str()) == Some("result")
377    {
378        let text = obj
379            .get("result")
380            .and_then(|v| v.as_str())
381            .unwrap_or("")
382            .to_string();
383        let input_tokens = obj
384            .get("usage")
385            .and_then(|u| u.get("input_tokens"))
386            .and_then(serde_json::Value::as_u64);
387        let output_tokens = obj
388            .get("usage")
389            .and_then(|u| u.get("output_tokens"))
390            .and_then(serde_json::Value::as_u64);
391        return (text, input_tokens, output_tokens);
392    }
393    (raw.to_string(), None, None)
394}
395
396#[cfg(test)]
397mod tests {
398    use super::*;
399
400    #[test]
401    fn session_flag_appends_for_grok_prompt_file() {
402        let cmd = "grok --prompt-file '/tmp/msg.txt'".to_string();
403        let updated = insert_session_flag(
404            "grok",
405            cmd,
406            SessionContinuation {
407                session_id: "abc",
408                resume: false,
409            },
410        );
411        assert!(updated.contains("--session-id 'abc'"), "{updated}");
412        assert!(updated.contains("--prompt-file"), "{updated}");
413    }
414
415    #[test]
416    fn session_flag_inserts_before_stdin_redirect() {
417        let cmd = "claude -p < \"/tmp/msg.txt\"".to_string();
418        let updated = insert_session_flag(
419            "claude",
420            cmd,
421            SessionContinuation {
422                session_id: "abc",
423                resume: true,
424            },
425        );
426        assert!(updated.contains("--resume 'abc'"), "{updated}");
427        let resume = updated.find("--resume").unwrap();
428        let redirect = updated.find("< \"").unwrap();
429        assert!(resume < redirect, "{updated}");
430    }
431
432    #[test]
433    fn session_flag_ignored_for_codex() {
434        let cmd = "codex exec".to_string();
435        let updated = insert_session_flag(
436            "codex",
437            cmd.clone(),
438            SessionContinuation {
439                session_id: "abc",
440                resume: false,
441            },
442        );
443        assert_eq!(updated, cmd);
444    }
445
446    #[test]
447    fn a_long_reply_comes_back_whole() {
448        let long = format!(
449            "Plan:\n{}",
450            "- a step that says usage: hello <name>\n".repeat(40)
451        );
452        let raw = serde_json::json!({"type": "result", "result": long}).to_string();
453        assert_eq!(reply_text(&raw, "Plan:"), long, "not cut to the summary");
454    }
455
456    #[test]
457    fn a_json_task_reply_keeps_its_summary() {
458        let raw = serde_json::json!({"type": "result", "result": "{\"status\":\"done\",\"summary\":\"ok\"}"}).to_string();
459        assert_eq!(reply_text(&raw, "ok"), "ok", "the task summary");
460    }
461
462    #[test]
463    fn test_extract_from_envelope_claude_json() {
464        let raw = r#"{"type":"result","result":"Hello world","usage":{"input_tokens":10,"output_tokens":5}}"#;
465        let (text, input, output) = extract_from_envelope(raw);
466        assert_eq!(text, "Hello world");
467        assert_eq!(input, Some(10));
468        assert_eq!(output, Some(5));
469    }
470
471    #[test]
472    fn test_extract_from_envelope_ndjson_stream() {
473        let raw = concat!(
474            r#"{"type":"system","subtype":"init"}"#,
475            "\n",
476            r#"{"type":"assistant","message":{}}"#,
477            "\n",
478            r#"{"type":"result","result":"streamed result","usage":{"input_tokens":20,"output_tokens":8}}"#,
479            "\n"
480        );
481        let (text, input, output) = extract_from_envelope(raw);
482        assert_eq!(text, "streamed result");
483        assert_eq!(input, Some(20));
484        assert_eq!(output, Some(8));
485    }
486
487    #[test]
488    fn test_extract_from_envelope_not_envelope() {
489        let raw = "plain text response";
490        let (text, input, output) = extract_from_envelope(raw);
491        assert_eq!(text, "plain text response");
492        assert_eq!(input, None);
493        assert_eq!(output, None);
494    }
495
496    #[test]
497    fn test_extract_from_envelope_wrong_type() {
498        let raw = r#"{"type":"error","message":"something"}"#;
499        let (text, input, output) = extract_from_envelope(raw);
500        assert_eq!(text, raw);
501        assert_eq!(input, None);
502        assert_eq!(output, None);
503    }
504
505    #[test]
506    fn test_direct_result_debug() {
507        let r = DirectResult {
508            text: "hi".to_string(),
509            input_tokens: Some(1),
510            output_tokens: Some(2),
511            cost_usd: None,
512        };
513        assert!(format!("{r:?}").contains("hi"));
514    }
515
516    #[test]
517    fn test_direct_command_error_display() {
518        assert_eq!(
519            DirectCommandError::Timeout { secs: 30 }.to_string(),
520            "agent timed out after 30s"
521        );
522        assert_eq!(
523            DirectCommandError::Spawn {
524                message: "no binary".to_string()
525            }
526            .to_string(),
527            "spawning agent: no binary"
528        );
529        assert_eq!(
530            DirectCommandError::NonZeroExit {
531                exit_code: 1,
532                stdout: "out".to_string(),
533                stderr: "err".to_string()
534            }
535            .to_string(),
536            "agent failed (exit 1): err"
537        );
538        assert_eq!(
539            DirectCommandError::EmptyResponse {
540                stderr: String::new()
541            }
542            .to_string(),
543            "agent returned empty response"
544        );
545    }
546}