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
67pub fn one_shot_specs() -> Vec<OneShotAdapterSpec> {
68    ["claude", "codex", "kimi"]
69        .into_iter()
70        .map(|id| spec_for(id).expect("hardcoded one-shot adapter"))
71        .collect()
72}
73
74pub fn one_shot_spec(adapter_id: &AdapterId) -> Result<OneShotAdapterSpec, OneShotAdapterError> {
75    spec_for(adapter_id.as_str())
76}
77
78pub fn resolve_one_shot_plan(
79    adapter_id: &AdapterId,
80    launch: &LaunchSpec,
81    prompt: &str,
82    selection: Option<&SessionOptionSelection>,
83) -> Result<OneShotPlan, OneShotAdapterError> {
84    resolve_one_shot_plan_with_persistence(
85        adapter_id,
86        launch,
87        prompt,
88        selection,
89        OneShotSessionPersistence::Ephemeral,
90    )
91}
92
93pub fn resolve_one_shot_plan_with_persistence(
94    adapter_id: &AdapterId,
95    launch: &LaunchSpec,
96    prompt: &str,
97    selection: Option<&SessionOptionSelection>,
98    persistence: OneShotSessionPersistence,
99) -> Result<OneShotPlan, OneShotAdapterError> {
100    if prompt.trim().is_empty()
101        || prompt.len() > PROVIDER_EVENT_TEXT_MAX_BYTES
102        || prompt.contains('\0')
103    {
104        return Err(OneShotAdapterError::InvalidPrompt);
105    }
106    if launch.program.trim().is_empty() || launch.program.contains('\0') {
107        return Err(OneShotAdapterError::InvalidLaunch);
108    }
109    if launch.fixed_args.iter().any(|arg| arg.contains('\0')) {
110        return Err(OneShotAdapterError::InvalidLaunch);
111    }
112
113    let spec = one_shot_spec(adapter_id)?;
114    if persistence == OneShotSessionPersistence::Persist && adapter_id.as_str() != "codex" {
115        return Err(OneShotAdapterError::PersistentSessionsUnsupported(
116            adapter_id.as_str().to_owned(),
117        ));
118    }
119    let (model, thinking) = resolve_selection(&spec, selection)?;
120    let mut args = launch.fixed_args.clone();
121    match adapter_id.as_str() {
122        "claude" => {
123            args.extend(strings(&[
124                "-p",
125                "--output-format",
126                "text",
127                "--model",
128                &model,
129                "--permission-mode",
130                "plan",
131            ]));
132            if let Some(thinking) = &thinking {
133                args.extend(["--effort".to_owned(), thinking.clone()]);
134            }
135        }
136        "codex" => {
137            args.push("exec".to_owned());
138            if persistence == OneShotSessionPersistence::Ephemeral {
139                args.push("--ephemeral".to_owned());
140            }
141            args.extend(strings(&[
142                "--skip-git-repo-check", "-s", "read-only", "--model", &model,
143            ]));
144            if let Some(thinking) = &thinking {
145                args.extend([
146                    "-c".to_owned(),
147                    format!("model_reasoning_effort={thinking}"),
148                ]);
149            }
150        }
151        "kimi" => {
152            args.extend(strings(&["-p", prompt, "--output-format", "text"]));
153        }
154        id => return Err(OneShotAdapterError::UnsupportedAdapter(id.to_owned())),
155    }
156
157    let mut applied = SessionOptionSelection::new(model);
158    if let Some(thinking) = thinking {
159        applied
160            .values
161            .insert(ONE_SHOT_THINKING_OPTION_ID.to_owned(), thinking.into());
162    }
163    Ok(OneShotPlan {
164        program: launch.program.clone(),
165        args,
166        stdin_payload: (spec.prompt_delivery == OneShotPromptDelivery::StdinClose)
167            .then(|| prompt.to_owned()),
168        label: spec.label,
169        applied,
170    })
171}
172
173fn resolve_selection(
174    spec: &OneShotAdapterSpec,
175    selection: Option<&SessionOptionSelection>,
176) -> Result<(String, Option<String>), OneShotAdapterError> {
177    if let Some(selection) = selection {
178        selection
179            .validate()
180            .map_err(|_| OneShotAdapterError::InvalidSelection)?;
181        if selection
182            .values
183            .keys()
184            .any(|key| key != ONE_SHOT_THINKING_OPTION_ID)
185        {
186            return Err(OneShotAdapterError::UnknownOption);
187        }
188    }
189    let model_id = selection
190        .map(|selection| selection.model.clone())
191        .unwrap_or_else(|| spec.default_model_id.clone());
192    let known = spec.models.iter().find(|model| model.id == model_id);
193    if known.is_none() && spec.model_source == OneShotModelSource::Static {
194        return Err(OneShotAdapterError::UnknownModel(model_id));
195    }
196    let requested_thinking = selection
197        .and_then(|selection| selection.values.get(ONE_SHOT_THINKING_OPTION_ID))
198        .map(|value| match value {
199            SessionOptionValue::String(value) => Ok(value.clone()),
200            SessionOptionValue::Boolean(_) => Err(OneShotAdapterError::InvalidSelection),
201        })
202        .transpose()?;
203    let default_thinking = known
204        .and_then(|model| model.default_thinking_level.clone())
205        .or_else(|| {
206            (spec.model_source == OneShotModelSource::Dynamic
207                && supports_openai_thinking(&model_id))
208            .then(|| "low".to_owned())
209        });
210    let thinking = requested_thinking.or(default_thinking);
211    if let (Some(model), Some(thinking)) = (known, &thinking) {
212        if !model.thinking_levels.is_empty()
213            && !model
214                .thinking_levels
215                .iter()
216                .any(|level| &level.id == thinking)
217        {
218            return Err(OneShotAdapterError::UnknownThinkingLevel(thinking.clone()));
219        }
220        if model.thinking_levels.is_empty() && spec.model_source == OneShotModelSource::Static {
221            return Err(OneShotAdapterError::ThinkingUnsupported(model.id.clone()));
222        }
223    }
224    Ok((model_id, thinking))
225}
226
227fn spec_for(id: &str) -> Result<OneShotAdapterSpec, OneShotAdapterError> {
228    let (label, delivery, source, models, default_model_id) = match id {
229        "claude" => (
230            "Claude",
231            OneShotPromptDelivery::StdinClose,
232            OneShotModelSource::Static,
233            vec![
234                model("haiku", "Haiku", &[], None),
235                model("sonnet", "Sonnet", &claude_thinking(), Some("low")),
236                model("opus", "Opus", &claude_thinking(), Some("low")),
237            ],
238            "sonnet",
239        ),
240        "codex" => (
241            "Codex",
242            OneShotPromptDelivery::StdinClose,
243            OneShotModelSource::Dynamic,
244            [
245                "gpt-5.5",
246                "gpt-5.4",
247                "gpt-5.4-mini",
248                "gpt-5.3-codex",
249                "gpt-5.3-codex-spark",
250                "gpt-5.2",
251            ]
252            .into_iter()
253            .map(|id| model(id, id, &openai_thinking(), Some("low")))
254            .collect(),
255            "gpt-5.5",
256        ),
257        "kimi" => (
258            "Kimi Code",
259            OneShotPromptDelivery::Positional,
260            OneShotModelSource::Static,
261            vec![model("default", "Provider default", &[], None)],
262            "default",
263        ),
264        id => return Err(OneShotAdapterError::UnsupportedAdapter(id.to_owned())),
265    };
266    Ok(OneShotAdapterSpec {
267        adapter_id: AdapterId::new(id).expect("hardcoded adapter ID"),
268        label: label.to_owned(),
269        prompt_delivery: delivery,
270        model_source: source,
271        models,
272        default_model_id: default_model_id.to_owned(),
273    })
274}
275
276fn model(
277    id: &str,
278    label: &str,
279    thinking: &[(&str, &str)],
280    default_thinking: Option<&str>,
281) -> OneShotModelSpec {
282    OneShotModelSpec {
283        id: id.to_owned(),
284        label: label.to_owned(),
285        thinking_levels: thinking
286            .iter()
287            .map(|(id, label)| OneShotThinkingLevel {
288                id: (*id).to_owned(),
289                label: (*label).to_owned(),
290            })
291            .collect(),
292        default_thinking_level: default_thinking.map(str::to_owned),
293    }
294}
295
296fn openai_thinking() -> [(&'static str, &'static str); 4] {
297    [
298        ("low", "Low"),
299        ("medium", "Medium"),
300        ("high", "High"),
301        ("xhigh", "Extra High"),
302    ]
303}
304
305fn claude_thinking() -> [(&'static str, &'static str); 5] {
306    [
307        ("low", "Low"),
308        ("medium", "Medium"),
309        ("high", "High"),
310        ("xhigh", "Extra High"),
311        ("max", "Max"),
312    ]
313}
314
315fn supports_openai_thinking(id: &str) -> bool {
316    let id = id.to_ascii_lowercase();
317    id.contains("gpt-5") || id.contains("codex")
318}
319
320fn strings(values: &[&str]) -> Vec<String> {
321    values.iter().map(|value| (*value).to_owned()).collect()
322}
323
324#[derive(Clone, Debug, Error, Eq, PartialEq)]
325pub enum OneShotAdapterError {
326    #[error("unsupported one-shot adapter '{0}'")]
327    UnsupportedAdapter(String),
328    #[error("one-shot prompt is empty, contains NUL, or exceeds its bound")]
329    InvalidPrompt,
330    #[error("one-shot launch contract is invalid")]
331    InvalidLaunch,
332    #[error("one-shot session-option selection is invalid")]
333    InvalidSelection,
334    #[error("one-shot selection contains an unknown option")]
335    UnknownOption,
336    #[error("one-shot model '{0}' is not declared by the provider adapter")]
337    UnknownModel(String),
338    #[error("one-shot model '{0}' does not support thinking effort")]
339    ThinkingUnsupported(String),
340    #[error("one-shot thinking level '{0}' is not declared by the model")]
341    UnknownThinkingLevel(String),
342    #[error("one-shot adapter '{0}' does not support persistent sessions")]
343    PersistentSessionsUnsupported(String),
344}
345
346#[cfg(test)]
347mod tests {
348    use super::*;
349    use std::collections::BTreeSet;
350
351    fn launch(program: &str) -> LaunchSpec {
352        LaunchSpec {
353            by_platform: Vec::new(),
354            program: program.to_owned(),
355            fixed_args: vec!["fixed".to_owned()],
356        }
357    }
358
359    #[test]
360    fn one_shot_inventory_includes_current_target_contracts() {
361        let specs = one_shot_specs();
362        let actual = specs
363            .iter()
364            .map(|spec| spec.adapter_id.as_str())
365            .collect::<BTreeSet<_>>();
366        assert_eq!(actual, ["claude", "codex", "kimi"].into_iter().collect());
367        assert_eq!(
368            specs
369                .iter()
370                .find(|spec| spec.adapter_id.as_str() == "codex")
371                .unwrap()
372                .default_model_id,
373            "gpt-5.5"
374        );
375    }
376
377    #[test]
378    fn exact_provider_plans_preserve_prompt_delivery_and_safety_flags() {
379        let claude = resolve_one_shot_plan(
380            &AdapterId::new("claude").unwrap(),
381            &launch("claude-custom"),
382            "large prompt",
383            None,
384        )
385        .unwrap();
386        assert_eq!(claude.program, "claude-custom");
387        assert_eq!(claude.stdin_payload.as_deref(), Some("large prompt"));
388        assert!(claude
389            .args
390            .windows(2)
391            .any(|pair| pair == ["--permission-mode", "plan"]));
392        assert!(claude
393            .args
394            .windows(2)
395            .any(|pair| pair == ["--effort", "low"]));
396
397        let codex = resolve_one_shot_plan(
398            &AdapterId::new("codex").unwrap(),
399            &launch("codex"),
400            "prompt",
401            Some(
402                &SessionOptionSelection::new("gpt-5.4")
403                    .with_value(ONE_SHOT_THINKING_OPTION_ID, "xhigh"),
404            ),
405        )
406        .unwrap();
407        assert!(codex.args.contains(&"--ephemeral".to_owned()));
408        assert!(codex.args.contains(&"read-only".to_owned()));
409        assert!(codex
410            .args
411            .contains(&"model_reasoning_effort=xhigh".to_owned()));
412
413        let kimi = resolve_one_shot_plan(
414            &AdapterId::new("kimi").unwrap(),
415            &launch("kimi"),
416            "prompt in argv",
417            None,
418        )
419        .unwrap();
420        assert_eq!(kimi.stdin_payload, None);
421        assert_eq!(
422            kimi.args,
423            ["fixed", "-p", "prompt in argv", "--output-format", "text"]
424        );
425    }
426
427    #[test]
428    fn codex_persistence_is_explicit_and_preserves_the_exact_safe_plan() {
429        assert_eq!(
430            OneShotSessionPersistence::default(),
431            OneShotSessionPersistence::Ephemeral
432        );
433        let adapter_id = AdapterId::new("codex").unwrap();
434        let selection = SessionOptionSelection::new("gpt-5.4")
435            .with_value(ONE_SHOT_THINKING_OPTION_ID, "xhigh");
436        let legacy = resolve_one_shot_plan(
437            &adapter_id,
438            &launch("codex"),
439            "prompt",
440            Some(&selection),
441        )
442        .unwrap();
443        let ephemeral = resolve_one_shot_plan_with_persistence(
444            &adapter_id,
445            &launch("codex"),
446            "prompt",
447            Some(&selection),
448            OneShotSessionPersistence::Ephemeral,
449        )
450        .unwrap();
451        assert_eq!(legacy, ephemeral);
452
453        let persistent = resolve_one_shot_plan_with_persistence(
454            &adapter_id,
455            &launch("codex"),
456            "prompt",
457            Some(&selection),
458            OneShotSessionPersistence::Persist,
459        )
460        .unwrap();
461        assert_eq!(
462            persistent.args,
463            [
464                "fixed",
465                "exec",
466                "--skip-git-repo-check",
467                "-s",
468                "read-only",
469                "--model",
470                "gpt-5.4",
471                "-c",
472                "model_reasoning_effort=xhigh",
473            ]
474        );
475        assert_eq!(persistent.stdin_payload.as_deref(), Some("prompt"));
476    }
477
478    #[test]
479    fn persistent_sessions_fail_closed_for_non_codex_adapters() {
480        assert!(matches!(
481            resolve_one_shot_plan_with_persistence(
482                &AdapterId::new("claude").unwrap(),
483                &launch("claude"),
484                "prompt",
485                None,
486                OneShotSessionPersistence::Persist,
487            ),
488            Err(OneShotAdapterError::PersistentSessionsUnsupported(id)) if id == "claude"
489        ));
490    }
491
492    #[test]
493    fn every_registered_provider_builds_its_default_execution_path() {
494        let expected_flag = [
495            ("claude", "--permission-mode"),
496            ("codex", "--ephemeral"),
497            ("kimi", "-p"),
498        ];
499        for (id, flag) in expected_flag {
500            let plan = resolve_one_shot_plan(
501                &AdapterId::new(id).unwrap(),
502                &launch(&format!("{id}-binary")),
503                "provider prompt",
504                None,
505            )
506            .unwrap();
507            assert_eq!(plan.program, format!("{id}-binary"));
508            assert_eq!(plan.args.first().map(String::as_str), Some("fixed"));
509            assert!(plan.args.iter().any(|arg| arg == flag), "{id}: {flag}");
510            let delivery = one_shot_spec(&AdapterId::new(id).unwrap())
511                .unwrap()
512                .prompt_delivery;
513            assert_eq!(
514                plan.stdin_payload.is_some(),
515                delivery == OneShotPromptDelivery::StdinClose,
516                "{id}"
517            );
518        }
519    }
520
521    #[test]
522    fn static_models_fail_closed_while_dynamic_models_remain_discovery_compatible() {
523        assert!(matches!(
524            resolve_one_shot_plan(
525                &AdapterId::new("claude").unwrap(),
526                &launch("claude"),
527                "prompt",
528                Some(&SessionOptionSelection::new("unknown")),
529            ),
530            Err(OneShotAdapterError::UnknownModel(_))
531        ));
532        let dynamic = resolve_one_shot_plan(
533            &AdapterId::new("codex").unwrap(),
534            &launch("codex"),
535            "prompt",
536            Some(&SessionOptionSelection::new("vendor/new-model")),
537        )
538        .unwrap();
539        assert!(dynamic.args.contains(&"vendor/new-model".to_owned()));
540    }
541}