Skip to main content

rigspark_runtime/
connect.rs

1//! Points third-party coding agents at the active local server without editing their own
2//! configuration files: agents that accept per-launch settings are launched with them,
3//! the rest get exact instructions.
4
5use serde_json::json;
6
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8pub enum Agent {
9    ClaudeCode,
10    Codex,
11    OpenCode,
12    Pi,
13    Hermes,
14    OpenClaw,
15    Cline,
16}
17
18impl Agent {
19    pub const NAMES: [&'static str; 7] = [
20        "claude", "codex", "opencode", "pi", "hermes", "openclaw", "cline",
21    ];
22    pub fn parse(value: &str) -> Option<Self> {
23        Some(match value {
24            "claude" | "claude-code" => Self::ClaudeCode,
25            "codex" => Self::Codex,
26            "opencode" => Self::OpenCode,
27            "pi" => Self::Pi,
28            "hermes" => Self::Hermes,
29            "openclaw" => Self::OpenClaw,
30            "cline" => Self::Cline,
31            _ => return None,
32        })
33    }
34    pub fn label(self) -> &'static str {
35        match self {
36            Self::ClaudeCode => "Claude Code",
37            Self::Codex => "Codex",
38            Self::OpenCode => "OpenCode",
39            Self::Pi => "Pi",
40            Self::Hermes => "Hermes Agent",
41            Self::OpenClaw => "OpenClaw",
42            Self::Cline => "Cline",
43        }
44    }
45}
46
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub enum ConnectPlan {
49    /// Run `binary` (looked up on PATH) with these arguments and extra environment.
50    Launch {
51        binary: &'static str,
52        args: Vec<String>,
53        env: Vec<(String, String)>,
54    },
55    Instructions {
56        text: String,
57    },
58}
59
60#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
61pub enum ConnectError {
62    #[error("{agent} needs the {api} API, which the {backend} backend does not serve")]
63    Unsupported {
64        agent: &'static str,
65        api: &'static str,
66        backend: String,
67    },
68    #[error("only a loopback rigspark endpoint can be connected")]
69    Endpoint,
70    #[error("invalid runtime model id")]
71    Model,
72}
73
74/// Wire APIs each backend serves (verified: llama.cpp b10090, current Ollama, LM Studio).
75fn serves(backend: &str, api: &str) -> bool {
76    match api {
77        "Anthropic Messages" => matches!(backend, "ollama" | "llamacpp"),
78        "OpenAI Responses" => matches!(backend, "ollama" | "llamacpp" | "lmstudio"),
79        _ => true,
80    }
81}
82
83pub fn plan(
84    agent: Agent,
85    endpoint: &str,
86    backend: &str,
87    model: &str,
88) -> Result<ConnectPlan, ConnectError> {
89    let url = crate::state::loopback(endpoint).map_err(|_| ConnectError::Endpoint)?;
90    let host = url.host_str().ok_or(ConnectError::Endpoint)?;
91    let port = url.port_or_known_default().ok_or(ConnectError::Endpoint)?;
92    let base = format!("{}://{host}:{port}", url.scheme());
93    let v1 = format!("{base}/v1");
94    crate::adapters::model_id(model).map_err(|_| ConnectError::Model)?;
95    let require = |api: &'static str| {
96        if serves(backend, api) {
97            Ok(())
98        } else {
99            Err(ConnectError::Unsupported {
100                agent: agent.label(),
101                api,
102                backend: rigspark_core::reports::strip_control(backend),
103            })
104        }
105    };
106    let pair = |key: &str, value: &str| (key.to_owned(), value.to_owned());
107    Ok(match agent {
108        Agent::ClaudeCode => {
109            require("Anthropic Messages")?;
110            ConnectPlan::Launch {
111                binary: "claude",
112                args: vec!["--model".into(), model.into()],
113                env: vec![
114                    pair("ANTHROPIC_BASE_URL", &base),
115                    pair("ANTHROPIC_AUTH_TOKEN", "rigspark-local"),
116                    pair("ANTHROPIC_API_KEY", ""),
117                    pair("ANTHROPIC_SMALL_FAST_MODEL", model),
118                    pair("ANTHROPIC_DEFAULT_HAIKU_MODEL", model),
119                ],
120            }
121        }
122        Agent::Codex => {
123            require("OpenAI Responses")?;
124            ConnectPlan::Launch {
125                binary: "codex",
126                args: vec![
127                    "-c".into(),
128                    "model_provider=\"rigspark\"".into(),
129                    "-c".into(),
130                    format!(
131                        "model_providers.rigspark={{name=\"RigSpark (local)\",base_url=\"{v1}\",wire_api=\"responses\"}}"
132                    ),
133                    "-m".into(),
134                    model.into(),
135                ],
136                env: Vec::new(),
137            }
138        }
139        Agent::OpenCode => {
140            let config = json!({
141                "model": format!("rigspark/{model}"),
142                "provider": {"rigspark": {
143                    "npm": "@ai-sdk/openai-compatible",
144                    "name": "RigSpark (local)",
145                    "options": {"baseURL": v1},
146                    "models": {model: {"name": model}},
147                }},
148            });
149            ConnectPlan::Launch {
150                binary: "opencode",
151                args: Vec::new(),
152                env: vec![pair("OPENCODE_CONFIG_CONTENT", &config.to_string())],
153            }
154        }
155        Agent::Pi => {
156            let snippet = json!({"providers": {"rigspark": {
157                "baseUrl": v1,
158                "api": "openai-completions",
159                "apiKey": "rigspark-local",
160                "models": [{"id": model}],
161            }}});
162            ConnectPlan::Instructions {
163                text: format!(
164                    "Pi reads providers from its models.json (default ~/.pi/agent/models.json).\nMerge this provider, then pick {model} with /model:\n\n{}\n",
165                    serde_json::to_string_pretty(&snippet).unwrap_or_default()
166                ),
167            }
168        }
169        Agent::Hermes => ConnectPlan::Instructions {
170            text: format!(
171                "Run `hermes model`, choose More providers > Custom endpoint, and enter:\n  Base URL: {v1}\n  API key:  (leave blank)\n  Model:    {model}\n"
172            ),
173        },
174        Agent::OpenClaw => ConnectPlan::Instructions {
175            text: format!(
176                "Add an OpenAI-compatible custom provider in OpenClaw:\n  Base URL: {v1}\n  API:      openai-completions\n  API key:  rigspark-local (ignored)\n  Model:    {model}\n"
177            ),
178        },
179        Agent::Cline => ConnectPlan::Instructions {
180            text: format!(
181                "In Cline: Settings > API Configuration > API Provider = OpenAI Compatible.\n  Base URL: {v1}\n  API key:  (leave blank)\n  Model ID: {model}\nSet the context window to at least 32K tokens.\n"
182            ),
183        },
184    })
185}