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 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" => {
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 "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}