sqlite_graphrag/commands/
opencode_runner.rs

1//! OpenCode headless runner for ingest and enrich pipelines (v1.0.90).
2//!
3//! Symmetric to `claude_runner.rs` (claude -p) and `codex_spawn.rs`
4//! (codex exec). Builds the `opencode run` command, parses NDJSON
5//! output, and provides rate-limit backoff.
6
7use crate::errors::AppError;
8use std::path::{Path, PathBuf};
9use std::process::Stdio;
10use tokio::process::Command;
11
12/// Default timeout per opencode invocation in seconds.
13const DEFAULT_OPENCODE_TIMEOUT_SECS: u64 = 300;
14
15/// Minimum supported opencode version.
16const MIN_OPENCODE_VERSION: (u64, u64, u64) = (1, 17, 0);
17
18/// Resolve the opencode binary path.
19///
20/// Precedence: `SQLITE_GRAPHRAG_OPENCODE_BINARY` env var > `which::which("opencode")`.
21pub fn find_opencode_binary_with_override(explicit: Option<&Path>) -> Result<PathBuf, AppError> {
22    if let Some(p) = explicit {
23        if p.exists() {
24            return Ok(p.to_path_buf());
25        }
26        return Err(AppError::Validation(format!(
27            "opencode binary not found at explicit path: {}",
28            p.display()
29        )));
30    }
31    if let Ok(path) = std::env::var("SQLITE_GRAPHRAG_OPENCODE_BINARY") {
32        let p = PathBuf::from(path);
33        if p.exists() {
34            return Ok(p);
35        }
36        tracing::warn!(
37            target: "opencode_runner",
38            path = %p.display(),
39            "SQLITE_GRAPHRAG_OPENCODE_BINARY is set but file does not exist; falling back to PATH"
40        );
41    }
42    which::which("opencode").map_err(|_| {
43        AppError::Validation(
44            "`opencode` not found on PATH. Install opencode (>= 1.17) or set \
45             SQLITE_GRAPHRAG_OPENCODE_BINARY to the binary path."
46                .into(),
47        )
48    })
49}
50
51pub fn find_opencode_binary() -> Result<PathBuf, AppError> {
52    find_opencode_binary_with_override(None)
53}
54
55/// Resolve the opencode model name.
56///
57/// Precedence: explicit `model` arg > `SQLITE_GRAPHRAG_OPENCODE_MODEL` env var
58/// > default `opencode/big-pickle`.
59///
60/// NOTE: intentionally does NOT fall back to `SQLITE_GRAPHRAG_LLM_MODEL` because
61/// that var typically holds a codex/claude model (e.g. "gpt-5.4-mini") that
62/// opencode does not recognise — cross-contamination caused
63/// ProviderModelNotFoundError (v1.0.90 audit).
64pub fn resolve_opencode_model(model_override: Option<&str>) -> String {
65    if let Some(m) = model_override {
66        return m.to_string();
67    }
68    std::env::var("SQLITE_GRAPHRAG_OPENCODE_MODEL")
69        .unwrap_or_else(|_| "opencode/big-pickle".to_string())
70}
71
72/// Resolve the opencode timeout in seconds.
73///
74/// Precedence: explicit arg > `SQLITE_GRAPHRAG_OPENCODE_TIMEOUT` env var > default 300s.
75pub fn resolve_opencode_timeout(timeout_override: Option<u64>) -> u64 {
76    if let Some(t) = timeout_override {
77        return t;
78    }
79    std::env::var("SQLITE_GRAPHRAG_OPENCODE_TIMEOUT")
80        .ok()
81        .and_then(|v| v.parse::<u64>().ok())
82        .unwrap_or(DEFAULT_OPENCODE_TIMEOUT_SECS)
83}
84
85/// Validate the installed opencode version meets the minimum requirement.
86pub fn validate_opencode_version(binary: &Path) -> Result<(u64, u64, u64), AppError> {
87    let output = std::process::Command::new(binary)
88        .arg("--version")
89        .output()
90        .map_err(|e| AppError::Validation(format!("failed to run opencode --version: {e}")))?;
91
92    let raw = String::from_utf8_lossy(&output.stdout).trim().to_string();
93    let raw = if raw.is_empty() {
94        String::from_utf8_lossy(&output.stderr).trim().to_string()
95    } else {
96        raw
97    };
98
99    parse_version(&raw).and_then(|v| {
100        if v >= MIN_OPENCODE_VERSION {
101            Ok(v)
102        } else {
103            Err(AppError::Validation(format!(
104                "opencode version {}.{}.{} is below minimum {}.{}.{}",
105                v.0,
106                v.1,
107                v.2,
108                MIN_OPENCODE_VERSION.0,
109                MIN_OPENCODE_VERSION.1,
110                MIN_OPENCODE_VERSION.2,
111            )))
112        }
113    })
114}
115
116fn parse_version(raw: &str) -> Result<(u64, u64, u64), AppError> {
117    // opencode --version returns just the version number, e.g. "1.17.7"
118    let digits: String = raw
119        .chars()
120        .filter(|c| c.is_ascii_digit() || *c == '.')
121        .collect();
122    let parts: Vec<&str> = digits.split('.').collect();
123    if parts.len() >= 3 {
124        if let (Ok(major), Ok(minor), Ok(patch)) = (
125            parts[0].parse::<u64>(),
126            parts[1].parse::<u64>(),
127            parts[2].parse::<u64>(),
128        ) {
129            return Ok((major, minor, patch));
130        }
131    }
132    Err(AppError::Validation(format!(
133        "could not parse opencode version from: {raw}"
134    )))
135}
136
137/// Propagate opencode-relevant env vars into a subprocess.
138///
139/// After `env_clear()`, the subprocess only has PATH and HOME. OpenCode
140/// may need provider API keys (OPENROUTER_API_KEY, ANTHROPIC_AUTH_TOKEN,
141/// etc.), XDG dirs, LANG/TERM for proper operation. This helper forwards
142/// any env var matching the OPENCODE_*, OPENROUTER_*, XDG_*, LANG, TERM
143/// prefixes from the parent process.
144pub fn propagate_opencode_env(cmd: &mut Command) {
145    const PREFIXES: &[&str] = &["OPENCODE_", "OPENROUTER_", "XDG_"];
146    const EXACT: &[&str] = &["LANG", "TERM", "USER", "LOGNAME", "TMPDIR"];
147    for (key, val) in std::env::vars() {
148        if PREFIXES.iter().any(|p| key.starts_with(p)) || EXACT.contains(&key.as_str()) {
149            cmd.env(&key, &val);
150        }
151    }
152}
153
154/// Build the opencode run command with hardening flags.
155///
156/// Unlike codex (9 flags) and claude (7 flags), opencode has only
157/// `--dangerously-skip-permissions` for auto-approval.
158pub fn build_opencode_command(
159    binary: &Path,
160    model: &str,
161    prompt: &str,
162) -> Result<Command, AppError> {
163    let mut cmd = Command::new(binary);
164    cmd.arg("run")
165        .arg("--format")
166        .arg("json")
167        .arg("-m")
168        .arg(model)
169        .arg("--dangerously-skip-permissions")
170        .arg(prompt)
171        .env_clear()
172        .env("PATH", std::env::var("PATH").unwrap_or_default())
173        .env("HOME", std::env::var("HOME").unwrap_or_default())
174        .stdin(Stdio::null())
175        .stdout(Stdio::piped())
176        .stderr(Stdio::piped())
177        .kill_on_drop(true);
178    propagate_opencode_env(&mut cmd);
179    crate::spawn::apply_cwd_isolation_tokio(&mut cmd)?;
180    Ok(cmd)
181}
182
183/// Parse the NDJSON output from `opencode run --format json`.
184///
185/// The output has 3 event types:
186/// - `step_start`: ignored
187/// - `text`: `.part.text` contains the LLM response text
188/// - `step_finish`: `.part.tokens` and `.part.cost` for accounting
189///
190/// Returns `(response_text, cost, tokens)`.
191pub fn parse_opencode_output(stdout: &str) -> Result<(String, f64, u64), AppError> {
192    let mut texts: Vec<String> = Vec::new();
193    let mut cost: f64 = 0.0;
194    let mut tokens: u64 = 0;
195
196    for line in stdout.lines() {
197        let trimmed = line.trim();
198        if trimmed.is_empty() {
199            continue;
200        }
201        let Ok(event) = serde_json::from_str::<serde_json::Value>(trimmed) else {
202            continue;
203        };
204        let event_type = event.get("type").and_then(|t| t.as_str()).unwrap_or("");
205        match event_type {
206            "text" => {
207                if let Some(text) = event
208                    .get("part")
209                    .and_then(|p| p.get("text"))
210                    .and_then(|t| t.as_str())
211                {
212                    texts.push(text.to_string());
213                }
214            }
215            "step_finish" => {
216                if let Some(part) = event.get("part") {
217                    if let Some(c) = part.get("cost").and_then(|c| c.as_f64()) {
218                        cost = c;
219                    }
220                    if let Some(t) = part
221                        .get("tokens")
222                        .and_then(|t| t.get("total"))
223                        .and_then(|t| t.as_u64())
224                    {
225                        tokens = t;
226                    }
227                }
228            }
229            _ => {}
230        }
231    }
232
233    if texts.is_empty() {
234        return Err(AppError::Embedding(
235            "opencode returned no text events in NDJSON output".to_string(),
236        ));
237    }
238
239    Ok((texts.concat(), cost, tokens))
240}
241
242/// Parse a JSON value from opencode output text.
243///
244/// Opencode has no `--output-schema`, so the LLM may include markdown
245/// fences or explanation text around the JSON. This function tries:
246/// 1. Direct JSON parse of the full text
247/// 2. Extract JSON from markdown code fences
248/// 3. Find the first `{` to last `}` substring
249pub fn parse_json_from_opencode_text<T: serde::de::DeserializeOwned>(
250    text: &str,
251) -> Result<T, String> {
252    // Strategy 1: direct parse
253    if let Ok(parsed) = serde_json::from_str::<T>(text) {
254        return Ok(parsed);
255    }
256
257    // Strategy 2: extract from markdown code fence
258    if let Some(start) = text.find("```json") {
259        let after_fence = &text[start + 7..];
260        if let Some(end) = after_fence.find("```") {
261            let json_str = after_fence[..end].trim();
262            if let Ok(parsed) = serde_json::from_str::<T>(json_str) {
263                return Ok(parsed);
264            }
265        }
266    }
267    if let Some(start) = text.find("```") {
268        let after_fence = &text[start + 3..];
269        if let Some(end) = after_fence.find("```") {
270            let json_str = after_fence[..end].trim();
271            if let Ok(parsed) = serde_json::from_str::<T>(json_str) {
272                return Ok(parsed);
273            }
274        }
275    }
276
277    // Strategy 3: find first { to last }
278    if let (Some(start), Some(end)) = (text.find('{'), text.rfind('}')) {
279        if start < end {
280            let json_str = &text[start..=end];
281            if let Ok(parsed) = serde_json::from_str::<T>(json_str) {
282                return Ok(parsed);
283            }
284        }
285    }
286
287    Err(format!(
288        "could not extract valid JSON from opencode response: {}",
289        &text[..text.len().min(200)]
290    ))
291}
292
293/// Call opencode headless and return the parsed JSON response.
294///
295/// Combines `build_opencode_command`, subprocess execution with timeout,
296/// `parse_opencode_output`, and `parse_json_from_opencode_text`.
297pub async fn call_opencode<T: serde::de::DeserializeOwned>(
298    binary: &Path,
299    model: &str,
300    prompt: &str,
301    timeout_secs: u64,
302) -> Result<(T, f64, u64), AppError> {
303    let mut cmd = build_opencode_command(binary, model, prompt)?;
304    let timeout = std::time::Duration::from_secs(timeout_secs);
305
306    let output = match tokio::time::timeout(timeout, cmd.output()).await {
307        Err(_elapsed) => {
308            return Err(AppError::Embedding(format!(
309                "opencode timed out after {timeout_secs}s"
310            )));
311        }
312        Ok(Err(e)) => {
313            return Err(AppError::Embedding(format!(
314                "failed to spawn opencode: {e}"
315            )));
316        }
317        Ok(Ok(o)) => o,
318    };
319
320    if !output.status.success() {
321        let stderr = String::from_utf8_lossy(&output.stderr);
322        let stdout = String::from_utf8_lossy(&output.stdout);
323        return Err(AppError::Embedding(format!(
324            "opencode exited with {}: stderr={}, stdout={}",
325            output.status,
326            &stderr[..stderr.len().min(500)],
327            &stdout[..stdout.len().min(500)],
328        )));
329    }
330
331    let stdout_str = String::from_utf8_lossy(&output.stdout);
332    let (text, _cost, _tokens) = parse_opencode_output(&stdout_str)?;
333    let parsed: T = parse_json_from_opencode_text(&text)
334        .map_err(|e| AppError::Embedding(format!("opencode JSON parse failed: {e}")))?;
335
336    Ok((parsed, _cost, _tokens))
337}
338
339/// Propagate opencode-relevant env vars into a sync subprocess.
340///
341/// Same logic as `propagate_opencode_env` but for `std::process::Command`.
342pub fn propagate_opencode_env_sync(cmd: &mut std::process::Command) {
343    const PREFIXES: &[&str] = &["OPENCODE_", "OPENROUTER_", "XDG_"];
344    const EXACT: &[&str] = &["LANG", "TERM", "USER", "LOGNAME", "TMPDIR"];
345    for (key, val) in std::env::vars() {
346        if PREFIXES.iter().any(|p| key.starts_with(p)) || EXACT.contains(&key.as_str()) {
347            cmd.env(&key, &val);
348        }
349    }
350}
351
352/// Build a sync `std::process::Command` for opencode.
353///
354/// Mirror of `build_opencode_command` but returns `std::process::Command`
355/// for use in the enrich pipeline which uses `wait_timeout` (sync).
356pub fn build_opencode_command_sync(
357    binary: &Path,
358    model: &str,
359    prompt: &str,
360    input_text: &str,
361) -> Result<std::process::Command, AppError> {
362    let full_prompt = if input_text.is_empty() {
363        prompt.to_string()
364    } else {
365        format!("{prompt}\n\n{input_text}")
366    };
367    let mut cmd = std::process::Command::new(binary);
368    cmd.arg("run")
369        .arg("--format")
370        .arg("json")
371        .arg("-m")
372        .arg(model)
373        .arg("--dangerously-skip-permissions")
374        .arg(&full_prompt)
375        .env_clear()
376        .env("PATH", std::env::var("PATH").unwrap_or_default())
377        .env("HOME", std::env::var("HOME").unwrap_or_default())
378        .stdin(std::process::Stdio::null())
379        .stdout(std::process::Stdio::piped())
380        .stderr(std::process::Stdio::piped());
381    propagate_opencode_env_sync(&mut cmd);
382    crate::spawn::apply_cwd_isolation(&mut cmd)?;
383    Ok(cmd)
384}
385
386/// Spawn opencode with setsid for process group isolation but WITHOUT
387/// RLIMIT_AS. The Bun runtime inside opencode uses aggressive virtual
388/// memory mappings that exceed the 4 GB limit applied to claude/codex.
389#[cfg(target_os = "linux")]
390pub fn spawn_opencode(cmd: &mut std::process::Command) -> std::io::Result<std::process::Child> {
391    use std::os::unix::process::CommandExt;
392    unsafe {
393        cmd.pre_exec(|| {
394            let sid = libc::setsid();
395            if sid == -1 {
396                let err = std::io::Error::last_os_error();
397                if err.raw_os_error() != Some(libc::EPERM) {
398                    return Err(err);
399                }
400            }
401            Ok(())
402        });
403    }
404    cmd.spawn()
405}
406
407#[cfg(not(target_os = "linux"))]
408pub fn spawn_opencode(cmd: &mut std::process::Command) -> std::io::Result<std::process::Child> {
409    #[cfg(unix)]
410    {
411        use std::os::unix::process::CommandExt;
412        unsafe {
413            cmd.pre_exec(|| {
414                let _ = libc::setsid();
415                Ok(())
416            });
417        }
418    }
419    cmd.spawn()
420}
421
422#[cfg(test)]
423mod tests {
424    use super::*;
425
426    #[test]
427    fn parse_version_valid() {
428        assert_eq!(parse_version("1.17.7").unwrap(), (1, 17, 7));
429        assert_eq!(parse_version("2.0.0").unwrap(), (2, 0, 0));
430    }
431
432    #[test]
433    fn parse_version_with_prefix() {
434        assert_eq!(parse_version("v1.17.7").unwrap(), (1, 17, 7));
435        assert_eq!(parse_version("opencode 1.17.7").unwrap(), (1, 17, 7));
436    }
437
438    #[test]
439    fn parse_version_invalid() {
440        assert!(parse_version("unknown").is_err());
441        assert!(parse_version("").is_err());
442    }
443
444    #[test]
445    fn validate_version_rejects_old() {
446        // We can't easily test with a real binary, so test the parse path
447        let v = parse_version("1.16.0").unwrap();
448        assert!(v < MIN_OPENCODE_VERSION);
449    }
450
451    #[test]
452    fn validate_version_accepts_minimum() {
453        let v = parse_version("1.17.0").unwrap();
454        assert!(v >= MIN_OPENCODE_VERSION);
455    }
456
457    #[test]
458    fn resolve_model_uses_default() {
459        // When no override and no env var, should return default
460        let model = resolve_opencode_model(None);
461        // May be overridden by env in CI, so just check it's non-empty
462        assert!(!model.is_empty());
463    }
464
465    #[test]
466    fn resolve_model_uses_override() {
467        let model = resolve_opencode_model(Some("opencode/test-model"));
468        assert_eq!(model, "opencode/test-model");
469    }
470
471    #[test]
472    fn resolve_timeout_uses_default() {
473        let t = resolve_opencode_timeout(None);
474        assert!(t > 0);
475    }
476
477    #[test]
478    fn resolve_timeout_uses_override() {
479        assert_eq!(resolve_opencode_timeout(Some(600)), 600);
480    }
481
482    #[test]
483    fn parse_opencode_output_extracts_text() {
484        let stdout = r#"{"type":"step_start","timestamp":1234,"sessionID":"ses_test","part":{"type":"step-start"}}
485{"type":"text","timestamp":1235,"sessionID":"ses_test","part":{"type":"text","text":"{\"entities\":[]}"}}
486{"type":"step_finish","timestamp":1236,"sessionID":"ses_test","part":{"type":"step-finish","tokens":{"total":100,"input":90,"output":10,"reasoning":0},"cost":0.0}}"#;
487
488        let (text, cost, tokens) = parse_opencode_output(stdout).unwrap();
489        assert_eq!(text, "{\"entities\":[]}");
490        assert_eq!(cost, 0.0);
491        assert_eq!(tokens, 100);
492    }
493
494    #[test]
495    fn parse_opencode_output_concatenates_multiple_text_events() {
496        let stdout = r#"{"type":"step_start","timestamp":1234,"sessionID":"s","part":{"type":"step-start"}}
497{"type":"text","timestamp":1235,"sessionID":"s","part":{"type":"text","text":"{\"ent"}}
498{"type":"text","timestamp":1236,"sessionID":"s","part":{"type":"text","text":"ities\":[]}"}}
499{"type":"step_finish","timestamp":1237,"sessionID":"s","part":{"type":"step-finish","tokens":{"total":50,"input":40,"output":10,"reasoning":0},"cost":0}}"#;
500
501        let (text, _, _) = parse_opencode_output(stdout).unwrap();
502        assert_eq!(text, "{\"entities\":[]}");
503    }
504
505    #[test]
506    fn parse_opencode_output_empty_fails() {
507        assert!(parse_opencode_output("").is_err());
508        assert!(parse_opencode_output("{\"type\":\"step_start\"}").is_err());
509    }
510
511    #[test]
512    fn parse_json_from_opencode_text_direct() {
513        let text = r#"{"entities":[],"relationships":[]}"#;
514        let parsed: serde_json::Value = parse_json_from_opencode_text(text).unwrap();
515        assert!(parsed.get("entities").is_some());
516    }
517
518    #[test]
519    fn parse_json_from_opencode_text_markdown_fence() {
520        let text = "Here is the result:\n```json\n{\"entities\":[]}\n```\nDone.";
521        let parsed: serde_json::Value = parse_json_from_opencode_text(text).unwrap();
522        assert!(parsed.get("entities").is_some());
523    }
524
525    #[test]
526    fn parse_json_from_opencode_text_extract_braces() {
527        let text = "The answer is {\"entities\":[]} and that's it.";
528        let parsed: serde_json::Value = parse_json_from_opencode_text(text).unwrap();
529        assert!(parsed.get("entities").is_some());
530    }
531
532    #[test]
533    fn parse_json_from_opencode_text_invalid() {
534        assert!(parse_json_from_opencode_text::<serde_json::Value>("no json here").is_err());
535    }
536
537    #[test]
538    fn build_command_has_correct_args() {
539        let cmd = build_opencode_command(
540            Path::new("/usr/bin/opencode"),
541            "opencode/big-pickle",
542            "test prompt",
543        )
544        .unwrap();
545        let argv: Vec<String> = cmd
546            .as_std()
547            .get_args()
548            .filter_map(|a| a.to_str().map(|s| s.to_string()))
549            .collect();
550
551        assert!(argv.contains(&"run".to_string()));
552        assert!(argv.contains(&"--format".to_string()));
553        assert!(argv.contains(&"json".to_string()));
554        assert!(argv.contains(&"-m".to_string()));
555        assert!(argv.contains(&"opencode/big-pickle".to_string()));
556        assert!(argv.contains(&"--dangerously-skip-permissions".to_string()));
557        assert!(argv.contains(&"test prompt".to_string()));
558    }
559}
sqlite_graphrag/commands/opencode_runner.rs

sqlite_graphrag/commands/
opencode_runner.rs
