Skip to main content

gate4agent_adapters/
one_shot.rs

1use gate4agent_types::{
2    AdapterId, LaunchSpec, SessionOptionSelection, SessionOptionValue,
3    PROVIDER_EVENT_TEXT_MAX_BYTES,
4};
5use thiserror::Error;
6
7pub const ONE_SHOT_REVISION: &str = "gate4agent-one-shot/orca-d8629c4/v2";
8pub const CLAUDE_CODE_INLINE_REVISION: &str = "gate4agent-inline/claude-code-2.1/v1";
9pub const CODEX_CLI_INLINE_REVISION: &str = "gate4agent-inline/codex-cli-0.144/v1";
10pub const KIMI_CODE_INLINE_REVISION: &str = "gate4agent-inline/kimi-code-0.31/v1";
11pub const ONE_SHOT_OUTPUT_MAX_BYTES: usize = 4 * 1024 * 1024;
12pub const ONE_SHOT_TIMEOUT_SECONDS: u64 = 60;
13pub const ONE_SHOT_THINKING_OPTION_ID: &str = "thinking-level";
14
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub enum OneShotPromptDelivery {
17    StdinClose,
18    Positional,
19}
20
21#[derive(Clone, Copy, Debug, Eq, PartialEq)]
22pub enum OneShotModelSource {
23    Static,
24    Dynamic,
25}
26
27#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
28pub enum OneShotSessionPersistence {
29    #[default]
30    Ephemeral,
31    Persist,
32}
33
34#[derive(Clone, Debug, Eq, PartialEq)]
35pub struct OneShotThinkingLevel {
36    pub id: String,
37    pub label: String,
38}
39
40#[derive(Clone, Debug, Eq, PartialEq)]
41pub struct OneShotModelSpec {
42    pub id: String,
43    pub label: String,
44    pub thinking_levels: Vec<OneShotThinkingLevel>,
45    pub default_thinking_level: Option<String>,
46}
47
48#[derive(Clone, Debug, Eq, PartialEq)]
49pub struct OneShotAdapterSpec {
50    pub adapter_id: AdapterId,
51    pub label: String,
52    pub prompt_delivery: OneShotPromptDelivery,
53    pub model_source: OneShotModelSource,
54    pub models: Vec<OneShotModelSpec>,
55    pub default_model_id: String,
56}
57
58#[derive(Clone, Debug, Eq, PartialEq)]
59pub struct OneShotPlan {
60    pub program: String,
61    pub args: Vec<String>,
62    pub stdin_payload: Option<String>,
63    pub label: String,
64    pub applied: SessionOptionSelection,
65}
66
67/// Model id meaning "no model flag": the CLI's own configured default.
68pub const ONE_SHOT_PROVIDER_DEFAULT_MODEL: &str = "default";
69
70pub fn one_shot_specs() -> Vec<OneShotAdapterSpec> {
71    ["claude", "codex", "kimi", "opencode", "mcode"]
72        .into_iter()
73        .map(|id| spec_for(id).expect("hardcoded one-shot adapter"))
74        .collect()
75}
76
77pub fn one_shot_spec(adapter_id: &AdapterId) -> Result<OneShotAdapterSpec, OneShotAdapterError> {
78    spec_for(adapter_id.as_str())
79}
80
81pub fn resolve_one_shot_plan(
82    adapter_id: &AdapterId,
83    launch: &LaunchSpec,
84    prompt: &str,
85    selection: Option<&SessionOptionSelection>,
86) -> Result<OneShotPlan, OneShotAdapterError> {
87    resolve_one_shot_plan_with_persistence(
88        adapter_id,
89        launch,
90        prompt,
91        selection,
92        OneShotSessionPersistence::Ephemeral,
93    )
94}
95
96pub fn resolve_one_shot_plan_with_persistence(
97    adapter_id: &AdapterId,
98    launch: &LaunchSpec,
99    prompt: &str,
100    selection: Option<&SessionOptionSelection>,
101    persistence: OneShotSessionPersistence,
102) -> Result<OneShotPlan, OneShotAdapterError> {
103    if prompt.trim().is_empty()
104        || prompt.len() > PROVIDER_EVENT_TEXT_MAX_BYTES
105        || prompt.contains('\0')
106    {
107        return Err(OneShotAdapterError::InvalidPrompt);
108    }
109    if launch.program.trim().is_empty() || launch.program.contains('\0') {
110        return Err(OneShotAdapterError::InvalidLaunch);
111    }
112    if launch.fixed_args.iter().any(|arg| arg.contains('\0')) {
113        return Err(OneShotAdapterError::InvalidLaunch);
114    }
115
116    let spec = one_shot_spec(adapter_id)?;
117    if persistence == OneShotSessionPersistence::Persist && adapter_id.as_str() != "codex" {
118        return Err(OneShotAdapterError::PersistentSessionsUnsupported(
119            adapter_id.as_str().to_owned(),
120        ));
121    }
122    let (model, thinking) = resolve_selection(&spec, selection)?;
123    let mut args = launch.fixed_args.clone();
124    match adapter_id.as_str() {
125        "claude" => {
126            args.extend(strings(&[
127                "-p",
128                "--output-format",
129                "text",
130                "--model",
131                &model,
132                "--permission-mode",
133                "plan",
134            ]));
135            if let Some(thinking) = &thinking {
136                args.extend(["--effort".to_owned(), thinking.clone()]);
137            }
138        }
139        "codex" => {
140            args.push("exec".to_owned());
141            if persistence == OneShotSessionPersistence::Ephemeral {
142                args.push("--ephemeral".to_owned());
143            }
144            args.extend(strings(&[
145                "--skip-git-repo-check", "-s", "read-only", "--model", &model,
146            ]));
147            if let Some(thinking) = &thinking {
148                args.extend([
149                    "-c".to_owned(),
150                    format!("model_reasoning_effort={thinking}"),
151                ]);
152            }
153        }
154        "kimi" => {
155            args.extend(strings(&["-p", prompt, "--output-format", "text"]));
156        }
157        // opencode 1.19.4 `run --help`: `-m provider/model`, `--variant`
158        // (provider-specific reasoning effort). "default" keeps the
159        // account's own default model.
160        "opencode" => {
161            args.push("run".to_owned());
162            if model != ONE_SHOT_PROVIDER_DEFAULT_MODEL {
163                args.extend(["-m".to_owned(), model.clone()]);
164            }
165            if let Some(thinking) = &thinking {
166                args.extend(["--variant".to_owned(), thinking.clone()]);
167            }
168            args.extend(["--".to_owned(), prompt.to_owned()]);
169        }
170        // MiniMax Code 0.6.13 `exec --help`: `--model provider/model`,
171        // `--effort LEVEL`, `--output-format text`.
172        "mcode" => {
173            args.extend(strings(&["exec", "--output-format", "text"]));
174            if model != ONE_SHOT_PROVIDER_DEFAULT_MODEL {
175                args.extend(["--model".to_owned(), model.clone()]);
176            }
177            if let Some(thinking) = &thinking {
178                args.extend(["--effort".to_owned(), thinking.clone()]);
179            }
180            args.extend(["--".to_owned(), prompt.to_owned()]);
181        }
182        id => return Err(OneShotAdapterError::UnsupportedAdapter(id.to_owned())),
183    }
184
185    let mut applied = SessionOptionSelection::new(model);
186    if let Some(thinking) = thinking {
187        applied
188            .values
189            .insert(ONE_SHOT_THINKING_OPTION_ID.to_owned(), thinking.into());
190    }
191    Ok(OneShotPlan {
192        program: launch.program.clone(),
193        args,
194        stdin_payload: (spec.prompt_delivery == OneShotPromptDelivery::StdinClose)
195            .then(|| prompt.to_owned()),
196        label: spec.label,
197        applied,
198    })
199}
200
201fn resolve_selection(
202    spec: &OneShotAdapterSpec,
203    selection: Option<&SessionOptionSelection>,
204) -> Result<(String, Option<String>), OneShotAdapterError> {
205    if let Some(selection) = selection {
206        selection
207            .validate()
208            .map_err(|_| OneShotAdapterError::InvalidSelection)?;
209        if selection
210            .values
211            .keys()
212            .any(|key| key != ONE_SHOT_THINKING_OPTION_ID)
213        {
214            return Err(OneShotAdapterError::UnknownOption);
215        }
216    }
217    let model_id = selection
218        .map(|selection| selection.model.clone())
219        .unwrap_or_else(|| spec.default_model_id.clone());
220    let known = spec.models.iter().find(|model| model.id == model_id);
221    if known.is_none() && spec.model_source == OneShotModelSource::Static {
222        return Err(OneShotAdapterError::UnknownModel(model_id));
223    }
224    let requested_thinking = selection
225        .and_then(|selection| selection.values.get(ONE_SHOT_THINKING_OPTION_ID))
226        .map(|value| match value {
227            SessionOptionValue::String(value) => Ok(value.clone()),
228            SessionOptionValue::Boolean(_) => Err(OneShotAdapterError::InvalidSelection),
229        })
230        .transpose()?;
231    let default_thinking = known
232        .and_then(|model| model.default_thinking_level.clone())
233        .or_else(|| {
234            (spec.model_source == OneShotModelSource::Dynamic
235                && supports_openai_thinking(&model_id))
236            .then(|| "low".to_owned())
237        });
238    let thinking = requested_thinking.or(default_thinking);
239    if let (Some(model), Some(thinking)) = (known, &thinking) {
240        if !model.thinking_levels.is_empty()
241            && !model
242                .thinking_levels
243                .iter()
244                .any(|level| &level.id == thinking)
245        {
246            return Err(OneShotAdapterError::UnknownThinkingLevel(thinking.clone()));
247        }
248        if model.thinking_levels.is_empty() && spec.model_source == OneShotModelSource::Static {
249            return Err(OneShotAdapterError::ThinkingUnsupported(model.id.clone()));
250        }
251    }
252    Ok((model_id, thinking))
253}
254
255fn spec_for(id: &str) -> Result<OneShotAdapterSpec, OneShotAdapterError> {
256    let (label, delivery, source, models, default_model_id) = match id {
257        "claude" => (
258            "Claude",
259            OneShotPromptDelivery::StdinClose,
260            OneShotModelSource::Static,
261            vec![
262                model("haiku", "Haiku", &[], None),
263                model("sonnet", "Sonnet", &claude_thinking(), Some("low")),
264                model("opus", "Opus", &claude_thinking(), Some("low")),
265            ],
266            "sonnet",
267        ),
268        "codex" => (
269            "Codex",
270            OneShotPromptDelivery::StdinClose,
271            OneShotModelSource::Dynamic,
272            [
273                "gpt-5.5",
274                "gpt-5.4",
275                "gpt-5.4-mini",
276                "gpt-5.3-codex",
277                "gpt-5.3-codex-spark",
278                "gpt-5.2",
279            ]
280            .into_iter()
281            .map(|id| model(id, id, &openai_thinking(), Some("low")))
282            .collect(),
283            "gpt-5.5",
284        ),
285        "kimi" => (
286            "Kimi Code",
287            OneShotPromptDelivery::Positional,
288            OneShotModelSource::Static,
289            vec![model("default", "Provider default", &[], None)],
290            "default",
291        ),
292        "opencode" => (
293            "opencode",
294            OneShotPromptDelivery::Positional,
295            OneShotModelSource::Dynamic,
296            vec![model(
297                ONE_SHOT_PROVIDER_DEFAULT_MODEL,
298                "Provider default",
299                &[],
300                None,
301            )],
302            ONE_SHOT_PROVIDER_DEFAULT_MODEL,
303        ),
304        "mcode" => (
305            "MiniMax Code",
306            OneShotPromptDelivery::Positional,
307            OneShotModelSource::Dynamic,
308            vec![model(
309                ONE_SHOT_PROVIDER_DEFAULT_MODEL,
310                "Provider default",
311                &[],
312                None,
313            )],
314            ONE_SHOT_PROVIDER_DEFAULT_MODEL,
315        ),
316        id => return Err(OneShotAdapterError::UnsupportedAdapter(id.to_owned())),
317    };
318    Ok(OneShotAdapterSpec {
319        adapter_id: AdapterId::new(id).expect("hardcoded adapter ID"),
320        label: label.to_owned(),
321        prompt_delivery: delivery,
322        model_source: source,
323        models,
324        default_model_id: default_model_id.to_owned(),
325    })
326}
327
328fn model(
329    id: &str,
330    label: &str,
331    thinking: &[(&str, &str)],
332    default_thinking: Option<&str>,
333) -> OneShotModelSpec {
334    OneShotModelSpec {
335        id: id.to_owned(),
336        label: label.to_owned(),
337        thinking_levels: thinking
338            .iter()
339            .map(|(id, label)| OneShotThinkingLevel {
340                id: (*id).to_owned(),
341                label: (*label).to_owned(),
342            })
343            .collect(),
344        default_thinking_level: default_thinking.map(str::to_owned),
345    }
346}
347
348fn openai_thinking() -> [(&'static str, &'static str); 4] {
349    [
350        ("low", "Low"),
351        ("medium", "Medium"),
352        ("high", "High"),
353        ("xhigh", "Extra High"),
354    ]
355}
356
357fn claude_thinking() -> [(&'static str, &'static str); 5] {
358    [
359        ("low", "Low"),
360        ("medium", "Medium"),
361        ("high", "High"),
362        ("xhigh", "Extra High"),
363        ("max", "Max"),
364    ]
365}
366
367fn supports_openai_thinking(id: &str) -> bool {
368    let id = id.to_ascii_lowercase();
369    id.contains("gpt-5") || id.contains("codex")
370}
371
372fn strings(values: &[&str]) -> Vec<String> {
373    values.iter().map(|value| (*value).to_owned()).collect()
374}
375
376#[derive(Clone, Debug, Error, Eq, PartialEq)]
377pub enum OneShotAdapterError {
378    #[error("unsupported one-shot adapter '{0}'")]
379    UnsupportedAdapter(String),
380    #[error("one-shot prompt is empty, contains NUL, or exceeds its bound")]
381    InvalidPrompt,
382    #[error("one-shot launch contract is invalid")]
383    InvalidLaunch,
384    #[error("one-shot session-option selection is invalid")]
385    InvalidSelection,
386    #[error("one-shot selection contains an unknown option")]
387    UnknownOption,
388    #[error("one-shot model '{0}' is not declared by the provider adapter")]
389    UnknownModel(String),
390    #[error("one-shot model '{0}' does not support thinking effort")]
391    ThinkingUnsupported(String),
392    #[error("one-shot thinking level '{0}' is not declared by the model")]
393    UnknownThinkingLevel(String),
394    #[error("one-shot adapter '{0}' does not support persistent sessions")]
395    PersistentSessionsUnsupported(String),
396}
397
398#[cfg(test)]
399mod tests {
400    use super::*;
401    use std::collections::BTreeSet;
402
403    fn launch(program: &str) -> LaunchSpec {
404        LaunchSpec {
405            program: program.to_owned(),
406            fixed_args: vec!["fixed".to_owned()],
407        }
408    }
409
410    #[test]
411    fn one_shot_inventory_includes_current_target_contracts() {
412        let specs = one_shot_specs();
413        let actual = specs
414            .iter()
415            .map(|spec| spec.adapter_id.as_str())
416            .collect::<BTreeSet<_>>();
417        assert_eq!(
418            actual,
419            ["claude", "codex", "kimi", "mcode", "opencode"]
420                .into_iter()
421                .collect()
422        );
423        assert_eq!(
424            specs
425                .iter()
426                .find(|spec| spec.adapter_id.as_str() == "codex")
427                .unwrap()
428                .default_model_id,
429            "gpt-5.5"
430        );
431    }
432
433    #[test]
434    fn exact_provider_plans_preserve_prompt_delivery_and_safety_flags() {
435        let claude = resolve_one_shot_plan(
436            &AdapterId::new("claude").unwrap(),
437            &launch("claude-custom"),
438            "large prompt",
439            None,
440        )
441        .unwrap();
442        assert_eq!(claude.program, "claude-custom");
443        assert_eq!(claude.stdin_payload.as_deref(), Some("large prompt"));
444        assert!(claude
445            .args
446            .windows(2)
447            .any(|pair| pair == ["--permission-mode", "plan"]));
448        assert!(claude
449            .args
450            .windows(2)
451            .any(|pair| pair == ["--effort", "low"]));
452
453        let codex = resolve_one_shot_plan(
454            &AdapterId::new("codex").unwrap(),
455            &launch("codex"),
456            "prompt",
457            Some(
458                &SessionOptionSelection::new("gpt-5.4")
459                    .with_value(ONE_SHOT_THINKING_OPTION_ID, "xhigh"),
460            ),
461        )
462        .unwrap();
463        assert!(codex.args.contains(&"--ephemeral".to_owned()));
464        assert!(codex.args.contains(&"read-only".to_owned()));
465        assert!(codex
466            .args
467            .contains(&"model_reasoning_effort=xhigh".to_owned()));
468
469        let kimi = resolve_one_shot_plan(
470            &AdapterId::new("kimi").unwrap(),
471            &launch("kimi"),
472            "prompt in argv",
473            None,
474        )
475        .unwrap();
476        assert_eq!(kimi.stdin_payload, None);
477        assert_eq!(
478            kimi.args,
479            ["fixed", "-p", "prompt in argv", "--output-format", "text"]
480        );
481    }
482
483    #[test]
484    fn codex_persistence_is_explicit_and_preserves_the_exact_safe_plan() {
485        assert_eq!(
486            OneShotSessionPersistence::default(),
487            OneShotSessionPersistence::Ephemeral
488        );
489        let adapter_id = AdapterId::new("codex").unwrap();
490        let selection = SessionOptionSelection::new("gpt-5.4")
491            .with_value(ONE_SHOT_THINKING_OPTION_ID, "xhigh");
492        let legacy = resolve_one_shot_plan(
493            &adapter_id,
494            &launch("codex"),
495            "prompt",
496            Some(&selection),
497        )
498        .unwrap();
499        let ephemeral = resolve_one_shot_plan_with_persistence(
500            &adapter_id,
501            &launch("codex"),
502            "prompt",
503            Some(&selection),
504            OneShotSessionPersistence::Ephemeral,
505        )
506        .unwrap();
507        assert_eq!(legacy, ephemeral);
508
509        let persistent = resolve_one_shot_plan_with_persistence(
510            &adapter_id,
511            &launch("codex"),
512            "prompt",
513            Some(&selection),
514            OneShotSessionPersistence::Persist,
515        )
516        .unwrap();
517        assert_eq!(
518            persistent.args,
519            [
520                "fixed",
521                "exec",
522                "--skip-git-repo-check",
523                "-s",
524                "read-only",
525                "--model",
526                "gpt-5.4",
527                "-c",
528                "model_reasoning_effort=xhigh",
529            ]
530        );
531        assert_eq!(persistent.stdin_payload.as_deref(), Some("prompt"));
532    }
533
534    #[test]
535    fn persistent_sessions_fail_closed_for_non_codex_adapters() {
536        assert!(matches!(
537            resolve_one_shot_plan_with_persistence(
538                &AdapterId::new("claude").unwrap(),
539                &launch("claude"),
540                "prompt",
541                None,
542                OneShotSessionPersistence::Persist,
543            ),
544            Err(OneShotAdapterError::PersistentSessionsUnsupported(id)) if id == "claude"
545        ));
546    }
547
548    #[test]
549    fn every_registered_provider_builds_its_default_execution_path() {
550        let expected_flag = [
551            ("claude", "--permission-mode"),
552            ("codex", "--ephemeral"),
553            ("kimi", "-p"),
554            ("opencode", "run"),
555            ("mcode", "exec"),
556        ];
557        for (id, flag) in expected_flag {
558            let plan = resolve_one_shot_plan(
559                &AdapterId::new(id).unwrap(),
560                &launch(&format!("{id}-binary")),
561                "provider prompt",
562                None,
563            )
564            .unwrap();
565            assert_eq!(plan.program, format!("{id}-binary"));
566            assert_eq!(plan.args.first().map(String::as_str), Some("fixed"));
567            assert!(plan.args.iter().any(|arg| arg == flag), "{id}: {flag}");
568            let delivery = one_shot_spec(&AdapterId::new(id).unwrap())
569                .unwrap()
570                .prompt_delivery;
571            assert_eq!(
572                plan.stdin_payload.is_some(),
573                delivery == OneShotPromptDelivery::StdinClose,
574                "{id}"
575            );
576        }
577    }
578
579    #[test]
580    fn static_models_fail_closed_while_dynamic_models_remain_discovery_compatible() {
581        assert!(matches!(
582            resolve_one_shot_plan(
583                &AdapterId::new("claude").unwrap(),
584                &launch("claude"),
585                "prompt",
586                Some(&SessionOptionSelection::new("unknown")),
587            ),
588            Err(OneShotAdapterError::UnknownModel(_))
589        ));
590        let dynamic = resolve_one_shot_plan(
591            &AdapterId::new("codex").unwrap(),
592            &launch("codex"),
593            "prompt",
594            Some(&SessionOptionSelection::new("vendor/new-model")),
595        )
596        .unwrap();
597        assert!(dynamic.args.contains(&"vendor/new-model".to_owned()));
598    }
599
600    #[test]
601    fn opencode_and_mcode_plans_match_live_help_flags() {
602        let opencode = resolve_one_shot_plan(
603            &AdapterId::new("opencode").unwrap(),
604            &launch("opencode"),
605            "-hi",
606            Some(
607                &SessionOptionSelection::new("opencode/big-pickle")
608                    .with_value(ONE_SHOT_THINKING_OPTION_ID, "high"),
609            ),
610        )
611        .unwrap();
612        assert_eq!(
613            opencode.args,
614            [
615                "fixed",
616                "run",
617                "-m",
618                "opencode/big-pickle",
619                "--variant",
620                "high",
621                "--",
622                "-hi"
623            ]
624        );
625        assert_eq!(opencode.stdin_payload, None);
626
627        let mcode = resolve_one_shot_plan(
628            &AdapterId::new("mcode").unwrap(),
629            &launch("mcode"),
630            "prompt",
631            None,
632        )
633        .unwrap();
634        assert_eq!(
635            mcode.args,
636            ["fixed", "exec", "--output-format", "text", "--", "prompt"]
637        );
638        let mcode = resolve_one_shot_plan(
639            &AdapterId::new("mcode").unwrap(),
640            &launch("mcode"),
641            "prompt",
642            Some(
643                &SessionOptionSelection::new("minimax/MiniMax-M3.1-Flash")
644                    .with_value(ONE_SHOT_THINKING_OPTION_ID, "low"),
645            ),
646        )
647        .unwrap();
648        assert!(mcode
649            .args
650            .windows(2)
651            .any(|pair| pair == ["--model", "minimax/MiniMax-M3.1-Flash"]));
652        assert!(mcode.args.windows(2).any(|pair| pair == ["--effort", "low"]));
653    }
654}