1mod efficiency;
4mod provider_supervisor;
5
6pub use efficiency::ShellEfficiencyFacts;
7pub use gate4agent::pty::ForegroundProbeTiming;
12pub use provider_supervisor::{
13 NativeProviderExecutor, NativeProviderExit, NativeProviderOperation,
14 NativeProviderOperationError, NativeProviderResultPoll, PhysicalExitAck,
15 ProviderOperationKey, ProviderOperationSnapshot, ProviderSupervisor,
16 ProviderSupervisorBuildError, ProviderSupervisorFault, ProviderSupervisorFaultKind,
17 ProviderStopCause, ProviderSupervisorSnapshot, ProviderSupervisorState,
18 ProviderSupervisorTick, DEFAULT_PROVIDER_STOP_GRACE,
19 MAX_PROVIDER_FORCE_STOP_ATTEMPTS, MAX_PROVIDER_STOP_SIGNAL_ATTEMPTS,
20 MAX_PROVIDER_SUPERVISOR_EVENTS, MAX_PROVIDER_SUPERVISOR_OPERATIONS,
21 MAX_PROVIDER_SUPERVISOR_OUTCOMES_PER_TICK, MAX_PROVIDER_SUPERVISOR_TOMBSTONES,
22 MAX_PROVIDER_SUPERVISOR_WORK_PER_TICK,
23};
24
25use gate4agent::acp::protocol::{McpServerConfig, SessionMode};
26use gate4agent::agent::{is_agent_foreground_wrapper, is_expected_agent_process, ReadinessStatus};
27use gate4agent::pty::cli::codex::strip_ansi_codes;
28use gate4agent::pty::cli::{create_pipeline, ClassificationPipeline, MessageClass, ParsedMessage};
29use gate4agent::pty::event::PtyMouseProtocolEncoding;
30use gate4agent::pty::{
31 PtyAttachment, PtyEvent, PtyEventEnvelope, PtyEventReceiver, PtyForegroundObservation,
32 PtyReplayCursor, PtySession, PtyTerminalSnapshot, RateLimitDetector, VteParser,
33};
34use gate4agent::{
35 AcpSession, AcpSessionOptions, AgentEvent, CliTool, HostDecisionAuthority, HostPolicy,
36 HostRequestDecision, HostRequestOutcome, LaunchRequest, OperatorPermissionChoice,
37 PipeProcessOptions, PipeSession, PromptFraming,
38 ReadinessIntent, ReadinessPermit, ReadinessTracker, RpcId, RuntimePlatform, SessionConfig,
39 StopReason,
40};
41use gate4agent_adapters::{
42 build_resume_plan_for_identity, builtin_adapter_registry, AdapterRuntimeRegistry,
43 CodexPtySessionIdentityExtractor, KimiPtySessionIdentityExtractor, OneShotSessionPersistence,
44};
45use gate4agent_catalog::{
46 acp_full_auto_is_host_policy, approval_level_resolution, ApprovalLevelResolution,
47 AgentRegistry, AgentSpec, EnvMutation,
48 McpServerSpec, ModeId,
49};
50use gate4agent_shell_one_shot::NativeOneShotSession;
51use gate4agent_types::{
52 AdapterFamily, AgentCommand, AgentId, AgentInstanceId, ApprovalLevel, CapabilityProbeFailure,
53 ContextWindowUsage as ProviderContextWindowUsage, ControlEffect,
54 ControlObservation, EffectEnvelope, ForegroundProcess, ForegroundProcessKind,
55 ForegroundRequirement, HostDecisionAuthority as ProviderHostDecisionAuthority,
56 HostRequestDecision as ProviderHostRequestDecision,
57 HostRequestOutcome as ProviderHostRequestOutcome, InputAction, ObservationEnvelope,
58 OperationId, OperatorGateInput,
59 OperatorGateKind, OperatorGateOption, OperatorGateOptionSemantics, OperatorGateState,
60 OperatorGateSubject, PipeProtocol,
61 PreparedInputKind, PromptPayload, ProviderAvailableCommand, ProviderConfigChoice,
62 ProviderConfigOption, ProviderConfigOptionKind, ProviderEvent, ProviderInteractionKind,
63 ProviderInteractionOption, ProviderInteractionResponse, ProviderInteractionTarget,
64 ProviderModeInfo, ProviderPlanPriority,
65 ProviderPlanStatus, ProviderPlanStep,
66 ProviderRateLimitKind, ProviderRuntimeCapability, ProviderRuntimePolicy,
67 ProviderSessionIdentity, ProviderSessionKey, ProviderStopReason,
68 ProviderSource, PtyScreenState, ResumeLaunchRequest, SessionGeneration, StartRequest,
69 TerminalFrame, TerminalMouseProtocolEncoding, TerminalSize, TokenUsage, TransportKind,
70 OPERATOR_GATE_OPTIONS_MAX, WORKING_DIRECTORY_MAX_BYTES,
71};
72use std::collections::{BTreeMap, VecDeque};
73use std::ffi::{OsStr, OsString};
74use std::path::PathBuf;
75use std::sync::Mutex;
76use std::time::{Duration, Instant};
77use tokio::sync::broadcast;
78use uuid::Uuid;
79
80const INSTANCE_LAUNCH_ARGS_MAX: usize = 128;
81const INSTANCE_LAUNCH_ARG_MAX_BYTES: usize = 65_536;
82const INSTANCE_LAUNCH_ARGS_TOTAL_MAX_BYTES: usize = 262_144;
83const RESERVED_CLAUDE_LAUNCH_FLAGS: &[&str] = &[
84 "--continue",
85 "--print",
86 "--prompt",
87 "--prompt-interactive",
88 "--resume",
89 "--session-id",
90 "-c",
91 "-p",
92 "-r",
93];
94
95fn mcp_server_acp_entry(spec: &McpServerSpec) -> McpServerConfig {
112 McpServerConfig::stdio(
113 spec.name().to_owned(),
114 spec.program().to_string_lossy().into_owned(),
115 spec.args()
116 .iter()
117 .map(|arg| arg.to_string_lossy().into_owned())
118 .collect::<Vec<_>>(),
119 spec.env()
120 .iter()
121 .map(|(key, value)| (key.to_string_lossy().into_owned(), value.to_string_lossy().into_owned()))
122 .collect::<Vec<_>>(),
123 )
124}
125
126#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
127pub struct NativeSessionKey {
128 pub instance_id: AgentInstanceId,
129 pub generation: SessionGeneration,
130}
131
132struct NativeSpawnRequest {
133 agent_id: AgentId,
134 transport: TransportKind,
135 request: StartRequest,
136 runtime_policy: ProviderRuntimePolicy,
137 launch_extra_args: Vec<OsString>,
138 instance_extra_args: Vec<OsString>,
139 resumed_provider_session: Option<gate4agent_types::ProviderSessionIdentity>,
140 one_shot_session_persistence: OneShotSessionPersistence,
141}
142
143struct OwnedPtySession {
144 session: PtySession,
145 spawn_operation_id: OperationId,
146 last_terminal_sequence: u64,
147 terminal_stale_published: bool,
148 runtime_policy: ProviderRuntimePolicy,
149 provider: Option<OwnedPtyProvider>,
150 agent_id: AgentId,
155 last_screen_gate: Option<OperatorGateState>,
156 last_screen_failure: Option<&'static str>,
157 last_foreground_verdict: Option<ForegroundVerdict>,
158 last_screen_state: PtyScreenState,
159 ever_reached_ready: bool,
170 screen_had_content: bool,
175 next_foreground_probe: Option<Instant>,
180}
181
182struct OwnedPtyProvider {
183 source: ProviderSource,
184 receiver: PtyEventReceiver,
185 replay: VecDeque<PtyEventEnvelope>,
186 pending_events: VecDeque<ProviderEvent>,
187 utf8: Utf8ChunkDecoder,
188 pipeline: Mutex<ClassificationPipeline>,
189 rate_limits: RateLimitFeed,
190 kimi_identity: Option<KimiPtySessionIdentityExtractor>,
191 semantic_events: bool,
192 provider_session_started: bool,
193 next_provider_sequence: u64,
194}
195
196struct RateLimitFeed {
223 detector: RateLimitDetector,
224 vte: VteParser,
225 buffer: String,
226}
227
228impl RateLimitFeed {
229 fn new_for_tool(tool: CliTool) -> Self {
230 Self {
231 detector: RateLimitDetector::new_for_tool(tool),
232 vte: VteParser::new(),
233 buffer: String::new(),
234 }
235 }
236
237 fn detect(&mut self, raw: &str) -> Option<gate4agent::core::types::RateLimitInfo> {
247 let cleaned = self.vte.parse(raw);
248 self.buffer.push_str(&cleaned);
249 let info = self.detector.detect(&self.buffer);
250 if let Some(last_newline) = self.buffer.rfind('\n') {
251 self.buffer.drain(..=last_newline);
252 } else if self.buffer.len() > RATE_LIMIT_FEED_BUFFER_MAX_BYTES {
253 let mut cut = self.buffer.len() - RATE_LIMIT_FEED_BUFFER_MAX_BYTES;
261 while !self.buffer.is_char_boundary(cut) {
262 cut += 1;
263 }
264 self.buffer.drain(..cut);
265 }
266 info
267 }
268}
269
270const RATE_LIMIT_FEED_BUFFER_MAX_BYTES: usize = 8192;
273
274#[derive(Default)]
275struct Utf8ChunkDecoder {
276 pending: Vec<u8>,
277}
278
279impl Utf8ChunkDecoder {
280 fn push(&mut self, bytes: &[u8]) -> String {
281 self.pending.extend_from_slice(bytes);
282 let mut decoded = String::new();
283 loop {
284 match std::str::from_utf8(&self.pending) {
285 Ok(text) => {
286 decoded.push_str(text);
287 self.pending.clear();
288 break;
289 }
290 Err(error) => {
291 let valid = error.valid_up_to();
292 if valid > 0 {
293 let text = std::str::from_utf8(&self.pending[..valid])
294 .expect("validated UTF-8 prefix");
295 decoded.push_str(text);
296 self.pending.drain(..valid);
297 continue;
298 }
299 let Some(invalid) = error.error_len() else {
300 break;
301 };
302 decoded.push('\u{fffd}');
303 self.pending.drain(..invalid.min(self.pending.len()));
304 }
305 }
306 }
307 decoded
308 }
309
310 fn clear(&mut self) {
311 self.pending.clear();
312 }
313}
314
315struct OwnedProviderSession<S> {
316 source: ProviderSource,
317 session: S,
318 events: broadcast::Receiver<AgentEvent>,
319 pending_events: VecDeque<AgentEvent>,
320 pending_provider_events: VecDeque<ProviderEvent>,
329 next_provider_sequence: u64,
330 observed_exit_code: Option<i32>,
331 runtime_policy: ProviderRuntimePolicy,
332}
333
334pub struct NativeEffectShell {
337 catalog: AgentRegistry,
338 legacy_adapters: AdapterRuntimeRegistry<CliTool>,
339 pty_sessions: BTreeMap<NativeSessionKey, OwnedPtySession>,
340 pipe_sessions: BTreeMap<NativeSessionKey, OwnedProviderSession<PipeSession>>,
341 one_shot_sessions: BTreeMap<NativeSessionKey, OwnedProviderSession<NativeOneShotSession>>,
342 acp_sessions: BTreeMap<NativeSessionKey, OwnedProviderSession<AcpSession>>,
343 pending_observations: VecDeque<ObservationEnvelope>,
344 efficiency_facts: ShellEfficiencyFacts,
349}
350
351impl NativeEffectShell {
352 pub fn new(catalog: AgentRegistry) -> Self {
353 Self::new_with_runtime_adapters(catalog, builtin_legacy_adapter_runtimes())
354 }
355
356 pub fn new_with_runtime_adapters(
362 catalog: AgentRegistry,
363 legacy_adapters: AdapterRuntimeRegistry<CliTool>,
364 ) -> Self {
365 Self {
366 catalog,
367 legacy_adapters,
368 pty_sessions: BTreeMap::new(),
369 pipe_sessions: BTreeMap::new(),
370 one_shot_sessions: BTreeMap::new(),
371 acp_sessions: BTreeMap::new(),
372 pending_observations: VecDeque::new(),
373 efficiency_facts: ShellEfficiencyFacts::default(),
374 }
375 }
376
377 pub fn take_efficiency_facts(&mut self) -> ShellEfficiencyFacts {
383 self.efficiency_facts.take()
384 }
385
386 pub fn active_session_count(&self) -> usize {
387 self.pty_sessions.len()
388 + self.pipe_sessions.len()
389 + self.one_shot_sessions.len()
390 + self.acp_sessions.len()
391 }
392
393 pub fn spawn_operation_id(&self, key: NativeSessionKey) -> Option<OperationId> {
394 self.pty_sessions
395 .get(&key)
396 .map(|owned| owned.spawn_operation_id)
397 }
398
399 pub fn terminal_snapshot(&self, key: NativeSessionKey) -> Result<PtyTerminalSnapshot, String> {
400 self.pty_sessions
401 .get(&key)
402 .ok_or_else(|| missing_session_message(key))?
403 .session
404 .terminal_snapshot()
405 .map_err(|error| error.to_string())
406 }
407
408 pub async fn execute(&mut self, envelope: EffectEnvelope) -> ObservationEnvelope {
409 self.execute_with_environment(envelope, Vec::new()).await
410 }
411
412 pub async fn execute_with_pty_env(
415 &mut self,
416 envelope: EffectEnvelope,
417 pty_env: Vec<EnvMutation>,
418 ) -> ObservationEnvelope {
419 self.execute_with_environment(envelope, pty_env).await
420 }
421
422 pub async fn execute_with_environment(
426 &mut self,
427 envelope: EffectEnvelope,
428 environment: Vec<EnvMutation>,
429 ) -> ObservationEnvelope {
430 self.execute_with_launch_overlay(envelope, environment, Vec::new())
431 .await
432 }
433
434 pub async fn execute_with_launch_overlay(
437 &mut self,
438 envelope: EffectEnvelope,
439 environment: Vec<EnvMutation>,
440 extra_args: Vec<OsString>,
441 ) -> ObservationEnvelope {
442 self.execute_with_launch_overlay_and_persistence(
443 envelope,
444 environment,
445 extra_args,
446 OneShotSessionPersistence::Ephemeral,
447 )
448 .await
449 }
450
451 pub async fn execute_with_launch_overlay_and_persistence(
454 &mut self,
455 envelope: EffectEnvelope,
456 environment: Vec<EnvMutation>,
457 extra_args: Vec<OsString>,
458 one_shot_session_persistence: OneShotSessionPersistence,
459 ) -> ObservationEnvelope {
460 self.execute_with_launch_context(
461 envelope,
462 environment,
463 extra_args,
464 one_shot_session_persistence,
465 None,
466 )
467 .await
468 }
469
470 pub async fn execute_with_launch_context(
471 &mut self,
472 envelope: EffectEnvelope,
473 environment: Vec<EnvMutation>,
474 extra_args: Vec<OsString>,
475 one_shot_session_persistence: OneShotSessionPersistence,
476 mcp_server: Option<McpServerSpec>,
477 ) -> ObservationEnvelope {
478 let EffectEnvelope {
479 operation_id,
480 instance_id,
481 generation,
482 effect,
483 } = envelope;
484 let key = NativeSessionKey {
485 instance_id,
486 generation,
487 };
488
489 let observation = {
490 match effect {
491 ControlEffect::Spawn {
492 agent_id,
493 transport,
494 runtime_policy,
495 request,
496 } => {
497 self.spawn_native(
498 key,
499 operation_id,
500 NativeSpawnRequest {
501 agent_id,
502 transport,
503 request,
504 runtime_policy,
505 launch_extra_args: Vec::new(),
506 instance_extra_args: extra_args,
507 resumed_provider_session: None,
508 one_shot_session_persistence,
509 },
510 environment,
511 mcp_server,
512 )
513 .await
514 }
515 ControlEffect::SpawnResume {
516 agent_id,
517 transport,
518 provider_session,
519 runtime_policy,
520 request,
521 } => {
522 self.spawn_resume(
523 key,
524 operation_id,
525 agent_id,
526 transport,
527 provider_session,
528 runtime_policy,
529 request,
530 environment,
531 extra_args,
532 one_shot_session_persistence,
533 mcp_server,
534 )
535 .await
536 }
537 ControlEffect::Stop { force } => self.stop_native(key, force).await,
538 ControlEffect::WriteInput {
539 input,
540 required_foreground,
541 } => match self.pty_sessions.get(&key) {
542 Some(owned) => match required_foreground {
543 ForegroundRequirement::Any
544 if matches!(
545 input.kind(),
546 PreparedInputKind::TerminalText
547 | PreparedInputKind::TerminalBytes
548 | PreparedInputKind::TerminalControl
549 ) =>
550 {
551 match owned.session.send_terminal_input(input).await {
552 Ok(()) => ControlObservation::InputCompleted,
553 Err(error) => ControlObservation::InputFailed {
554 message: error.to_string(),
555 },
556 }
557 }
558 ForegroundRequirement::Shell
559 if input.kind() == PreparedInputKind::ShellCommand =>
560 {
561 if !owned.runtime_policy.semantic_readiness {
562 ControlObservation::InputFailed {
563 message: "semantic shell input is not admitted by the provider runtime policy"
564 .to_owned(),
565 }
566 } else {
567 match owned.session.send_shell_input(input).await {
568 Ok(()) => ControlObservation::InputCompleted,
569 Err(error) => ControlObservation::InputFailed {
570 message: error.to_string(),
571 },
572 }
573 }
574 }
575 ForegroundRequirement::Agent { agent_id }
576 if matches!(
577 input.kind(),
578 PreparedInputKind::InsertDraft
579 | PreparedInputKind::SubmitPrompt
580 | PreparedInputKind::AgentCommand
581 ) && &agent_id == owned.session.agent_id() =>
582 {
583 if !owned.runtime_policy.semantic_readiness
584 || !owned.runtime_policy.structured_prompt
585 {
586 return completion_observation(
587 operation_id,
588 instance_id,
589 generation,
590 ControlObservation::InputFailed {
591 message: "semantic input is not admitted by the provider runtime policy"
592 .to_owned(),
593 },
594 );
595 }
596 let intent = match input.kind() {
597 PreparedInputKind::InsertDraft
598 | PreparedInputKind::AgentCommand => ReadinessIntent::DraftPaste,
599 PreparedInputKind::SubmitPrompt => ReadinessIntent::FollowupPrompt,
600 PreparedInputKind::ShellCommand
601 | PreparedInputKind::TerminalText
602 | PreparedInputKind::TerminalBytes
603 | PreparedInputKind::TerminalControl => unreachable!(),
604 };
605 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
606 return completion_observation(
607 operation_id,
608 instance_id,
609 generation,
610 ControlObservation::InputFailed {
611 message: "session agent disappeared from native catalog"
612 .to_owned(),
613 },
614 );
615 };
616 match wait_for_readiness(&owned.session, &spec, intent, false).await {
617 Ok(permit) => {
618 let result = if input.kind() == PreparedInputKind::AgentCommand
619 {
620 owned.session.send_agent_command_input(input, permit).await
621 } else {
622 owned.session.send_prepared_input(input, permit).await
623 };
624 match result {
625 Ok(()) => ControlObservation::InputCompleted,
626 Err(error) => ControlObservation::InputFailed {
627 message: error.to_string(),
628 },
629 }
630 }
631 Err(message) => ControlObservation::InputFailed { message },
632 }
633 }
634 required_foreground => ControlObservation::InputFailed {
635 message: format!(
636 "prepared input kind {:?} does not satisfy route {:?}",
637 input.kind(),
638 required_foreground
639 ),
640 },
641 },
642 None => ControlObservation::InputFailed {
643 message: "typed PTY input requires a PTY session".to_owned(),
644 },
645 },
646 ControlEffect::SubmitPrompt { prompt } => match self.acp_sessions.get(&key) {
647 Some(owned) if !owned.runtime_policy.structured_prompt => {
648 ControlObservation::InputFailed {
649 message: "structured prompt is not admitted by the provider runtime policy"
650 .to_owned(),
651 }
652 }
653 Some(owned) => match submit_acp_prompt(&owned.session, &prompt).await {
654 Ok(()) => ControlObservation::InputCompleted,
655 Err(error) => ControlObservation::InputFailed {
656 message: error.to_string(),
657 },
658 },
659 None => ControlObservation::InputFailed {
660 message: "semantic follow-up prompts require an ACP session".to_owned(),
661 },
662 },
663 ControlEffect::Interrupt => match self.acp_sessions.get(&key) {
664 Some(owned) => match owned.session.cancel().await {
665 Ok(()) => ControlObservation::InputCompleted,
666 Err(error) => ControlObservation::InputFailed {
667 message: error.to_string(),
668 },
669 },
670 None => ControlObservation::InputFailed {
671 message: "semantic interrupt requires an ACP session".to_owned(),
672 },
673 },
674 ControlEffect::ResolveInteraction { target, response } => {
675 resolve_acp_interaction_observation(
676 self.acp_sessions.get(&key).map(|owned| &owned.session),
677 target,
678 response,
679 )
680 }
681 ControlEffect::SetSessionMode { mode_id } => {
682 set_acp_session_mode_observation(
683 self.acp_sessions.get(&key).map(|owned| &owned.session),
684 mode_id,
685 )
686 .await
687 }
688 ControlEffect::SetSessionConfigOption {
689 option_id,
690 value_json,
691 } => {
692 set_acp_session_config_option_observation(
693 self.acp_sessions.get(&key).map(|owned| &owned.session),
694 option_id,
695 value_json,
696 )
697 .await
698 }
699 ControlEffect::SetSessionModel { model_id } => {
700 set_acp_session_model_observation(
701 self.acp_sessions.get(&key).map(|owned| &owned.session),
702 model_id,
703 )
704 }
705 ControlEffect::Resize { size } if !size.is_valid() => {
706 ControlObservation::ResizeFailed {
707 message: "terminal size is outside the supported range".to_owned(),
708 }
709 }
710 ControlEffect::Resize { size } => match self.pty_sessions.get(&key) {
711 Some(owned) => match owned.session.resize(size.rows, size.columns).await {
712 Ok(()) => ControlObservation::ResizeCompleted { size },
713 Err(error) => ControlObservation::ResizeFailed {
714 message: error.to_string(),
715 },
716 },
717 None => ControlObservation::ResizeFailed {
718 message: "terminal resize requires a PTY session".to_owned(),
719 },
720 },
721 ControlEffect::ObserveForeground => match self.pty_sessions.get(&key) {
722 Some(owned) => match owned.session.observe_foreground().await {
723 Ok(observation) => ControlObservation::ForegroundObserved {
724 process: canonical_foreground(
725 owned.session.agent_id().clone(),
726 &observation,
727 ),
728 },
729 Err(error) => ControlObservation::ForegroundFailed {
730 message: error.to_string(),
731 },
732 },
733 None => ControlObservation::ForegroundFailed {
734 message: "foreground observation requires a PTY session".to_owned(),
735 },
736 },
737 ControlEffect::ProbeCapabilities { .. } => {
738 ControlObservation::CapabilityProbeFailed {
739 failure: CapabilityProbeFailure::ExecutorUnavailable,
740 }
741 }
742 ControlEffect::DiscoverHistory { .. } | ControlEffect::LoadHistory { .. } => {
743 ControlObservation::HistoryFailed {
744 message: "history effects require the dedicated native history authority"
745 .to_owned(),
746 }
747 }
748 ControlEffect::AuthorizeResume { .. } => ControlObservation::ResumeFailed {
749 message: "resume authorization requires the dedicated native authority"
750 .to_owned(),
751 },
752 }
753 };
754
755 completion_observation(operation_id, instance_id, generation, observation)
756 }
757
758 async fn spawn_native(
759 &mut self,
760 key: NativeSessionKey,
761 operation_id: OperationId,
762 spawn: NativeSpawnRequest,
763 pty_env: Vec<EnvMutation>,
764 mcp_server: Option<McpServerSpec>,
765 ) -> ControlObservation {
766 let NativeSpawnRequest {
767 agent_id,
768 transport,
769 request,
770 runtime_policy,
771 mut launch_extra_args,
772 instance_extra_args,
773 resumed_provider_session,
774 one_shot_session_persistence,
775 } = spawn;
776 if let Err(message) =
777 validate_instance_launch_arguments(&agent_id, transport, &instance_extra_args)
778 {
779 return ControlObservation::SpawnFailed { message };
780 }
781 if let Err(message) = validate_spawn_runtime_policy(
782 runtime_policy,
783 transport,
784 request.initial_prompt.is_some(),
785 resumed_provider_session.is_some(),
786 ) {
787 return ControlObservation::SpawnFailed { message };
788 }
789 if self.session_exists(key) {
790 return ControlObservation::SpawnFailed {
791 message: format!(
792 "native session {:?}/{:?} already exists",
793 key.instance_id, key.generation
794 ),
795 };
796 }
797 if !request.terminal_size.is_valid() {
798 return ControlObservation::SpawnFailed {
799 message: "terminal size is outside the supported range".to_owned(),
800 };
801 }
802 if request.working_directory.is_empty()
803 || request.working_directory.len() > WORKING_DIRECTORY_MAX_BYTES
804 || request.working_directory.contains('\0')
805 {
806 return ControlObservation::SpawnFailed {
807 message: "working directory is invalid".to_owned(),
808 };
809 }
810 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
811 return ControlObservation::SpawnFailed {
812 message: format!("agent '{agent_id}' is absent from native catalog"),
813 };
814 };
815 let working_dir = PathBuf::from(&request.working_directory);
816
817 match transport {
818 TransportKind::Pty if !spec.capabilities.transports.pty => {
819 ControlObservation::SpawnFailed {
820 message: format!("agent '{agent_id}' does not support PTY transport"),
821 }
822 }
823 TransportKind::Pty => {
824 let pty_env = with_pty_terminal_capability_defaults(pty_env);
829 let fresh_provider_session = prepare_fresh_pty_provider_session(
830 spec.capabilities.transports.pty_adapter.as_ref(),
831 resumed_provider_session.is_some(),
832 runtime_policy.provider_session_identity,
833 &mut launch_extra_args,
834 );
835 launch_extra_args.extend(instance_extra_args);
836 let mut authoritative_provider_session = resumed_provider_session
837 .clone()
838 .or(fresh_provider_session);
839 let probe_kimi_identity = should_probe_pty_identity(
840 runtime_policy,
841 spec.capabilities.transports.pty_adapter.as_ref(),
842 authoritative_provider_session.is_some(),
843 "kimi",
844 );
845 let probe_codex_identity = should_probe_pty_identity(
846 runtime_policy,
847 spec.capabilities.transports.pty_adapter.as_ref(),
848 authoritative_provider_session.is_some(),
849 "codex",
850 );
851 tracing::info!(
864 agent_id = %agent_id,
865 instance_id = ?key.instance_id,
866 generation = ?key.generation,
867 terminal_size = ?request.terminal_size,
868 program = %spec.launch.program,
869 fixed_args = ?spec.launch.fixed_args,
870 extra_args = ?redact_provider_arguments(&launch_extra_args),
871 has_initial_prompt = request.initial_prompt.is_some(),
872 "spawning provider process over a PTY",
873 );
874 match PtySession::spawn_agent_with_size(
875 &spec,
876 LaunchRequest {
877 working_dir,
878 env: pty_env,
879 platform: RuntimePlatform::current(),
880 prompt: request.initial_prompt,
881 session_options: request.session_options,
882 extra_args: launch_extra_args,
883 },
884 request.terminal_size.rows,
885 request.terminal_size.columns,
886 )
887 .await
888 {
889 Ok(mut session) => {
890 if probe_kimi_identity {
891 match probe_fresh_kimi_session_identity(&session, &spec).await {
892 Ok(Some(identity)) => authoritative_provider_session = Some(identity),
893 Ok(None) => {}
894 Err(error) => {
895 let message = match session.shutdown().await {
896 Ok(_) => error,
897 Err(shutdown_error) => {
898 format!("{error}; PTY cleanup failed: {shutdown_error}")
899 }
900 };
901 return ControlObservation::SpawnFailed { message };
902 }
903 }
904 }
905 if probe_codex_identity {
906 match probe_fresh_codex_session_identity(&session, &spec).await {
907 Ok(Some(identity)) => authoritative_provider_session = Some(identity),
908 Ok(None) => {}
909 Err(error) => {
910 let message = match session.shutdown().await {
911 Ok(_) => error,
912 Err(shutdown_error) => {
913 format!("{error}; PTY cleanup failed: {shutdown_error}")
914 }
915 };
916 return ControlObservation::SpawnFailed { message };
917 }
918 }
919 }
920 if let Err(error) = deliver_pending_initial_prompt(&mut session, &spec).await {
921 let message = match session.shutdown().await {
922 Ok(_) => error,
923 Err(shutdown_error) => {
924 format!("{error}; PTY cleanup failed: {shutdown_error}")
925 }
926 };
927 return ControlObservation::SpawnFailed { message };
928 }
929 let process_id = session.root_pid();
930 let provider = match spec.capabilities.transports.pty_adapter.as_ref() {
931 _ if !should_attach_pty_provider_stream(runtime_policy) => None,
932 Some(adapter) => {
933 let tool = match self
934 .legacy_adapters
935 .resolve(AdapterFamily::PtySemantic, adapter)
936 {
937 Ok(tool) => *tool,
938 Err(error) => {
939 let _ = session.shutdown().await;
940 return ControlObservation::SpawnFailed {
941 message: error.to_string(),
942 };
943 }
944 };
945 match session.attach_events(session.beginning_cursor()) {
946 Ok(attachment) => {
947 let mut pending_events = VecDeque::new();
948 let mut provider_session_started = false;
949 if let Some(identity) = authoritative_provider_session {
950 pending_events.push_back(ProviderEvent::SessionStarted {
951 session_id: identity.id.clone(),
952 model: String::new(),
953 tools: Vec::new(),
954 });
955 pending_events.push_back(
956 ProviderEvent::SessionIdentityObserved { identity },
957 );
958 provider_session_started = true;
959 }
960 let is_kimi = tool == CliTool::KimiCode;
961 Some(OwnedPtyProvider {
962 source: ProviderSource {
963 family: AdapterFamily::PtySemantic,
964 binding: adapter.clone(),
965 },
966 receiver: attachment.receiver,
967 replay: attachment.replay.into(),
968 pending_events,
969 utf8: Utf8ChunkDecoder::default(),
970 pipeline: Mutex::new(create_pipeline(tool)),
971 rate_limits: RateLimitFeed::new_for_tool(tool),
972 kimi_identity: (runtime_policy.provider_session_identity
973 && is_kimi
974 && !provider_session_started)
975 .then(KimiPtySessionIdentityExtractor::default),
976 semantic_events: runtime_policy.semantic_readiness,
977 provider_session_started,
978 next_provider_sequence: 1,
979 })
980 }
981 Err(error) => {
982 let _ = session.shutdown().await;
983 return ControlObservation::SpawnFailed {
984 message: error.to_string(),
985 };
986 }
987 }
988 }
989 None => None,
990 };
991 self.pty_sessions.insert(
992 key,
993 OwnedPtySession {
994 session,
995 spawn_operation_id: operation_id,
996 last_terminal_sequence: 0,
997 terminal_stale_published: false,
998 runtime_policy,
999 provider,
1000 agent_id,
1001 last_screen_gate: None,
1002 last_screen_failure: None,
1003 last_foreground_verdict: None,
1004 last_screen_state: PtyScreenState::default(),
1005 ever_reached_ready: false,
1006 screen_had_content: false,
1007 next_foreground_probe: Some(Instant::now()),
1012 },
1013 );
1014 ControlObservation::Spawned { process_id }
1015 }
1016 Err(error) => {
1017 let message = error.to_string();
1018 tracing::warn!(
1019 agent_id = %agent_id,
1020 instance_id = ?key.instance_id,
1021 generation = ?key.generation,
1022 program = %spec.launch.program,
1023 fixed_args = ?spec.launch.fixed_args,
1024 cause = %message,
1025 "provider process failed to start",
1026 );
1027 ControlObservation::SpawnFailed { message }
1028 }
1029 }
1030 }
1031 TransportKind::Pipe => {
1032 let Some(pipe_spec) = spec.capabilities.transports.pipe.as_ref() else {
1033 return ControlObservation::SpawnFailed {
1034 message: format!("agent '{agent_id}' does not support Pipe transport"),
1035 };
1036 };
1037 let prompt = request.initial_prompt.unwrap_or_default();
1038 if pipe_spec.protocol == PipeProtocol::OneShotText {
1039 let Some(binding) = spec.capabilities.adapters.one_shot.as_ref() else {
1040 return ControlObservation::SpawnFailed {
1041 message: format!(
1042 "agent '{agent_id}' does not declare OneShot capability"
1043 ),
1044 };
1045 };
1046 if binding != &pipe_spec.adapter {
1047 return ControlObservation::SpawnFailed {
1048 message: format!(
1049 "agent '{agent_id}' has mismatched OneShot transport bindings"
1050 ),
1051 };
1052 }
1053 return match NativeOneShotSession::spawn_with_environment_and_persistence(
1054 &spec,
1055 binding,
1056 &prompt,
1057 request.session_options.as_ref(),
1058 &working_dir,
1059 &pty_env,
1060 one_shot_session_persistence,
1061 )
1062 .await
1063 {
1064 Ok(session) => {
1065 let process_id = session.process_id();
1066 let events = session.subscribe();
1067 self.one_shot_sessions.insert(
1068 key,
1069 OwnedProviderSession {
1070 source: ProviderSource {
1071 family: AdapterFamily::OneShot,
1072 binding: binding.clone(),
1073 },
1074 session,
1075 events,
1076 pending_events: VecDeque::new(),
1077 pending_provider_events: VecDeque::new(),
1078 next_provider_sequence: 1,
1079 observed_exit_code: None,
1080 runtime_policy,
1081 },
1082 );
1083 ControlObservation::Spawned { process_id }
1084 }
1085 Err(error) => ControlObservation::SpawnFailed {
1086 message: error.to_string(),
1087 },
1088 };
1089 }
1090 let tool = match self
1091 .legacy_adapters
1092 .resolve(AdapterFamily::Pipe, &pipe_spec.adapter)
1093 {
1094 Ok(tool) => *tool,
1095 Err(error) => {
1096 return ControlObservation::SpawnFailed {
1097 message: error.to_string(),
1098 }
1099 }
1100 };
1101 let source = ProviderSource {
1102 family: AdapterFamily::Pipe,
1103 binding: pipe_spec.adapter.clone(),
1104 };
1105 let config = SessionConfig {
1106 tool,
1107 working_dir,
1108 env_vars: Vec::new(),
1109 name: None,
1110 };
1111 if resumed_provider_session.is_some() && pipe_spec.launch_override.is_some() {
1112 return ControlObservation::SpawnFailed {
1113 message: format!(
1114 "agent '{agent_id}' cannot resume through a catalog launch override"
1115 ),
1116 };
1117 }
1118 let mut options = PipeProcessOptions::default();
1119 if let Some(identity) = resumed_provider_session.as_ref() {
1120 options.claude.resume_session_id = Some(identity.id.clone());
1121 }
1122 let spawned = match pipe_spec.launch_override.as_ref() {
1123 Some(launch) => {
1124 PipeSession::spawn_with_launch(
1125 config,
1126 &prompt,
1127 launch,
1128 pipe_spec.prompt_delivery,
1129 )
1130 .await
1131 }
1132 None => {
1133 PipeSession::spawn(config, &prompt, options).await
1134 }
1135 };
1136 match spawned {
1137 Ok(session) => {
1138 let process_id = session.process_id();
1139 let events = session.subscribe();
1140 let pending_events = if pipe_spec.protocol == PipeProtocol::SemanticNdjson {
1141 VecDeque::from([AgentEvent::SessionStart {
1142 session_id: session.session_id().to_owned(),
1143 model: String::new(),
1144 tools: Vec::new(),
1145 }])
1146 } else {
1147 VecDeque::new()
1148 };
1149 self.pipe_sessions.insert(
1150 key,
1151 OwnedProviderSession {
1152 source,
1153 session,
1154 events,
1155 pending_events,
1156 pending_provider_events: VecDeque::new(),
1157 next_provider_sequence: 1,
1158 observed_exit_code: None,
1159 runtime_policy,
1160 },
1161 );
1162 ControlObservation::Spawned { process_id }
1163 }
1164 Err(error) => ControlObservation::SpawnFailed {
1165 message: error.to_string(),
1166 },
1167 }
1168 }
1169 TransportKind::Acp => {
1170 let Some(acp_spec) = spec.capabilities.transports.acp else {
1171 return ControlObservation::SpawnFailed {
1172 message: format!("agent '{agent_id}' does not support ACP transport"),
1173 };
1174 };
1175 let tool = match self
1176 .legacy_adapters
1177 .resolve(AdapterFamily::Acp, &acp_spec.adapter)
1178 {
1179 Ok(tool) => *tool,
1180 Err(error) => {
1181 return ControlObservation::SpawnFailed {
1182 message: error.to_string(),
1183 }
1184 }
1185 };
1186 let source = ProviderSource {
1187 family: AdapterFamily::Acp,
1188 binding: acp_spec.adapter.clone(),
1189 };
1190 let acp_mode_id = match required_acp_mode(&agent_id, request.approval_level) {
1219 Ok(mode_id) => mode_id,
1220 Err(message) => return ControlObservation::SpawnFailed { message },
1221 };
1222 let mcp_servers: Vec<McpServerConfig> =
1230 mcp_server.as_ref().map(mcp_server_acp_entry).into_iter().collect();
1231 if !mcp_servers.is_empty() {
1232 tracing::info!(
1240 agent_id = %agent_id,
1241 instance_id = ?key.instance_id,
1242 mcp_server_names = ?mcp_servers.iter().map(McpServerConfig::name).collect::<Vec<_>>(),
1243 "acp session/new carries {} mcp server(s)",
1244 mcp_servers.len(),
1245 );
1246 }
1247 let mut approval_level_args =
1251 acp_approval_level_args(&agent_id, request.approval_level);
1252 for argument in &instance_extra_args {
1253 approval_level_args.push(argument.to_string_lossy().into_owned());
1254 }
1255 let acp_options = AcpSessionOptions {
1256 host_policy: host_policy_for_approval_level(request.approval_level),
1257 approval_level_args,
1272 defer_permission_requests: defers_permission_requests(
1273 &agent_id,
1274 request.approval_level,
1275 ),
1276 mcp_servers,
1277 ..AcpSessionOptions::default()
1278 };
1279 let spawned = match acp_spec.launch_override.as_ref() {
1280 Some(launch) => {
1281 AcpSession::spawn_with_launch(tool, &working_dir, acp_options, launch)
1282 .await
1283 }
1284 None => AcpSession::spawn(tool, &working_dir, acp_options).await,
1285 };
1286 match spawned {
1287 Ok(session) => {
1288 let events = session.subscribe();
1290 tracing::info!(capabilities = ?session.capability_names(),
1291 "ACP initialize capabilities");
1292 if let Some(identity) = resumed_provider_session.as_ref() {
1293 if !session.supports_load_session() {
1294 let _ = session.kill().await;
1295 return ControlObservation::SpawnFailed {
1296 message: "ACP session/load unsupported".to_owned(),
1297 };
1298 }
1299 if let Err(error) = session.load_session(&identity.id).await {
1300 let _ = session.kill().await;
1301 return ControlObservation::SpawnFailed { message: error.to_string() };
1302 }
1303 }
1304 if let Some(mode_id) = acp_mode_id.as_ref() {
1305 if let Err(message) =
1306 apply_acp_approval_mode(&session, mode_id, request.approval_level)
1307 .await
1308 {
1309 let _ = session.kill().await;
1310 return ControlObservation::SpawnFailed { message };
1311 }
1312 }
1313 let process_id = session.process_id();
1314 let session_id = session
1315 .acp_session_id()
1316 .await
1317 .unwrap_or_else(|| session.session_id().to_owned());
1318 let identity_observed = if runtime_policy.provider_session_identity {
1348 match session.provider_reported_session_id().await {
1349 Some(id) => Some(ProviderEvent::SessionIdentityObserved {
1350 identity: ProviderSessionIdentity {
1351 key: ProviderSessionKey::SessionId,
1352 id,
1353 transcript_path: None,
1354 },
1355 }),
1356 None => {
1357 tracing::warn!(
1358 agent_id = %agent_id,
1359 adapter = %acp_spec.adapter.id,
1360 "ACP session/new returned no sessionId; provider \
1361 session identity stays IdentityPending",
1362 );
1363 None
1364 }
1365 }
1366 } else {
1367 None
1368 };
1369 if let Some(prompt) = request.initial_prompt {
1370 if let Err(error) = session.start_prompt(&prompt).await {
1371 let _ = session.kill().await;
1372 return ControlObservation::SpawnFailed {
1373 message: error.to_string(),
1374 };
1375 }
1376 }
1377 let announced_mode = session.current_mode_id();
1379 self.acp_sessions.insert(
1380 key,
1381 OwnedProviderSession {
1382 source,
1383 session,
1384 events,
1385 pending_events: {
1386 let mut seeded = VecDeque::from([AgentEvent::SessionStart {
1387 session_id,
1388 model: String::new(),
1389 tools: Vec::new(),
1390 }]);
1391 if let Some(mode_id) = announced_mode {
1414 seeded.push_back(AgentEvent::ModeChanged { mode_id });
1415 }
1416 seeded
1417 },
1418 pending_provider_events: VecDeque::from_iter(identity_observed),
1419 next_provider_sequence: 1,
1420 observed_exit_code: None,
1421 runtime_policy,
1422 },
1423 );
1424 ControlObservation::Spawned { process_id }
1425 }
1426 Err(error) => ControlObservation::SpawnFailed {
1427 message: error.to_string(),
1428 },
1429 }
1430 }
1431 }
1432 }
1433
1434 async fn spawn_resume(
1435 &mut self,
1436 key: NativeSessionKey,
1437 operation_id: OperationId,
1438 agent_id: AgentId,
1439 transport: TransportKind,
1440 provider_session: gate4agent_types::ProviderSessionIdentity,
1441 runtime_policy: ProviderRuntimePolicy,
1442 request: ResumeLaunchRequest,
1443 pty_env: Vec<EnvMutation>,
1444 instance_extra_args: Vec<OsString>,
1445 one_shot_session_persistence: OneShotSessionPersistence,
1446 mcp_server: Option<McpServerSpec>,
1447 ) -> ControlObservation {
1448 if let Err(message) = validate_spawn_runtime_policy(
1449 runtime_policy,
1450 transport,
1451 request.initial_prompt.is_some(),
1452 true,
1453 ) {
1454 return ControlObservation::SpawnFailed { message };
1455 }
1456 if let Err(error) = request.validate() {
1457 return ControlObservation::SpawnFailed {
1458 message: error.to_string(),
1459 };
1460 }
1461 let Some(spec) = self.catalog.get(&agent_id) else {
1462 return ControlObservation::SpawnFailed {
1463 message: format!("agent '{agent_id}' is absent from native catalog"),
1464 };
1465 };
1466 let Some(binding) = spec.capabilities.adapters.resume.as_ref() else {
1467 return ControlObservation::SpawnFailed {
1468 message: format!("agent '{agent_id}' does not declare Resume capability"),
1469 };
1470 };
1471 let plan = match build_resume_plan_for_identity(&binding.id, &provider_session) {
1472 Ok(Some(plan)) => plan,
1473 Ok(None) => {
1474 return ControlObservation::SpawnFailed {
1475 message: format!("agent '{agent_id}' has no live Resume plan"),
1476 }
1477 }
1478 Err(error) => {
1479 return ControlObservation::SpawnFailed {
1480 message: error.to_string(),
1481 }
1482 }
1483 };
1484 if transport == TransportKind::Pipe {
1485 let Some(pipe) = spec.capabilities.transports.pipe.as_ref() else {
1486 return ControlObservation::SpawnFailed {
1487 message: format!("agent '{agent_id}' does not support Pipe transport"),
1488 };
1489 };
1490 if pipe.protocol != PipeProtocol::StructuredJsonl {
1491 return ControlObservation::SpawnFailed {
1492 message: format!(
1493 "agent '{agent_id}' does not expose a resumable structured Pipe contract"
1494 ),
1495 };
1496 }
1497 }
1498 let start = StartRequest {
1499 working_directory: request.working_directory,
1500 terminal_size: request.terminal_size,
1501 initial_prompt: request.initial_prompt,
1502 session_options: None,
1508 approval_level: ApprovalLevel::default(),
1509 };
1510 self.spawn_native(
1511 key,
1512 operation_id,
1513 NativeSpawnRequest {
1514 agent_id,
1515 transport,
1516 request: start,
1517 runtime_policy,
1518 launch_extra_args: if transport == TransportKind::Pty {
1519 plan.args.into_iter().map(OsString::from).collect()
1520 } else {
1521 Vec::new()
1522 },
1523 instance_extra_args,
1524 resumed_provider_session: Some(provider_session),
1525 one_shot_session_persistence,
1526 },
1527 pty_env,
1528 mcp_server,
1529 )
1530 .await
1531 }
1532
1533 async fn stop_native(&mut self, key: NativeSessionKey, force: bool) -> ControlObservation {
1534 if let Some(owned) = self.pty_sessions.remove(&key) {
1535 let shutdown = owned.session.shutdown().await;
1536 return match shutdown {
1537 Ok(outcome) => ControlObservation::StopCompleted {
1538 forced: force || outcome.termination.is_some(),
1539 exit_code: outcome.exit_code,
1540 final_terminal: Some(terminal_frame(outcome.terminal, owned.last_screen_state.clone())),
1544 },
1545 Err(error) => {
1546 eprintln!(
1547 "[gate4agent-shell-native] PTY stop failed for {key:?} (force={force}): {error}",
1548 );
1549 ControlObservation::StopFailed {
1550 message: error.to_string(),
1551 }
1552 }
1553 };
1554 }
1555 if let Some(owned) = self.pipe_sessions.remove(&key) {
1556 return match owned.session.stop(force).await {
1569 Ok(outcome) => ControlObservation::StopCompleted {
1570 forced: outcome.forced,
1571 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1572 final_terminal: None,
1573 },
1574 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1575 forced: false,
1576 exit_code: owned.observed_exit_code,
1577 final_terminal: None,
1578 },
1579 Err(error) => ControlObservation::StopFailed {
1580 message: error.to_string(),
1581 },
1582 };
1583 }
1584 if let Some(mut owned) = self.one_shot_sessions.remove(&key) {
1585 return match owned.session.kill().await {
1586 Ok(()) => ControlObservation::StopCompleted {
1587 forced: true,
1588 exit_code: owned.observed_exit_code,
1589 final_terminal: None,
1590 },
1591 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1592 forced: false,
1593 exit_code: owned.observed_exit_code,
1594 final_terminal: None,
1595 },
1596 Err(error) => ControlObservation::StopFailed {
1597 message: error.to_string(),
1598 },
1599 };
1600 }
1601 if let Some(owned) = self.acp_sessions.remove(&key) {
1602 return match owned.session.stop(force).await {
1613 Ok(outcome) => ControlObservation::StopCompleted {
1614 forced: outcome.forced,
1615 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1616 final_terminal: None,
1617 },
1618 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1619 forced: false,
1620 exit_code: owned.observed_exit_code,
1621 final_terminal: None,
1622 },
1623 Err(error) => ControlObservation::StopFailed {
1624 message: error.to_string(),
1625 },
1626 };
1627 }
1628 eprintln!("[gate4agent-shell-native] stop skipped: no session owns {key:?} in any transport map");
1634 ControlObservation::StopFailed {
1635 message: missing_session_message(key),
1636 }
1637 }
1638
1639 fn session_exists(&self, key: NativeSessionKey) -> bool {
1640 self.pty_sessions.contains_key(&key)
1641 || self.pipe_sessions.contains_key(&key)
1642 || self.one_shot_sessions.contains_key(&key)
1643 || self.acp_sessions.contains_key(&key)
1644 }
1645
1646 pub async fn collect_exits(&mut self) -> Vec<ObservationEnvelope> {
1649 let completed: Vec<_> = self
1650 .pty_sessions
1651 .iter()
1652 .filter_map(|(key, owned)| owned.session.reader_finished().then_some(*key))
1653 .collect();
1654 let mut observations = Vec::with_capacity(completed.len());
1655 for key in completed {
1656 let owned = self
1657 .pty_sessions
1658 .remove(&key)
1659 .expect("completed key came from the owned session map");
1660 let last_screen_state = owned.last_screen_state.clone();
1661 let (exit_code, final_terminal) = match owned.session.shutdown().await {
1662 Ok(outcome) => (
1663 outcome.exit_code,
1664 Some(terminal_frame(outcome.terminal, last_screen_state)),
1665 ),
1666 Err(_) => (None, None),
1667 };
1668 observations.push(ObservationEnvelope {
1669 operation_id: None,
1670 instance_id: key.instance_id,
1671 generation: key.generation,
1672 observation: ControlObservation::ProcessExited {
1673 exit_code,
1674 final_terminal,
1675 },
1676 });
1677 }
1678 collect_provider_exits(&mut self.pipe_sessions, &mut observations, |session| {
1679 session.reader_finished()
1680 });
1681 collect_provider_exits(&mut self.one_shot_sessions, &mut observations, |session| {
1682 session.reader_finished()
1683 });
1684 collect_provider_exits(&mut self.acp_sessions, &mut observations, |session| {
1685 session.reader_finished()
1686 });
1687 observations
1688 }
1689
1690 pub fn collect_provider_events(&mut self) -> Vec<ObservationEnvelope> {
1693 let mut observations = self.pending_observations.drain(..).collect::<Vec<_>>();
1694 for (key, owned) in &mut self.pty_sessions {
1695 if let Some(provider) = &mut owned.provider {
1696 drain_pty_provider(*key, provider, &mut observations);
1697 }
1698 }
1699 collect_provider_map(&mut self.pipe_sessions, &mut observations, |_| Vec::new());
1700 collect_provider_map(&mut self.one_shot_sessions, &mut observations, |_| Vec::new());
1701 for owned in self.acp_sessions.values() {
1713 owned.session.expire_deadlines();
1714 }
1715 collect_provider_map(&mut self.acp_sessions, &mut observations, AcpSession::available_modes);
1716 observations
1717 }
1718
1719 pub fn collect_terminal_frames(&mut self) -> Vec<ObservationEnvelope> {
1733 let mut observations = Vec::new();
1734 let pty_sessions = &mut self.pty_sessions;
1740 let efficiency_facts = &mut self.efficiency_facts;
1741 for (key, owned) in pty_sessions {
1742 if terminal_state_capture_should_skip(
1743 owned.session.terminal_sequence(),
1744 owned.last_terminal_sequence,
1745 ) {
1746 efficiency_facts.record_terminal_state_skip();
1747 continue;
1748 }
1749 let capture_start = Instant::now();
1750 let terminal_state = owned.session.terminal_state();
1751 efficiency_facts.record_terminal_state_capture(capture_start.elapsed());
1752 match terminal_state {
1753 Ok(snapshot) if snapshot.sequence > owned.last_terminal_sequence => {
1754 owned.last_terminal_sequence = snapshot.sequence;
1755 owned.terminal_stale_published = false;
1756
1757 owned.last_screen_gate = startup_operator_gate(&snapshot.contents);
1761 owned.last_screen_failure =
1772 screen_failure_for_generation(&snapshot.contents, owned.ever_reached_ready);
1773 let merged = classify_pty_screen_state(
1774 owned.last_foreground_verdict.as_ref(),
1775 owned.last_screen_gate.as_ref(),
1776 owned.last_screen_failure,
1777 );
1778 if !snapshot.contents.trim().is_empty() {
1789 owned.screen_had_content = true;
1790 }
1791 if merged == PtyScreenState::Ready && owned.screen_had_content {
1792 owned.ever_reached_ready = true;
1793 }
1794 if merged != owned.last_screen_state {
1795 if foreground_probe_rearms_immediately(&owned.last_screen_state, &merged) {
1796 owned.next_foreground_probe = Some(Instant::now());
1797 }
1798 owned.last_screen_state = merged.clone();
1799 observations.push(ObservationEnvelope {
1800 operation_id: None,
1801 instance_id: key.instance_id,
1802 generation: key.generation,
1803 observation: ControlObservation::ScreenState {
1804 state: merged.clone(),
1805 },
1806 });
1807 }
1808
1809 let frame = terminal_frame(snapshot, merged);
1810 efficiency_facts.record_terminal_frame_published(terminal_frame_byte_len(&frame));
1811 observations.push(ObservationEnvelope {
1812 operation_id: None,
1813 instance_id: key.instance_id,
1814 generation: key.generation,
1815 observation: ControlObservation::TerminalFrame { frame },
1816 });
1817 }
1818 Ok(_) => {}
1819 Err(error) if !owned.terminal_stale_published => {
1820 owned.terminal_stale_published = true;
1821 observations.push(ObservationEnvelope {
1822 operation_id: None,
1823 instance_id: key.instance_id,
1824 generation: key.generation,
1825 observation: ControlObservation::TerminalStale {
1826 message: error.to_string(),
1827 },
1828 });
1829 }
1830 Err(_) => {}
1831 }
1832 }
1833 observations
1834 }
1835
1836 pub async fn reclassify_foreground(&mut self) -> Vec<ObservationEnvelope> {
1854 let catalog = &self.catalog;
1855 let now = Instant::now();
1856 let due: Vec<NativeSessionKey> = self
1857 .pty_sessions
1858 .iter()
1859 .filter(|(_, owned)| owned.next_foreground_probe.is_some_and(|at| now >= at))
1860 .map(|(key, _)| *key)
1861 .collect();
1862
1863 let mut observations = Vec::new();
1864 for key in due {
1865 let Some(owned) = self.pty_sessions.get_mut(&key) else {
1866 continue;
1867 };
1868 let probe_result = owned.session.observe_foreground_timed().await;
1869 match probe_result {
1870 Ok((observation, timing)) => {
1871 self.efficiency_facts.record_foreground_probe(timing);
1884 let verdict = match catalog.get(&owned.agent_id) {
1885 Some(spec) => resolve_foreground_verdict(
1886 spec,
1887 &observation,
1888 RuntimePlatform::current(),
1889 ),
1890 None => ForegroundVerdict::Foreign {
1896 process: observation.observed_process.clone(),
1897 },
1898 };
1899 owned.last_foreground_verdict = Some(verdict);
1900 let merged = classify_pty_screen_state(
1901 owned.last_foreground_verdict.as_ref(),
1902 owned.last_screen_gate.as_ref(),
1903 owned.last_screen_failure,
1904 );
1905 if merged == PtyScreenState::Ready && owned.screen_had_content {
1910 owned.ever_reached_ready = true;
1911 }
1912 if merged != owned.last_screen_state {
1913 owned.last_screen_state = merged.clone();
1914 observations.push(ObservationEnvelope {
1915 operation_id: None,
1916 instance_id: key.instance_id,
1917 generation: key.generation,
1918 observation: ControlObservation::ScreenState { state: merged },
1919 });
1920 }
1921 owned.next_foreground_probe =
1922 match foreground_probe_schedule(&owned.last_screen_state) {
1923 ForegroundProbeSchedule::Disarmed => None,
1924 ForegroundProbeSchedule::Armed => {
1925 Some(now + FOREGROUND_RECLASSIFY_INTERVAL)
1926 }
1927 };
1928 }
1929 Err(_) => {
1930 owned.next_foreground_probe = Some(now + FOREGROUND_RECLASSIFY_INTERVAL);
1937 }
1938 }
1939 }
1940 observations
1941 }
1942}
1943
1944const PTY_TERM_DEFAULT_KEY: &str = "TERM";
1951const PTY_TERM_DEFAULT_VALUE: &str = "xterm-256color";
1952const PTY_COLORTERM_DEFAULT_KEY: &str = "COLORTERM";
1953const PTY_COLORTERM_DEFAULT_VALUE: &str = "truecolor";
1954
1955fn with_pty_terminal_capability_defaults(mut pty_env: Vec<EnvMutation>) -> Vec<EnvMutation> {
1961 let already_mutated = |env: &[EnvMutation], key: &str| {
1962 env.iter()
1963 .any(|mutation| mutation.key.as_os_str() == OsStr::new(key))
1964 };
1965 if !already_mutated(&pty_env, PTY_TERM_DEFAULT_KEY) {
1966 pty_env.push(EnvMutation {
1967 key: OsString::from(PTY_TERM_DEFAULT_KEY),
1968 value: Some(OsString::from(PTY_TERM_DEFAULT_VALUE)),
1969 });
1970 }
1971 if !already_mutated(&pty_env, PTY_COLORTERM_DEFAULT_KEY) {
1972 pty_env.push(EnvMutation {
1973 key: OsString::from(PTY_COLORTERM_DEFAULT_KEY),
1974 value: Some(OsString::from(PTY_COLORTERM_DEFAULT_VALUE)),
1975 });
1976 }
1977 pty_env
1978}
1979
1980fn missing_session_message(key: NativeSessionKey) -> String {
1981 format!(
1982 "native session {:?}/{:?} does not exist",
1983 key.instance_id, key.generation
1984 )
1985}
1986
1987fn host_policy_for_approval_level(level: ApprovalLevel) -> HostPolicy {
2012 match level {
2013 ApprovalLevel::FullAuto => HostPolicy::Yolo,
2014 ApprovalLevel::ReadOnly => HostPolicy::ReadOnly,
2015 ApprovalLevel::Moderate | ApprovalLevel::Unmanaged => HostPolicy::Auto,
2016 }
2017}
2018
2019fn defers_permission_requests(agent_id: &AgentId, level: ApprovalLevel) -> bool {
2050 match approval_level_resolution(agent_id, level) {
2051 ApprovalLevelResolution::Supported {
2052 asks_for_permission,
2053 ..
2054 } => asks_for_permission,
2055 ApprovalLevelResolution::Unsupported => true,
2056 }
2057}
2058
2059const ACP_MODE_CONFIRMATION_TIMEOUT: Duration = Duration::from_secs(5);
2069
2070fn required_acp_mode(agent_id: &AgentId, level: ApprovalLevel) -> Result<Option<ModeId>, String> {
2087 let (acp_mode_id, carries_argv_flags) = match approval_level_resolution(agent_id, level) {
2088 ApprovalLevelResolution::Unsupported => (None, false),
2089 ApprovalLevelResolution::Supported { acp_mode_id, args, .. } => {
2090 (acp_mode_id, !args.is_empty())
2091 }
2092 };
2093 match (acp_mode_id, level) {
2094 (Some(mode_id), _) => Ok(Some(mode_id)),
2095 (None, ApprovalLevel::Unmanaged) => Ok(None),
2096 (None, _) if carries_argv_flags => Ok(None),
2105 (None, ApprovalLevel::FullAuto) if acp_full_auto_is_host_policy(agent_id) => Ok(None),
2110 (None, _) => Err(format!(
2111 "agent '{agent_id}' has no verified ACP mode for {level:?} and the level carries no \
2112 vendor flags to apply through argv either; refusing rather than launching at the \
2113 vendor's own (wider-authority) default"
2114 )),
2115 }
2116}
2117
2118fn acp_approval_level_args(agent_id: &AgentId, level: ApprovalLevel) -> Vec<String> {
2135 match approval_level_resolution(agent_id, level) {
2136 ApprovalLevelResolution::Supported { args, acp_mode_id: None, .. } => args,
2137 ApprovalLevelResolution::Supported { acp_mode_id: Some(_), .. } => Vec::new(),
2138 ApprovalLevelResolution::Unsupported => Vec::new(),
2139 }
2140}
2141
2142#[derive(Debug)]
2150struct ApprovalLevelNotOfferedByAgent {
2151 level: ApprovalLevel,
2152 offered: Vec<String>,
2153}
2154
2155impl std::fmt::Display for ApprovalLevelNotOfferedByAgent {
2156 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2157 write!(
2158 formatter,
2159 "ApprovalLevelNotOfferedByAgent {{ level: {:?}, offered: {:?} }}",
2160 self.level, self.offered
2161 )
2162 }
2163}
2164
2165fn approval_level_not_offered_message(
2171 level: ApprovalLevel,
2172 mode_id: &ModeId,
2173 offered: &[SessionMode],
2174) -> Option<String> {
2175 if offered.iter().any(|mode| mode.id == mode_id.as_str()) {
2176 None
2177 } else {
2178 Some(
2179 ApprovalLevelNotOfferedByAgent {
2180 level,
2181 offered: offered.iter().map(|mode| mode.id.clone()).collect(),
2182 }
2183 .to_string(),
2184 )
2185 }
2186}
2187
2188async fn apply_acp_approval_mode(
2206 session: &AcpSession,
2207 mode_id: &ModeId,
2208 level: ApprovalLevel,
2209) -> Result<(), String> {
2210 if let Some(message) =
2211 approval_level_not_offered_message(level, mode_id, &session.available_modes())
2212 {
2213 return Err(message);
2214 }
2215
2216 let mut confirmation = session.subscribe();
2219 session
2220 .set_mode(mode_id.as_str())
2221 .await
2222 .map_err(|error| format!("session/set_mode to '{mode_id}' failed: {error}"))?;
2223
2224 let _ = tokio::time::timeout(ACP_MODE_CONFIRMATION_TIMEOUT, async {
2225 loop {
2226 match confirmation.recv().await {
2227 Ok(AgentEvent::ModeChanged { mode_id: changed }) if changed == mode_id.as_str() => {
2228 return;
2229 }
2230 Ok(_) => continue,
2231 Err(_) => return,
2232 }
2233 }
2234 })
2235 .await;
2236
2237 Ok(())
2238}
2239
2240fn validate_spawn_runtime_policy(
2241 policy: ProviderRuntimePolicy,
2242 transport: TransportKind,
2243 has_initial_prompt: bool,
2244 is_resume: bool,
2245) -> Result<(), String> {
2246 policy
2247 .validate()
2248 .map_err(|error| format!("provider runtime policy is invalid: {error}"))?;
2249 if transport != TransportKind::Acp {
2258 require_runtime_capability(policy, ProviderRuntimeCapability::RawPtyLifecycle)?;
2259 if transport != TransportKind::Pty {
2260 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2261 }
2262 if has_initial_prompt {
2263 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2264 require_runtime_capability(policy, ProviderRuntimeCapability::StructuredPrompt)?;
2265 }
2266 if is_resume && has_initial_prompt {
2267 require_runtime_capability(policy, ProviderRuntimeCapability::ProviderSessionIdentity)?;
2268 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticResume)?;
2269 }
2270 }
2271 Ok(())
2272}
2273
2274
2275fn is_codex_config_c_overlay_args(arguments: &[OsString]) -> bool {
2276 if arguments.is_empty() || arguments.len() % 2 != 0 {
2277 return false;
2278 }
2279 arguments.chunks_exact(2).all(|pair| {
2280 pair[0].as_os_str() == "-c"
2281 && pair[1]
2282 .to_str()
2283 .is_some_and(|value| !value.is_empty() && value.contains('=') && !value.contains('\0'))
2284 })
2285}
2286
2287fn validate_instance_launch_arguments(
2288 agent_id: &AgentId,
2289 transport: TransportKind,
2290 arguments: &[OsString],
2291) -> Result<(), String> {
2292 if arguments.is_empty() {
2293 return Ok(());
2294 }
2295 let acp_codex_c_overlay = transport == TransportKind::Acp
2296 && agent_id.as_str() == "codex"
2297 && is_codex_config_c_overlay_args(arguments);
2298 if transport != TransportKind::Pty && !acp_codex_c_overlay {
2299 return Err(
2300 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
2301 .to_owned(),
2302 );
2303 }
2304 if arguments.len() > INSTANCE_LAUNCH_ARGS_MAX {
2305 return Err("native instance launch argument count exceeds its bound".to_owned());
2306 }
2307 let mut total_bytes = 0usize;
2308 for argument in arguments {
2309 let argument = argument.to_string_lossy();
2310 if argument.contains('\0') {
2311 return Err("native instance launch argument is invalid".to_owned());
2312 }
2313 if argument.len() > INSTANCE_LAUNCH_ARG_MAX_BYTES {
2314 return Err("native instance launch argument exceeds its bound".to_owned());
2315 }
2316 total_bytes = total_bytes.saturating_add(argument.len());
2317 if total_bytes > INSTANCE_LAUNCH_ARGS_TOTAL_MAX_BYTES {
2318 return Err("native instance launch argument payload exceeds its bound".to_owned());
2319 }
2320 if agent_id.as_str() == "claude"
2321 && RESERVED_CLAUDE_LAUNCH_FLAGS.iter().any(|reserved| {
2322 argument == *reserved
2323 || (reserved.starts_with("--")
2324 && argument
2325 .strip_prefix(reserved)
2326 .is_some_and(|suffix| suffix.starts_with('=')))
2327 || (reserved.len() == 2
2328 && argument
2329 .strip_prefix(reserved)
2330 .is_some_and(|suffix| {
2331 !suffix.is_empty() && !suffix.starts_with('-')
2332 }))
2333 })
2334 {
2335 return Err(
2336 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
2337 .to_owned(),
2338 );
2339 }
2340 }
2341 Ok(())
2342}
2343
2344fn argument_looks_like_credential(value: &str) -> bool {
2357 const CREDENTIAL_PREFIXES: &[&str] = &["sk-", "sk_", "ghp_", "gho_", "ghs_", "xox", "bearer "];
2358 const CREDENTIAL_MARKERS: &[&str] = &[
2359 "apikey", "api_key", "api-key", "secret", "password", "passwd", "token=",
2360 ];
2361 let lower = value.to_ascii_lowercase();
2362 CREDENTIAL_PREFIXES
2363 .iter()
2364 .any(|prefix| lower.starts_with(prefix))
2365 || CREDENTIAL_MARKERS
2366 .iter()
2367 .any(|marker| lower.contains(marker))
2368 || has_prefixed_hex64_credential_shape(&lower)
2369}
2370
2371fn has_prefixed_hex64_credential_shape(lower: &str) -> bool {
2380 let Some((prefix, digest)) = lower.split_once('_') else {
2381 return false;
2382 };
2383 (2..=8).contains(&prefix.len())
2384 && prefix
2385 .bytes()
2386 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
2387 && digest.len() == 64
2388 && digest
2389 .bytes()
2390 .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
2391}
2392
2393fn redact_provider_argument(value: &OsStr) -> String {
2397 let text = value.to_string_lossy();
2398 if argument_looks_like_credential(&text) {
2399 "[redacted-credential-shaped-argument]".to_owned()
2400 } else {
2401 text.into_owned()
2402 }
2403}
2404
2405fn redact_provider_arguments(values: &[OsString]) -> Vec<String> {
2408 values.iter().map(|value| redact_provider_argument(value)).collect()
2409}
2410
2411fn require_runtime_capability(
2412 policy: ProviderRuntimePolicy,
2413 capability: ProviderRuntimeCapability,
2414) -> Result<(), String> {
2415 if policy.admits(capability) {
2416 Ok(())
2417 } else {
2418 Err(format!(
2419 "provider runtime capability {capability:?} is not admitted"
2420 ))
2421 }
2422}
2423
2424fn should_attach_pty_provider_stream(policy: ProviderRuntimePolicy) -> bool {
2425 policy.semantic_readiness || policy.provider_session_identity
2426}
2427
2428fn should_probe_pty_identity(
2429 policy: ProviderRuntimePolicy,
2430 adapter: Option<&gate4agent_types::AdapterBinding>,
2431 authoritative_identity_present: bool,
2432 expected_adapter: &str,
2433) -> bool {
2434 !authoritative_identity_present
2435 && policy.semantic_readiness
2436 && policy.structured_prompt
2437 && policy.provider_session_identity
2438 && adapter.is_some_and(|adapter| adapter.id.as_str() == expected_adapter)
2439}
2440
2441fn prepare_fresh_pty_provider_session(
2442 adapter: Option<&gate4agent_types::AdapterBinding>,
2443 is_resume: bool,
2444 identity_permitted: bool,
2445 launch_extra_args: &mut Vec<OsString>,
2446) -> Option<ProviderSessionIdentity> {
2447 let adapter = adapter?;
2448 if is_resume || !identity_permitted || adapter.id.as_str() != "claude-code" {
2449 return None;
2450 }
2451 let identity = ProviderSessionIdentity {
2452 key: ProviderSessionKey::SessionId,
2453 id: Uuid::new_v4().to_string(),
2454 transcript_path: None,
2455 };
2456 launch_extra_args.push(OsString::from("--session-id"));
2457 launch_extra_args.push(OsString::from(&identity.id));
2458 Some(identity)
2459}
2460
2461fn drain_pty_provider(
2462 key: NativeSessionKey,
2463 provider: &mut OwnedPtyProvider,
2464 observations: &mut Vec<ObservationEnvelope>,
2465) {
2466 while let Some(event) = provider.pending_events.pop_front() {
2467 push_provider_observation(key, provider, event, observations);
2468 }
2469
2470 loop {
2471 let envelope = match provider.replay.pop_front() {
2472 Some(envelope) => Some(envelope),
2473 None => provider.receiver.try_recv().unwrap_or_default(),
2474 };
2475 let Some(envelope) = envelope else {
2476 break;
2477 };
2478 match envelope.event {
2479 PtyEvent::Output(data) => {
2480 let raw = provider.utf8.push(&data);
2481 if raw.is_empty() {
2482 continue;
2483 }
2484 if provider.semantic_events {
2485 if let Some(info) = provider.rate_limits.detect(&raw) {
2486 push_provider_observation(
2487 key,
2488 provider,
2489 rate_limit_event(info),
2490 observations,
2491 );
2492 }
2493 }
2494 let identity = provider
2495 .kimi_identity
2496 .as_mut()
2497 .and_then(|extractor| extractor.push(&raw));
2498 if let Some(identity) = identity {
2499 if !provider.provider_session_started {
2500 push_provider_observation(
2501 key,
2502 provider,
2503 ProviderEvent::SessionStarted {
2504 session_id: identity.id.clone(),
2505 model: String::new(),
2506 tools: Vec::new(),
2507 },
2508 observations,
2509 );
2510 provider.provider_session_started = true;
2511 }
2512 push_provider_observation(
2513 key,
2514 provider,
2515 ProviderEvent::SessionIdentityObserved { identity },
2516 observations,
2517 );
2518 }
2519 if provider.semantic_events {
2520 let messages = provider
2521 .pipeline
2522 .get_mut()
2523 .unwrap_or_else(|poisoned| poisoned.into_inner())
2524 .process(&raw);
2525 for message in messages {
2526 if let Some(event) = parsed_provider_event(message) {
2527 push_provider_observation(key, provider, event, observations);
2528 }
2529 }
2530 }
2531 }
2532 PtyEvent::DataGap {
2533 from_sequence,
2534 to_sequence,
2535 ..
2536 } => {
2537 provider.utf8.clear();
2538 if let Some(extractor) = &mut provider.kimi_identity {
2539 extractor.reset_stream();
2540 }
2541 provider
2542 .pipeline
2543 .get_mut()
2544 .unwrap_or_else(|poisoned| poisoned.into_inner())
2545 .clear();
2546 let missed = to_sequence
2547 .checked_sub(from_sequence)
2548 .and_then(|difference| difference.checked_add(1));
2549 if let Some((source_sequence, missed)) = missed.and_then(|missed| {
2550 reserve_provider_gap_sequence(&mut provider.next_provider_sequence, missed)
2551 .map(|source_sequence| (source_sequence, missed))
2552 }) {
2553 observations.push(ObservationEnvelope {
2554 operation_id: None,
2555 instance_id: key.instance_id,
2556 generation: key.generation,
2557 observation: ControlObservation::ProviderGap {
2558 source: provider.source.clone(),
2559 source_sequence,
2560 missed,
2561 },
2562 });
2563 }
2564 }
2565 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
2566 push_provider_observation(
2567 key,
2568 provider,
2569 ProviderEvent::Error { message },
2570 observations,
2571 );
2572 }
2573 PtyEvent::Started
2574 | PtyEvent::Resized(_)
2575 | PtyEvent::ForegroundProcess(_)
2576 | PtyEvent::SnapshotAvailable { .. }
2577 | PtyEvent::Exited { .. } => {}
2578 }
2579 }
2580}
2581
2582fn push_provider_observation(
2583 key: NativeSessionKey,
2584 provider: &mut OwnedPtyProvider,
2585 event: ProviderEvent,
2586 observations: &mut Vec<ObservationEnvelope>,
2587) {
2588 let sequence = provider.next_provider_sequence;
2589 provider.next_provider_sequence = provider.next_provider_sequence.saturating_add(1);
2590 observations.push(ObservationEnvelope {
2591 operation_id: None,
2592 instance_id: key.instance_id,
2593 generation: key.generation,
2594 observation: ControlObservation::ProviderEvent {
2595 source: provider.source.clone(),
2596 sequence,
2597 event,
2598 },
2599 });
2600}
2601
2602fn reserve_provider_gap_sequence(next_sequence: &mut u64, missed: u64) -> Option<u64> {
2603 if missed == 0 {
2604 return None;
2605 }
2606 let Some(source_sequence) = missed
2607 .checked_sub(1)
2608 .and_then(|offset| next_sequence.checked_add(offset))
2609 else {
2610 *next_sequence = u64::MAX;
2611 return None;
2612 };
2613 let Some(next) = source_sequence.checked_add(1) else {
2614 *next_sequence = u64::MAX;
2615 return None;
2616 };
2617 *next_sequence = next;
2618 Some(source_sequence)
2619}
2620
2621fn parsed_provider_event(message: ParsedMessage) -> Option<ProviderEvent> {
2622 match message.class {
2623 MessageClass::AiResponse => Some(ProviderEvent::Text {
2624 text: message.content,
2625 is_delta: message.metadata.is_partial,
2626 }),
2627 MessageClass::ThinkingIndicator => Some(ProviderEvent::Thinking {
2628 text: message.content,
2629 }),
2630 MessageClass::Error => Some(ProviderEvent::Error {
2631 message: message.content,
2632 }),
2633 MessageClass::PromptReady => Some(ProviderEvent::Ready),
2634 MessageClass::ToolApproval => Some(ProviderEvent::InteractionRequested {
2635 request_id: None,
2636 interaction_kind: ProviderInteractionKind::Approval,
2637 tool_name: message
2638 .metadata
2639 .tool_name
2640 .unwrap_or_else(|| "unknown".to_owned()),
2641 title: None,
2645 prompt: message.content,
2646 options: Vec::new(),
2647 agent_id: None,
2648 }),
2649 MessageClass::InfoMessage
2650 | MessageClass::UiElement
2651 | MessageClass::UserEcho
2652 | MessageClass::Menu
2653 | MessageClass::Raw => None,
2654 }
2655}
2656
2657fn rate_limit_event(info: gate4agent::core::types::RateLimitInfo) -> ProviderEvent {
2658 ProviderEvent::RateLimited {
2659 limit_type: provider_rate_limit_kind(info.limit_type),
2660 resets_at: info.resets_at.map(|value| value.to_rfc3339()),
2661 usage_percent: info.usage_percent.map(|value| value.to_string()),
2662 raw_message: info.raw_message,
2663 }
2664}
2665
2666fn provider_host_request_decision(decision: HostRequestDecision) -> ProviderHostRequestDecision {
2673 match decision {
2674 HostRequestDecision::Granted { by } => {
2675 ProviderHostRequestDecision::Granted { by: provider_host_decision_authority(by) }
2676 }
2677 HostRequestDecision::Denied { by } => {
2678 ProviderHostRequestDecision::Denied { by: provider_host_decision_authority(by) }
2679 }
2680 HostRequestDecision::Deferred => ProviderHostRequestDecision::Deferred,
2681 }
2682}
2683
2684fn provider_host_decision_authority(by: HostDecisionAuthority) -> ProviderHostDecisionAuthority {
2685 match by {
2686 HostDecisionAuthority::Gate => ProviderHostDecisionAuthority::Gate,
2687 HostDecisionAuthority::Policy => ProviderHostDecisionAuthority::Policy,
2688 HostDecisionAuthority::Operator => ProviderHostDecisionAuthority::Operator,
2689 HostDecisionAuthority::DeadlinePolicy => ProviderHostDecisionAuthority::DeadlinePolicy,
2690 }
2691}
2692
2693fn provider_host_request_outcome(outcome: HostRequestOutcome) -> ProviderHostRequestOutcome {
2701 match outcome {
2702 HostRequestOutcome::Executed => ProviderHostRequestOutcome::Executed,
2703 HostRequestOutcome::Failed { error } => ProviderHostRequestOutcome::Failed { error },
2704 }
2705}
2706
2707fn provider_rate_limit_kind(
2711 limit_type: gate4agent::core::types::RateLimitType,
2712) -> ProviderRateLimitKind {
2713 use gate4agent::core::types::RateLimitType;
2714 match limit_type {
2715 RateLimitType::Session => ProviderRateLimitKind::Session,
2716 RateLimitType::Daily => ProviderRateLimitKind::Daily,
2717 RateLimitType::Weekly => ProviderRateLimitKind::Weekly,
2718 RateLimitType::Unknown => ProviderRateLimitKind::Unknown,
2719 }
2720}
2721
2722fn collect_provider_map<S>(
2728 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2729 observations: &mut Vec<ObservationEnvelope>,
2730 mode_catalogue: impl Fn(&S) -> Vec<SessionMode>,
2731) {
2732 for (key, owned) in sessions {
2733 let available_modes = mode_catalogue(&owned.session);
2734 drain_provider_stream(
2735 *key,
2736 &owned.source,
2737 &mut owned.events,
2738 &mut owned.pending_events,
2739 &mut owned.pending_provider_events,
2740 &mut owned.next_provider_sequence,
2741 Some(&mut owned.observed_exit_code),
2742 observations,
2743 &available_modes,
2744 );
2745 }
2746}
2747
2748fn push_sequenced_provider_event(
2755 key: NativeSessionKey,
2756 source: &ProviderSource,
2757 next_provider_sequence: &mut u64,
2758 observations: &mut Vec<ObservationEnvelope>,
2759 event: ProviderEvent,
2760) {
2761 let sequence = *next_provider_sequence;
2762 *next_provider_sequence = next_provider_sequence.saturating_add(1);
2763 observations.push(ObservationEnvelope {
2764 operation_id: None,
2765 instance_id: key.instance_id,
2766 generation: key.generation,
2767 observation: ControlObservation::ProviderEvent {
2768 source: source.clone(),
2769 sequence,
2770 event,
2771 },
2772 });
2773}
2774
2775fn drain_provider_stream(
2776 key: NativeSessionKey,
2777 source: &ProviderSource,
2778 events: &mut broadcast::Receiver<AgentEvent>,
2779 pending_events: &mut VecDeque<AgentEvent>,
2780 pending_provider_events: &mut VecDeque<ProviderEvent>,
2781 next_provider_sequence: &mut u64,
2782 mut observed_exit_code: Option<&mut Option<i32>>,
2783 observations: &mut Vec<ObservationEnvelope>,
2784 available_modes: &[SessionMode],
2785) {
2786 loop {
2787 if let Some(event) = pending_events.pop_front() {
2797 match event {
2798 AgentEvent::Exited { code } => {
2799 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2800 *exit_code = Some(code);
2801 }
2802 }
2803 event => {
2804 if let Some(event) = provider_event(event, available_modes) {
2805 push_sequenced_provider_event(
2806 key,
2807 source,
2808 next_provider_sequence,
2809 observations,
2810 event,
2811 );
2812 }
2813 }
2814 }
2815 continue;
2816 }
2817 if let Some(event) = pending_provider_events.pop_front() {
2818 push_sequenced_provider_event(key, source, next_provider_sequence, observations, event);
2819 continue;
2820 }
2821 match events.try_recv() {
2822 Ok(AgentEvent::Exited { code }) => {
2823 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2824 *exit_code = Some(code);
2825 }
2826 }
2827 Ok(event) => {
2828 if let Some(event) = provider_event(event, available_modes) {
2829 push_sequenced_provider_event(
2830 key,
2831 source,
2832 next_provider_sequence,
2833 observations,
2834 event,
2835 );
2836 }
2837 }
2838 Err(broadcast::error::TryRecvError::Lagged(missed)) => {
2839 if let Some(source_sequence) =
2840 reserve_provider_gap_sequence(next_provider_sequence, missed)
2841 {
2842 observations.push(ObservationEnvelope {
2843 operation_id: None,
2844 instance_id: key.instance_id,
2845 generation: key.generation,
2846 observation: ControlObservation::ProviderGap {
2847 source: source.clone(),
2848 source_sequence,
2849 missed,
2850 },
2851 });
2852 }
2853 }
2854 Err(broadcast::error::TryRecvError::Empty | broadcast::error::TryRecvError::Closed) => {
2855 break
2856 }
2857 }
2858 }
2859}
2860
2861fn collect_provider_exits<S>(
2862 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2863 observations: &mut Vec<ObservationEnvelope>,
2864 finished: impl Fn(&S) -> bool,
2865) {
2866 let completed: Vec<_> = sessions
2867 .iter()
2868 .filter_map(|(key, owned)| {
2869 (owned.observed_exit_code.is_some() || finished(&owned.session)).then_some(*key)
2870 })
2871 .collect();
2872 for key in completed {
2873 let owned = sessions
2874 .remove(&key)
2875 .expect("completed provider key came from the owned session map");
2876 observations.push(ObservationEnvelope {
2877 operation_id: None,
2878 instance_id: key.instance_id,
2879 generation: key.generation,
2880 observation: ControlObservation::ProcessExited {
2881 exit_code: owned.observed_exit_code,
2882 final_terminal: None,
2883 },
2884 });
2885 }
2886}
2887
2888const RPC_REQUEST_ID_NUMBER_PREFIX: &str = "number:";
2894const RPC_REQUEST_ID_STRING_PREFIX: &str = "string:";
2895
2896fn encode_rpc_request_id(id: &RpcId) -> String {
2908 match id {
2909 RpcId::Number(number) => format!("{RPC_REQUEST_ID_NUMBER_PREFIX}{number}"),
2910 RpcId::String(value) => format!("{RPC_REQUEST_ID_STRING_PREFIX}{value}"),
2911 }
2912}
2913
2914fn decode_rpc_request_id(raw: &str) -> Option<RpcId> {
2919 if let Some(number) = raw.strip_prefix(RPC_REQUEST_ID_NUMBER_PREFIX) {
2920 return number.parse::<u64>().ok().map(RpcId::Number);
2921 }
2922 raw.strip_prefix(RPC_REQUEST_ID_STRING_PREFIX)
2923 .map(|value| RpcId::String(value.to_owned()))
2924}
2925
2926fn resolve_acp_interaction_observation(
2939 session: Option<&AcpSession>,
2940 target: ProviderInteractionTarget,
2941 response: ProviderInteractionResponse,
2942) -> ControlObservation {
2943 let interaction_id = target.interaction_id;
2944 let fail = |message: String| ControlObservation::InteractionResolutionFailed {
2945 interaction_id,
2946 message,
2947 };
2948 let Some(session) = session else {
2949 return fail("semantic interaction resolution requires an ACP session".to_owned());
2950 };
2951 let Some(provider_request_id) = target.provider_request_id.as_deref() else {
2952 return fail("ACP interaction resolution requires a provider request id".to_owned());
2953 };
2954 let Some(id) = decode_rpc_request_id(provider_request_id) else {
2955 return fail(format!(
2956 "ACP interaction resolution request id {provider_request_id:?} is not a valid JSON-RPC id"
2957 ));
2958 };
2959 match resolve_acp_permission_interaction(session, &id, response) {
2960 Ok(()) => ControlObservation::InteractionResolutionCompleted { interaction_id },
2961 Err(message) => fail(message),
2962 }
2963}
2964
2965fn resolve_acp_permission_interaction(
2989 session: &AcpSession,
2990 id: &RpcId,
2991 response: ProviderInteractionResponse,
2992) -> Result<(), String> {
2993 let choice = match response {
2994 ProviderInteractionResponse::ApproveOnce => OperatorPermissionChoice::Approve,
2995 ProviderInteractionResponse::Deny => OperatorPermissionChoice::Reject,
2996 ProviderInteractionResponse::Answer { .. } => {
2997 return Err("ACP permission interactions do not accept free-text answers".to_owned())
2998 }
2999 };
3000 session.resolve_pending_request_as(id, choice).map_err(|error| error.to_string())
3001}
3002
3003async fn set_acp_session_mode_observation(
3016 session: Option<&AcpSession>,
3017 mode_id: String,
3018) -> ControlObservation {
3019 let Some(session) = session else {
3020 return ControlObservation::SessionModeSetFailed {
3021 message: "session mode switch requires an ACP session".to_owned(),
3022 };
3023 };
3024 let catalogue = session.available_modes();
3025 if catalogue.is_empty() {
3026 return ControlObservation::SessionModeSetFailed {
3027 message: "the provider announces no session-mode capability".to_owned(),
3028 };
3029 }
3030 if !catalogue.iter().any(|mode| mode.id == mode_id) {
3031 return ControlObservation::SessionModeSetFailed {
3032 message: format!("the provider never offered mode {mode_id:?}"),
3033 };
3034 }
3035 match session.set_mode(&mode_id).await {
3036 Ok(()) => ControlObservation::SessionModeSet { mode_id },
3037 Err(error) => ControlObservation::SessionModeSetFailed {
3038 message: error.to_string(),
3039 },
3040 }
3041}
3042
3043async fn set_acp_session_config_option_observation(
3059 session: Option<&AcpSession>,
3060 option_id: String,
3061 value_json: String,
3062) -> ControlObservation {
3063 let Some(session) = session else {
3064 return ControlObservation::SessionConfigOptionSetFailed {
3065 message: "session config-option switch requires an ACP session".to_owned(),
3066 };
3067 };
3068 let catalogue = session.config_options();
3069 if catalogue.is_empty() {
3070 return ControlObservation::SessionConfigOptionSetFailed {
3071 message: "the provider announces no session config-option capability".to_owned(),
3072 };
3073 }
3074 if !catalogue.iter().any(|option| option.id == option_id) {
3075 return ControlObservation::SessionConfigOptionSetFailed {
3076 message: format!("the provider never offered config option {option_id:?}"),
3077 };
3078 }
3079 let value = match value_json.parse() {
3080 Ok(value) => value,
3081 Err(error) => {
3082 return ControlObservation::SessionConfigOptionSetFailed {
3083 message: format!("session config option value is not valid JSON: {error}"),
3084 }
3085 }
3086 };
3087 match session.set_config_option(&option_id, value).await {
3088 Ok(()) => ControlObservation::SessionConfigOptionSet { option_id },
3089 Err(error) => ControlObservation::SessionConfigOptionSetFailed {
3090 message: error.to_string(),
3091 },
3092 }
3093}
3094
3095fn set_acp_session_model_observation(
3104 session: Option<&AcpSession>,
3105 model_id: String,
3106) -> ControlObservation {
3107 if session.is_none() {
3108 return ControlObservation::SessionModelSetFailed {
3109 message: "session model switch requires an ACP session".to_owned(),
3110 };
3111 }
3112 ControlObservation::SessionModelSetFailed {
3113 message: format!(
3114 "this provider offers no host-invocable model-switch method (requested model {model_id:?})"
3115 ),
3116 }
3117}
3118
3119fn map_provider_stop_reason(reason: StopReason) -> ProviderStopReason {
3132 match reason {
3133 StopReason::EndTurn => ProviderStopReason::EndTurn,
3134 StopReason::MaxTokens => ProviderStopReason::MaxTokens,
3135 StopReason::MaxTurnRequests => ProviderStopReason::MaxTurnRequests,
3136 StopReason::Refusal => ProviderStopReason::Refusal,
3137 StopReason::Cancelled => ProviderStopReason::Cancelled,
3138 StopReason::Other(value) => ProviderStopReason::Other { value },
3139 StopReason::ProviderError { code, message, vendor_code } => {
3140 ProviderStopReason::ProviderError { code, message, vendor_code }
3141 }
3142 }
3143}
3144
3145fn provider_event(event: AgentEvent, available_modes: &[SessionMode]) -> Option<ProviderEvent> {
3146 match event {
3147 AgentEvent::SessionStart {
3148 session_id,
3149 model,
3150 tools,
3151 } => Some(ProviderEvent::SessionStarted {
3152 session_id,
3153 model,
3154 tools,
3155 }),
3156 AgentEvent::Text { text, is_delta } => Some(ProviderEvent::Text { text, is_delta }),
3157 AgentEvent::Thinking { text } => Some(ProviderEvent::Thinking { text }),
3158 AgentEvent::ToolStart { id, name, input } => Some(ProviderEvent::ToolStarted {
3159 id,
3160 name,
3161 input_json: input.to_string(),
3162 agent_id: None,
3163 }),
3164 AgentEvent::ToolResult {
3165 id,
3166 output,
3167 is_error,
3168 duration_ms,
3169 non_execution_kind,
3170 } => Some(ProviderEvent::ToolCompleted {
3171 id,
3172 output,
3173 is_error,
3174 duration_ms,
3175 agent_id: None,
3176 non_execution_kind,
3177 }),
3178 AgentEvent::TurnComplete {
3179 input_tokens,
3180 output_tokens,
3181 cache_read_tokens,
3182 cache_write_tokens,
3183 reasoning_tokens,
3184 context_window,
3185 is_cumulative,
3186 } => Some(ProviderEvent::TurnCompleted {
3187 usage: TokenUsage {
3188 input_tokens,
3189 output_tokens,
3190 cache_read_tokens,
3191 cache_write_tokens,
3192 reasoning_tokens,
3193 context_window,
3194 },
3195 is_cumulative,
3196 }),
3197 AgentEvent::ContextWindowUsage { usage } => {
3198 Some(ProviderEvent::ContextWindowUsage {
3199 usage: ProviderContextWindowUsage {
3200 uncached_input_tokens: usage.uncached_input_tokens,
3201 cache_read_tokens: usage.cache_read_tokens,
3202 cache_write_tokens: usage.cache_write_tokens,
3203 output_tokens: usage.output_tokens,
3204 unattributed_tokens: usage.unattributed_tokens,
3205 used_tokens: usage.used_tokens,
3206 capacity_tokens: usage.capacity_tokens,
3207 },
3208 })
3209 }
3210 AgentEvent::SessionEnd {
3211 result,
3212 cost_usd,
3213 is_error,
3214 stop_reason,
3215 } => Some(ProviderEvent::SessionEnded {
3216 result,
3217 cost_usd: cost_usd.map(|cost| cost.to_string()),
3218 is_error,
3219 stop_reason: stop_reason.map(map_provider_stop_reason),
3220 }),
3221 AgentEvent::Error { message } => Some(ProviderEvent::Error { message }),
3222 AgentEvent::TurnInterrupted { reason } => {
3232 tracing::warn!(reason = %reason, "acp turn interrupted");
3233 Some(ProviderEvent::TurnInterrupted)
3234 }
3235 AgentEvent::PtyParsed(message) => parsed_provider_event(message),
3236 AgentEvent::PtyReady => Some(ProviderEvent::Ready),
3237 AgentEvent::PtyToolApproval {
3238 tool_name,
3239 description,
3240 } => Some(ProviderEvent::InteractionRequested {
3241 request_id: None,
3242 interaction_kind: ProviderInteractionKind::Approval,
3243 tool_name,
3244 title: None,
3248 prompt: description.unwrap_or_default(),
3249 options: Vec::new(),
3250 agent_id: None,
3251 }),
3252 AgentEvent::RateLimit(info) => Some(rate_limit_event(info)),
3253 AgentEvent::RpcIncomingRequest {
3267 id,
3268 method,
3269 params,
3270 decision,
3271 reason: _,
3275 outcome: _,
3279 } if method == "session/request_permission"
3280 && matches!(decision, HostRequestDecision::Deferred) =>
3281 {
3282 let tool_call = params.as_ref().and_then(|params| params.get("toolCall"));
3283 let field = |name: &str| {
3284 tool_call
3285 .and_then(|tool_call| tool_call.get(name))
3286 .and_then(|value| value.as_str())
3287 .filter(|value| !value.is_empty())
3288 .map(str::to_owned)
3289 };
3290 let title = field("title");
3299 let options: Vec<ProviderInteractionOption> = params
3311 .as_ref()
3312 .and_then(|params| params.get("options"))
3313 .and_then(|options| options.as_array())
3314 .map(|options| {
3315 options
3316 .iter()
3317 .filter_map(|option| {
3318 let option_id = option.get("optionId")?.as_str()?.to_owned();
3319 let name = option.get("name")?.as_str()?.to_owned();
3320 let kind = option.get("kind")?.as_str()?.to_owned();
3321 Some(ProviderInteractionOption { option_id, name, kind })
3322 })
3323 .collect()
3324 })
3325 .unwrap_or_default();
3326 Some(ProviderEvent::InteractionRequested {
3327 request_id: Some(encode_rpc_request_id(&id)),
3328 interaction_kind: ProviderInteractionKind::Approval,
3329 tool_name: field("kind").unwrap_or(method),
3330 title,
3331 prompt: field("title").unwrap_or_default(),
3332 options,
3333 agent_id: None,
3334 })
3335 }
3336 AgentEvent::RpcIncomingRequest {
3337 id: _,
3338 method,
3339 params,
3340 decision,
3341 outcome,
3350 reason,
3351 } => Some(ProviderEvent::HostRequestObserved {
3352 method,
3353 params_json: params.map(|value| value.to_string()).unwrap_or_default(),
3354 decision: provider_host_request_decision(decision),
3355 outcome: provider_host_request_outcome(outcome),
3356 reason,
3357 }),
3358 AgentEvent::RpcNotification { method, params } => {
3359 Some(ProviderEvent::UnrecognizedNotification {
3360 method,
3361 payload_json: params.to_string(),
3362 })
3363 }
3364 AgentEvent::Started { .. } | AgentEvent::Exited { .. } | AgentEvent::PtyRaw { .. } => None,
3365 AgentEvent::UserMessage { text, is_delta } => {
3366 Some(ProviderEvent::UserMessage { text, is_delta })
3367 }
3368 AgentEvent::Plan { steps } => Some(ProviderEvent::Plan {
3369 steps: steps.into_iter().map(provider_plan_step).collect(),
3370 }),
3371 AgentEvent::AvailableCommandsUpdate { commands } => {
3372 Some(ProviderEvent::AvailableCommandsUpdated {
3373 commands: commands
3374 .into_iter()
3375 .map(|command| ProviderAvailableCommand {
3376 name: command.name,
3377 description: command.description,
3378 input_hint: command.input_hint,
3379 })
3380 .collect(),
3381 })
3382 }
3383 AgentEvent::ModeChanged { mode_id } => Some(ProviderEvent::ModeChanged {
3384 mode_id,
3385 available: available_modes.iter().cloned().map(provider_mode_info).collect(),
3386 }),
3387 AgentEvent::SessionInfoUpdate { title } => {
3388 Some(ProviderEvent::SessionInfoUpdated { title })
3389 }
3390 AgentEvent::UsageUpdate {
3391 used_tokens,
3392 context_window,
3393 cost_amount,
3394 cost_currency,
3395 } => Some(ProviderEvent::UsageUpdated {
3396 used_tokens,
3397 context_window,
3398 cost_amount: cost_amount.map(|amount| amount.to_string()),
3399 cost_currency,
3400 }),
3401 AgentEvent::ConfigOptionsUpdate { options } => Some(ProviderEvent::ConfigOptionsUpdated {
3402 options: options.into_iter().map(provider_config_option).collect(),
3403 }),
3404 AgentEvent::ModelsUpdate { .. }
3411 | AgentEvent::ProviderModelChanged { .. }
3412 | AgentEvent::SettingsUpdate { .. }
3413 | AgentEvent::HookExecutionUpdate { .. }
3414 | AgentEvent::McpServersUpdate { .. }
3415 | AgentEvent::McpInitProgress { .. }
3416 | AgentEvent::McpInitialized { .. }
3417 | AgentEvent::AnnouncementsUpdate { .. } => None,
3418 }
3419}
3420
3421fn provider_plan_priority(priority: gate4agent::core::types::PlanStepPriority) -> ProviderPlanPriority {
3425 use gate4agent::core::types::PlanStepPriority;
3426 match priority {
3427 PlanStepPriority::High => ProviderPlanPriority::High,
3428 PlanStepPriority::Medium => ProviderPlanPriority::Medium,
3429 PlanStepPriority::Low => ProviderPlanPriority::Low,
3430 }
3431}
3432
3433fn provider_plan_status(status: gate4agent::core::types::PlanStepStatus) -> ProviderPlanStatus {
3435 use gate4agent::core::types::PlanStepStatus;
3436 match status {
3437 PlanStepStatus::Pending => ProviderPlanStatus::Pending,
3438 PlanStepStatus::InProgress => ProviderPlanStatus::InProgress,
3439 PlanStepStatus::Completed => ProviderPlanStatus::Completed,
3440 }
3441}
3442
3443fn provider_plan_step(step: gate4agent::core::types::PlanStep) -> ProviderPlanStep {
3444 ProviderPlanStep {
3445 content: step.content,
3446 priority: provider_plan_priority(step.priority),
3447 status: provider_plan_status(step.status),
3448 }
3449}
3450
3451fn provider_mode_info(mode: SessionMode) -> ProviderModeInfo {
3455 ProviderModeInfo {
3456 id: mode.id,
3457 name: mode.name,
3458 description: mode.description,
3459 }
3460}
3461
3462fn provider_config_option_kind(
3465 kind: gate4agent::core::types::ConfigOptionKind,
3466) -> ProviderConfigOptionKind {
3467 use gate4agent::core::types::ConfigOptionKind;
3468 match kind {
3469 ConfigOptionKind::Select => ProviderConfigOptionKind::Select,
3470 ConfigOptionKind::Boolean => ProviderConfigOptionKind::Boolean,
3471 ConfigOptionKind::Unknown => ProviderConfigOptionKind::Unknown,
3472 }
3473}
3474
3475fn provider_config_option(option: gate4agent::core::types::ConfigOptionInfo) -> ProviderConfigOption {
3481 ProviderConfigOption {
3482 id: option.id,
3483 name: option.name,
3484 description: option.description,
3485 category: option.category,
3486 kind: provider_config_option_kind(option.kind),
3487 value_json: option.value.to_string(),
3488 choices: option
3489 .choices
3490 .into_iter()
3491 .map(|choice| ProviderConfigChoice {
3492 value_json: choice.value.to_string(),
3493 label: choice.label,
3494 })
3495 .collect(),
3496 }
3497}
3498
3499fn builtin_legacy_adapter_runtimes() -> AdapterRuntimeRegistry<CliTool> {
3500 let definitions = [
3506 ("claude-code", CliTool::ClaudeCode),
3507 ("codex", CliTool::Codex),
3508 ("kimi", CliTool::KimiCode),
3509 ("grok", CliTool::Grok),
3510 ("opencode", CliTool::Opencode),
3511 ("mcode", CliTool::Mcode),
3512 ];
3513 let mut runtimes = AdapterRuntimeRegistry::default();
3514 for (id, tool) in definitions {
3515 for family in [
3516 AdapterFamily::PtySemantic,
3517 AdapterFamily::Pipe,
3518 AdapterFamily::Acp,
3519 ] {
3520 let Some(binding) = builtin_adapter_registry().binding(family, id) else {
3521 continue;
3522 };
3523 runtimes
3524 .insert(family, binding.clone(), tool)
3525 .expect("built-in native adapter runtime must be unique");
3526 }
3527 }
3528
3529 runtimes
3530}
3531
3532fn terminal_frame(snapshot: PtyTerminalSnapshot, screen_state: PtyScreenState) -> TerminalFrame {
3533 TerminalFrame {
3534 sequence: snapshot.sequence,
3535 size: TerminalSize {
3536 rows: snapshot.size.rows,
3537 columns: snapshot.size.cols,
3538 },
3539 cursor_row: snapshot.cursor.0,
3540 cursor_column: snapshot.cursor.1,
3541 contents: snapshot.contents,
3542 formatted: snapshot.formatted,
3543 scrollback_formatted: snapshot.scrollback_formatted,
3544 alternate_screen: snapshot.alternate_screen,
3545 mouse_protocol_enabled: snapshot.mouse_protocol_enabled,
3546 mouse_protocol_encoding: match snapshot.mouse_protocol_encoding {
3547 PtyMouseProtocolEncoding::Default => TerminalMouseProtocolEncoding::Default,
3548 PtyMouseProtocolEncoding::Utf8 => TerminalMouseProtocolEncoding::Utf8,
3549 PtyMouseProtocolEncoding::Sgr => TerminalMouseProtocolEncoding::Sgr,
3550 },
3551 produced_at_unix_ms: snapshot.produced_at_unix_ms,
3554 screen_state,
3555 bracketed_paste: Some(snapshot.bracketed_paste),
3560 }
3561}
3562
3563fn terminal_state_capture_should_skip<E>(sequence: Result<u64, E>, last_captured: u64) -> bool {
3571 matches!(sequence, Ok(sequence) if sequence <= last_captured)
3572}
3573
3574fn terminal_frame_byte_len(frame: &TerminalFrame) -> u64 {
3580 let scrollback_bytes: usize = frame.scrollback_formatted.iter().map(Vec::len).sum();
3581 (frame.formatted.len() + scrollback_bytes) as u64
3582}
3583
3584fn canonical_foreground(
3585 agent_id: AgentId,
3586 observation: &PtyForegroundObservation,
3587) -> ForegroundProcess {
3588 let kind = if observation.readiness.process_name.as_deref() == Some(agent_id.as_str()) {
3589 ForegroundProcessKind::Agent { agent_id }
3590 } else if observation.readiness.is_shell {
3591 ForegroundProcessKind::Shell
3592 } else {
3593 ForegroundProcessKind::Other
3594 };
3595 ForegroundProcess {
3596 root_process_id: observation.root_pid,
3597 process_id: observation.observed_pid,
3598 process_name: observation.observed_process.clone(),
3599 kind,
3600 }
3601}
3602
3603fn completion_observation(
3604 operation_id: OperationId,
3605 instance_id: AgentInstanceId,
3606 generation: SessionGeneration,
3607 observation: ControlObservation,
3608) -> ObservationEnvelope {
3609 ObservationEnvelope {
3610 operation_id: Some(operation_id),
3611 instance_id,
3612 generation,
3613 observation,
3614 }
3615}
3616
3617async fn wait_for_readiness(
3618 session: &PtySession,
3619 spec: &AgentSpec,
3620 intent: ReadinessIntent,
3621 detect_startup_gates: bool,
3622) -> Result<ReadinessPermit, String> {
3623 let started = Instant::now();
3624 let (terminal, attachment) = attach_readiness_boundary(session)?;
3625 let mut receiver = attachment.receiver;
3626 let mut tracker = ReadinessTracker::new(spec, RuntimePlatform::current(), intent);
3627 let mut diagnostics = ReadinessDiagnostics {
3628 draft_signal: Some(spec.readiness.draft_signal),
3629 ..ReadinessDiagnostics::default()
3630 };
3631 seed_readiness_from_terminal(
3632 &terminal,
3633 &mut tracker,
3634 &mut diagnostics,
3635 elapsed_ms(started),
3636 )?;
3637 let interval = Duration::from_millis(spec.readiness.poll_interval_ms.max(1));
3638 let mut next_probe = Instant::now();
3639
3640 for event in attachment.replay {
3641 observe_readiness_event(
3642 &mut tracker,
3643 &mut diagnostics,
3644 event.event,
3645 elapsed_ms(started),
3646 )?;
3647 if detect_startup_gates {
3648 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3649 ensure_no_startup_operator_gate(session, spec)?;
3650 }
3651 }
3652
3653 loop {
3654 if detect_startup_gates {
3655 ensure_no_startup_operator_gate(session, spec)?;
3656 }
3657 if Instant::now() >= next_probe {
3658 let foreground = session
3659 .observe_foreground()
3660 .await
3661 .map_err(|error| error.to_string())?;
3662 diagnostics.observe_foreground(&foreground.readiness);
3663 tracker.observe_foreground(&foreground.readiness, elapsed_ms(started));
3664 next_probe = Instant::now() + interval;
3665 }
3666 tracker.poll(elapsed_ms(started));
3667 if readiness_complete(tracker.status(), &diagnostics)? {
3668 if detect_startup_gates {
3669 ensure_no_startup_operator_gate(session, spec)?;
3670 }
3671 return tracker
3672 .into_permit()
3673 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3674 }
3675
3676 let wait = next_probe.saturating_duration_since(Instant::now());
3677 match tokio::time::timeout(wait, receiver.recv()).await {
3678 Ok(Ok(event)) => {
3679 if matches!(&event.event, PtyEvent::DataGap { .. }) {
3680 let (terminal, attachment) = attach_readiness_boundary(session)?;
3681 receiver = attachment.receiver;
3682 tracker = ReadinessTracker::new(
3683 spec,
3684 RuntimePlatform::current(),
3685 intent,
3686 );
3687 diagnostics = ReadinessDiagnostics {
3688 draft_signal: Some(spec.readiness.draft_signal),
3689 ..ReadinessDiagnostics::default()
3690 };
3691 seed_readiness_from_terminal(
3692 &terminal,
3693 &mut tracker,
3694 &mut diagnostics,
3695 elapsed_ms(started),
3696 )?;
3697 for retained in attachment.replay {
3698 observe_readiness_event(
3699 &mut tracker,
3700 &mut diagnostics,
3701 retained.event,
3702 elapsed_ms(started),
3703 )?;
3704 }
3705 } else {
3706 observe_readiness_event(
3707 &mut tracker,
3708 &mut diagnostics,
3709 event.event,
3710 elapsed_ms(started),
3711 )?;
3712 }
3713 if detect_startup_gates {
3714 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3715 ensure_no_startup_operator_gate(session, spec)?;
3716 }
3717 }
3718 Ok(Err(error)) => return Err(error.to_string()),
3719 Err(_) => {
3720 tracker.poll(elapsed_ms(started));
3721 }
3722 }
3723 if readiness_complete(tracker.status(), &diagnostics)? {
3724 if detect_startup_gates {
3725 ensure_no_startup_operator_gate(session, spec)?;
3726 }
3727 return tracker
3728 .into_permit()
3729 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3730 }
3731 }
3732}
3733
3734fn attach_readiness_boundary(
3735 session: &PtySession,
3736) -> Result<(PtyTerminalSnapshot, PtyAttachment), String> {
3737 let terminal = session.terminal_state().map_err(|error| error.to_string())?;
3738 let cursor = PtyReplayCursor {
3739 provider_revision: terminal.provider_revision.clone(),
3740 generation: terminal.generation,
3741 next_sequence: terminal.sequence.saturating_add(1).max(1),
3742 };
3743 let attachment = session
3744 .attach_events(cursor)
3745 .map_err(|error| error.to_string())?;
3746 Ok((terminal, attachment))
3747}
3748
3749fn seed_readiness_from_terminal(
3750 terminal: &PtyTerminalSnapshot,
3751 tracker: &mut ReadinessTracker<'_>,
3752 diagnostics: &mut ReadinessDiagnostics,
3753 elapsed_ms: u64,
3754) -> Result<(), String> {
3755 const ENABLE_BRACKETED_PASTE: &[u8] = b"\x1b[?2004h";
3756 if terminal.bracketed_paste {
3757 diagnostics.observe_output(ENABLE_BRACKETED_PASTE);
3758 tracker.observe_output(ENABLE_BRACKETED_PASTE, elapsed_ms);
3759 }
3760 if !terminal.formatted.is_empty() {
3761 diagnostics.observe_output(&terminal.formatted);
3762 tracker.observe_output(&terminal.formatted, elapsed_ms);
3763 }
3764 Ok(())
3765}
3766
3767const STARTUP_GATE_SETTLE_MS: u64 = 350;
3768const STARTUP_GATE_POLL_MS: u64 = 25;
3769const FOREGROUND_RECLASSIFY_INTERVAL: Duration = Duration::from_secs(1);
3783const CODEX_PASTE_ENTER_SUPPRESSION_MS: u64 = 120;
3787const CODEX_POST_RENDER_MARGIN_MS: u64 = 30;
3788const CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3789const KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3790
3791async fn probe_fresh_codex_session_identity(
3792 session: &PtySession,
3793 spec: &AgentSpec,
3794) -> Result<Option<ProviderSessionIdentity>, String> {
3795 let permit = match wait_for_readiness(session, spec, ReadinessIntent::DraftPaste, true).await {
3796 Ok(permit) => permit,
3797 Err(_) => return Ok(None),
3798 };
3799 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3800 return Ok(None);
3801 }
3802 let baseline = session
3803 .terminal_state()
3804 .map_err(|error| error.to_string())?;
3805 let mut extractor = CodexPtySessionIdentityExtractor::default();
3806 session
3807 .send_input_action(
3808 InputAction::AgentCommand(AgentCommand {
3809 agent_id: spec.id.clone(),
3810 name: "status".to_owned(),
3811 arguments: Vec::new(),
3812 }),
3813 permit,
3814 )
3815 .await
3816 .map_err(|error| format!("Codex /status identity probe failed: {error}"))?;
3817
3818 let deadline = Instant::now()
3819 + Duration::from_millis(
3820 spec.readiness
3821 .timeout_ms
3822 .min(CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS)
3823 .max(1),
3824 );
3825 loop {
3826 let snapshot = session
3827 .terminal_state()
3828 .map_err(|error| error.to_string())?;
3829 if snapshot.sequence > baseline.sequence {
3830 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3831 return Ok(Some(identity));
3832 }
3833 }
3834 if Instant::now() >= deadline {
3835 return Ok(None);
3836 }
3837 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3838 }
3839}
3840
3841async fn probe_fresh_kimi_session_identity(
3842 session: &PtySession,
3843 spec: &AgentSpec,
3844) -> Result<Option<ProviderSessionIdentity>, String> {
3845 let permit = match wait_for_readiness(
3846 session,
3847 spec,
3848 ReadinessIntent::FollowupPrompt,
3849 true,
3850 )
3851 .await
3852 {
3853 Ok(permit) => permit,
3854 Err(_) => return Ok(None),
3855 };
3856 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3857 return Ok(None);
3858 }
3859 let baseline = session
3860 .terminal_state()
3861 .map_err(|error| error.to_string())?;
3862 let mut extractor = KimiPtySessionIdentityExtractor::default();
3863 if let Some(identity) = extractor.observe_screen(&baseline.contents) {
3864 return Ok(Some(identity));
3865 }
3866 session
3867 .send_input_action(
3868 InputAction::SubmitPrompt(PromptPayload {
3869 text: "/status".to_owned(),
3870 framing: PromptFraming::BracketedPaste,
3871 }),
3872 permit,
3873 )
3874 .await
3875 .map_err(|error| format!("Kimi /status identity probe failed: {error}"))?;
3876
3877 let deadline = Instant::now()
3878 + Duration::from_millis(
3879 spec.readiness
3880 .timeout_ms
3881 .min(KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS)
3882 .max(1),
3883 );
3884 loop {
3885 let snapshot = session
3886 .terminal_state()
3887 .map_err(|error| error.to_string())?;
3888 if snapshot.sequence > baseline.sequence {
3889 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3890 return Ok(Some(identity));
3891 }
3892 }
3893 if Instant::now() >= deadline {
3894 return Ok(None);
3895 }
3896 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3897 }
3898}
3899
3900async fn deliver_pending_initial_prompt(
3901 session: &mut PtySession,
3902 spec: &AgentSpec,
3903) -> Result<(), String> {
3904 if session.pending_followup_prompt().is_none() {
3905 return Ok(());
3906 }
3907 let mut permit =
3908 wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3909 wait_for_startup_operator_gate(session, spec).await?;
3910 let render_confirmed_submit = spec.id.as_str() == "claude"
3911 || (RuntimePlatform::current() == RuntimePlatform::Windows
3912 && spec.id.as_str() == "codex");
3913 if render_confirmed_submit {
3914 let prompt = session
3915 .pending_followup_prompt()
3916 .ok_or_else(|| "deferred initial prompt disappeared before paste".to_owned())?
3917 .to_owned();
3918 let baseline = session
3919 .terminal_state()
3920 .map_err(|error| error.to_string())?;
3921 let inserted = session
3922 .insert_pending_followup_prompt(PromptFraming::BracketedPaste, &permit)
3923 .await
3924 .map_err(|error| error.to_string())?;
3925 if !inserted {
3926 return Err("deferred initial prompt was not inserted".to_owned());
3927 }
3928 wait_for_prompt_render(
3929 session,
3930 spec,
3931 &prompt,
3932 &baseline,
3933 spec.readiness.timeout_ms,
3934 )
3935 .await?;
3936 if RuntimePlatform::current() == RuntimePlatform::Windows && spec.id.as_str() == "codex" {
3937 tokio::time::sleep(Duration::from_millis(
3938 CODEX_PASTE_ENTER_SUPPRESSION_MS + CODEX_POST_RENDER_MARGIN_MS,
3939 ))
3940 .await;
3941 }
3942 permit = wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3943 wait_for_startup_operator_gate(session, spec).await?;
3944 }
3945 ensure_no_startup_operator_gate(session, spec)?;
3946 let submitted = session
3947 .submit_pending_followup(PromptFraming::BracketedPaste, permit)
3948 .await
3949 .map_err(|error| error.to_string())?;
3950 if !submitted {
3951 return Err("deferred initial prompt disappeared before delivery".to_owned());
3952 }
3953 Ok(())
3954}
3955
3956async fn wait_for_prompt_render(
3957 session: &PtySession,
3958 spec: &AgentSpec,
3959 prompt: &str,
3960 baseline: &PtyTerminalSnapshot,
3961 timeout_ms: u64,
3962) -> Result<(), String> {
3963 let probe = prompt_render_probe(&gate4agent_types::sanitize_prompt_text(prompt));
3964 let deadline = Instant::now() + Duration::from_millis(timeout_ms.max(1));
3965 loop {
3966 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
3967 if let Some(gate) = startup_operator_gate(&snapshot.contents) {
3968 return Err(startup_operator_error(spec, &gate));
3969 }
3970 if prompt_rendered(&snapshot, baseline, &probe) {
3971 return Ok(());
3972 }
3973 if Instant::now() >= deadline {
3974 let tail = terminal_tail(&snapshot.contents);
3975 let compact_tail = compact_alphanumeric(&tail);
3976 let baseline_tail = terminal_tail(&baseline.contents).to_ascii_lowercase();
3977 let normalized_tail = tail.to_ascii_lowercase();
3978 let retained = render_ack_event_summary(session, baseline.sequence);
3979 let foreground = session.observe_foreground().await.ok();
3980 let foreground_name = foreground
3981 .as_ref()
3982 .and_then(|observation| observation.readiness.process_name.as_deref())
3983 .map(safe_process_label)
3984 .unwrap_or_else(|| "none".to_owned());
3985 let child_live = retained.exit_code.is_none() && foreground.is_some();
3986 return Err(format!(
3987 "agent '{}' initial prompt paste was not rendered before submit; Enter was not sent (baseline_sequence={} current_sequence={} sequence_delta={} cursor_changed={} bracketed_baseline={} bracketed_current={} tail_chars={} probe_chars={} probe_match={} placeholder_baseline={} placeholder_current={} child_live={} foreground={} retained_output={} retained_foreground={} retained_snapshots={} retained_resized={} retained_gaps={} retained_reader_errors={} retained_operator_actions={} retained_exit_code={} output_flags={})",
3988 spec.id,
3989 baseline.sequence,
3990 snapshot.sequence,
3991 snapshot.sequence.saturating_sub(baseline.sequence),
3992 snapshot.cursor != baseline.cursor,
3993 baseline.bracketed_paste,
3994 snapshot.bracketed_paste,
3995 tail.chars().count(),
3996 probe.chars().count(),
3997 !probe.is_empty() && compact_tail.contains(&probe),
3998 paste_placeholder_visible(&baseline_tail),
3999 paste_placeholder_visible(&normalized_tail),
4000 child_live,
4001 foreground_name,
4002 retained.output,
4003 retained.foreground,
4004 retained.snapshots,
4005 retained.resized,
4006 retained.gaps,
4007 retained.reader_errors,
4008 retained.operator_actions,
4009 retained
4010 .exit_code
4011 .map_or_else(|| "none".to_owned(), |code| code.to_string()),
4012 if retained.output_flags.is_empty() {
4013 "none".to_owned()
4014 } else {
4015 retained.output_flags.join(",")
4016 },
4017 ));
4018 }
4019 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
4020 }
4021}
4022
4023#[derive(Default)]
4024struct RenderAckEventSummary {
4025 output: usize,
4026 foreground: usize,
4027 snapshots: usize,
4028 resized: usize,
4029 gaps: usize,
4030 reader_errors: usize,
4031 operator_actions: usize,
4032 exit_code: Option<i32>,
4033 output_flags: Vec<&'static str>,
4034}
4035
4036fn render_ack_event_summary(session: &PtySession, baseline_sequence: u64) -> RenderAckEventSummary {
4037 let mut summary = RenderAckEventSummary::default();
4038 let Ok(attachment) = session.attach_retained_events() else {
4039 return summary;
4040 };
4041 for envelope in attachment
4042 .replay
4043 .into_iter()
4044 .filter(|envelope| envelope.sequence > baseline_sequence)
4045 {
4046 match envelope.event {
4047 PtyEvent::Output(bytes) => {
4048 summary.output = summary.output.saturating_add(1);
4049 observe_render_ack_output_flags(&mut summary.output_flags, &bytes);
4050 }
4051 PtyEvent::ForegroundProcess(_) => {
4052 summary.foreground = summary.foreground.saturating_add(1);
4053 }
4054 PtyEvent::SnapshotAvailable { .. } => {
4055 summary.snapshots = summary.snapshots.saturating_add(1);
4056 }
4057 PtyEvent::Resized(_) => {
4058 summary.resized = summary.resized.saturating_add(1);
4059 }
4060 PtyEvent::DataGap { .. } => {
4061 summary.gaps = summary.gaps.saturating_add(1);
4062 }
4063 PtyEvent::ReaderError { .. } => {
4064 summary.reader_errors = summary.reader_errors.saturating_add(1);
4065 }
4066 PtyEvent::OperatorActionRequired { .. } => {
4067 summary.operator_actions = summary.operator_actions.saturating_add(1);
4068 }
4069 PtyEvent::Exited { code } => summary.exit_code = Some(code),
4070 PtyEvent::Started => {}
4071 }
4072 }
4073 summary
4074}
4075
4076fn observe_render_ack_output_flags(flags: &mut Vec<&'static str>, bytes: &[u8]) {
4077 let normalized = String::from_utf8_lossy(bytes).to_ascii_lowercase();
4078 for (label, marker) in [
4079 ("error", "error"),
4080 ("panic", "panic"),
4081 ("fatal", "fatal"),
4082 ("login", "login"),
4083 ("auth", "auth"),
4084 ("permission", "permission"),
4085 ("rate-limit", "rate limit"),
4086 ("usage-limit", "usage limit"),
4087 ("update", "update"),
4088 ("working", "working"),
4089 ("thinking", "thinking"),
4090 ] {
4091 if normalized.contains(marker) && !flags.contains(&label) {
4092 flags.push(label);
4093 }
4094 }
4095}
4096
4097fn safe_process_label(process_name: &str) -> String {
4098 process_name
4099 .chars()
4100 .take(64)
4101 .map(|character| {
4102 if character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | '-') {
4103 character
4104 } else {
4105 '?'
4106 }
4107 })
4108 .collect()
4109}
4110
4111fn prompt_rendered(
4112 snapshot: &PtyTerminalSnapshot,
4113 baseline: &PtyTerminalSnapshot,
4114 probe: &str,
4115) -> bool {
4116 if snapshot.sequence <= baseline.sequence {
4117 return false;
4118 }
4119 let tail = terminal_tail(&snapshot.contents);
4120 let compact = compact_alphanumeric(&tail);
4121 if !probe.is_empty() && compact.contains(probe) {
4122 return true;
4123 }
4124 let normalized_tail = tail.to_ascii_lowercase();
4125 let normalized_baseline = terminal_tail(&baseline.contents).to_ascii_lowercase();
4126 paste_placeholder_visible(&normalized_tail)
4127 && !paste_placeholder_visible(&normalized_baseline)
4128}
4129
4130fn paste_placeholder_visible(normalized_tail: &str) -> bool {
4131 normalized_tail.contains("[pasted content")
4135 || normalized_tail.contains("[pasted text #")
4136}
4137
4138fn terminal_tail(contents: &str) -> String {
4139 let mut lines = contents.lines().rev().take(12).collect::<Vec<_>>();
4140 lines.reverse();
4141 lines.join("\n")
4142}
4143
4144fn prompt_render_probe(prompt: &str) -> String {
4145 let compact = compact_alphanumeric(prompt);
4146 let chars = compact.chars().collect::<Vec<_>>();
4147 chars[chars.len().saturating_sub(32)..].iter().collect()
4148}
4149
4150fn compact_alphanumeric(value: &str) -> String {
4151 value
4152 .chars()
4153 .filter(|character| character.is_alphanumeric())
4154 .flat_map(char::to_lowercase)
4155 .collect()
4156}
4157
4158async fn wait_for_startup_operator_gate(
4159 session: &PtySession,
4160 spec: &AgentSpec,
4161) -> Result<(), String> {
4162 let deadline = Instant::now() + Duration::from_millis(STARTUP_GATE_SETTLE_MS);
4163 loop {
4164 ensure_no_startup_operator_gate(session, spec)?;
4165 let now = Instant::now();
4166 if now >= deadline {
4167 return Ok(());
4168 }
4169 tokio::time::sleep(
4170 deadline
4171 .saturating_duration_since(now)
4172 .min(Duration::from_millis(STARTUP_GATE_POLL_MS)),
4173 )
4174 .await;
4175 }
4176}
4177
4178fn ensure_no_startup_operator_gate(session: &PtySession, spec: &AgentSpec) -> Result<(), String> {
4198 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
4199 match startup_operator_gate(&snapshot.contents) {
4200 Some(gate) => Err(startup_operator_error(spec, &gate)),
4201 None => Ok(()),
4202 }
4203}
4204
4205fn startup_operator_error(spec: &AgentSpec, gate: &OperatorGateState) -> String {
4206 format!(
4207 "agent '{}' requires operator action at startup ({gate}); initial prompt was not submitted",
4208 spec.id
4209 )
4210}
4211
4212fn ensure_no_readiness_operator_gate(
4213 diagnostics: &ReadinessDiagnostics,
4214 spec: &AgentSpec,
4215) -> Result<(), String> {
4216 match &diagnostics.operator_gate {
4217 Some(gate) => Err(startup_operator_error(spec, gate)),
4218 None => Ok(()),
4219 }
4220}
4221
4222fn normalize_screen_text(contents: &str) -> String {
4229 contents
4230 .split_whitespace()
4231 .collect::<Vec<_>>()
4232 .join(" ")
4233 .to_ascii_lowercase()
4234}
4235
4236const PACKAGE_MANAGER_INSTALL_MARKERS: &[&str] = &[
4242 "npm install -g",
4243 "npm i -g",
4244 "npm update -g",
4245 "pip install --upgrade",
4246 "pip install -u",
4247 "yarn global add",
4248 "pnpm add -g",
4249];
4250
4251const PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS: &[&str] = &[
4257 "update ran successfully",
4258 "please restart",
4259 "update complete",
4260 "updated successfully",
4261];
4262
4263fn operator_gate(kind: OperatorGateKind, subject: OperatorGateSubject, contents: &str) -> OperatorGateState {
4274 let (input, options) = parse_operator_gate_options(contents);
4275 OperatorGateState::new(kind)
4276 .with_subject(subject)
4277 .with_options(input, options)
4278}
4279
4280fn startup_operator_gate(contents: &str) -> Option<OperatorGateState> {
4281 let normalized = normalize_screen_text(contents);
4282 if [
4283 "trust this folder",
4284 "trust the files in this folder",
4285 "trust the contents of this directory",
4286 "do you trust this directory",
4287 ]
4288 .iter()
4289 .any(|marker| normalized.contains(marker))
4290 {
4291 return Some(operator_gate(
4292 OperatorGateKind::WorkspaceTrust,
4293 OperatorGateSubject::Directory { path: None },
4294 contents,
4295 ));
4296 }
4297 if normalized.contains("quick safety check")
4298 && (normalized.contains("yes, i trust this folder")
4299 || normalized.contains("continue without these permissions"))
4300 {
4301 return Some(operator_gate(
4302 OperatorGateKind::WorkspaceTrust,
4303 OperatorGateSubject::Directory { path: None },
4304 contents,
4305 ));
4306 }
4307 if normalized.contains("hooks need review") && normalized.contains("continue without trusting")
4322 {
4323 return Some(operator_gate(
4324 OperatorGateKind::HookTrust,
4325 OperatorGateSubject::Hooks { count: None },
4326 contents,
4327 ));
4328 }
4329 if [
4330 "select authentication method",
4331 "choose how to authenticate",
4332 "no auth type is selected",
4333 ]
4334 .iter()
4335 .any(|marker| normalized.contains(marker))
4336 {
4337 return Some(operator_gate(
4338 OperatorGateKind::Authentication,
4339 OperatorGateSubject::Account,
4340 contents,
4341 ));
4342 }
4343 if normalized.contains("sign in")
4344 && (normalized.contains("openai")
4345 || normalized.contains("chatgpt")
4346 || normalized.contains("codex"))
4347 {
4348 return Some(operator_gate(
4349 OperatorGateKind::Authentication,
4350 OperatorGateSubject::Account,
4351 contents,
4352 ));
4353 }
4354 if normalized.contains("select login method") {
4363 return Some(operator_gate(
4364 OperatorGateKind::Authentication,
4365 OperatorGateSubject::Account,
4366 contents,
4367 ));
4368 }
4369 if normalized.contains("sign in") && normalized.contains("paste code") {
4381 return Some(
4382 OperatorGateState::new(OperatorGateKind::Authentication)
4383 .with_subject(OperatorGateSubject::Account)
4384 .with_options(OperatorGateInput::TextEntry, Vec::new()),
4385 );
4386 }
4387 if normalized.contains("kimi code update available")
4388 && normalized.contains("install update now")
4389 {
4390 return Some(operator_gate(
4391 OperatorGateKind::VendorUpdate,
4392 OperatorGateSubject::Unknown,
4393 contents,
4394 ));
4395 }
4396 if PACKAGE_MANAGER_INSTALL_MARKERS
4407 .iter()
4408 .any(|marker| normalized.contains(marker))
4409 && PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS
4410 .iter()
4411 .any(|marker| normalized.contains(marker))
4412 {
4413 return Some(operator_gate(
4414 OperatorGateKind::VendorUpdate,
4415 OperatorGateSubject::Unknown,
4416 contents,
4417 ));
4418 }
4419 if normalized.contains("choose the text style that looks best with your terminal") {
4420 return Some(operator_gate(
4421 OperatorGateKind::TerminalAppearance,
4422 OperatorGateSubject::Appearance,
4423 contents,
4424 ));
4425 }
4426 if normalized.contains("welcome to claude code for")
4427 && (normalized.contains("open files") || normalized.contains("selected lines"))
4428 {
4429 return Some(operator_gate(
4430 OperatorGateKind::Onboarding,
4431 OperatorGateSubject::Unknown,
4432 contents,
4433 ));
4434 }
4435 if normalized.contains("welcome to claude code")
4436 && (normalized.contains("press enter") || normalized.contains("enter to continue"))
4437 {
4438 return Some(operator_gate(
4439 OperatorGateKind::Onboarding,
4440 OperatorGateSubject::Unknown,
4441 contents,
4442 ));
4443 }
4444 if normalized.contains("migration") && normalized.contains("enter confirm") && normalized.contains("esc")
4445 {
4446 return Some(operator_gate(
4447 OperatorGateKind::ConfigurationMigration,
4448 OperatorGateSubject::Unknown,
4449 contents,
4450 ));
4451 }
4452 None
4453}
4454
4455fn parse_operator_gate_options(contents: &str) -> (OperatorGateInput, Vec<OperatorGateOption>) {
4477 let numbered: Vec<OperatorGateOption> = contents
4478 .lines()
4479 .filter_map(parse_numbered_gate_option_line)
4480 .take(OPERATOR_GATE_OPTIONS_MAX)
4481 .collect();
4482 if !numbered.is_empty() {
4483 return (OperatorGateInput::NumberedList, numbered);
4484 }
4485 let arrow: Vec<OperatorGateOption> = contents
4486 .lines()
4487 .filter_map(parse_arrow_gate_option_line)
4488 .take(OPERATOR_GATE_OPTIONS_MAX)
4489 .collect();
4490 if !arrow.is_empty() {
4491 return (OperatorGateInput::ArrowList, arrow);
4492 }
4493 (OperatorGateInput::Unknown, Vec::new())
4494}
4495
4496const GATE_CURSOR_GLYPHS: [char; 2] = ['\u{203a}', '\u{276f}'];
4510
4511fn parse_numbered_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4512 let trimmed = line.trim_start();
4513 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4521 Some(stripped) => (true, stripped.trim_start()),
4522 None => (false, trimmed),
4523 };
4524 let digits_end = rest.find(|character: char| !character.is_ascii_digit()).unwrap_or(0);
4525 if digits_end == 0 {
4526 return None;
4527 }
4528 let text = rest[digits_end..].strip_prefix('.')?.trim();
4529 if text.is_empty() {
4530 return None;
4531 }
4532 Some(OperatorGateOption {
4533 semantics: classify_operator_gate_option_semantics(text),
4534 text: text.to_owned(),
4535 selected,
4536 })
4537}
4538
4539fn parse_arrow_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4563 let trimmed = line.trim();
4564 if trimmed.is_empty()
4565 || trimmed
4566 .chars()
4567 .any(|character| matches!(character, '.' | '?' | '!' | ':'))
4568 {
4569 return None;
4570 }
4571 let lower = trimmed.to_ascii_lowercase();
4572 if lower.contains('\u{2191}') || lower.contains('\u{2193}') || lower.contains("navigate") {
4573 return None;
4574 }
4575 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4576 Some(stripped) => (true, stripped.trim()),
4577 None => (false, trimmed),
4578 };
4579 if rest.is_empty() || !rest.chars().any(|character| character.is_alphabetic()) {
4580 return None;
4581 }
4582 let semantics = classify_operator_gate_option_semantics(rest);
4583 if !selected && semantics == OperatorGateOptionSemantics::Unknown {
4584 return None;
4585 }
4586 Some(OperatorGateOption {
4587 semantics,
4588 text: rest.to_owned(),
4589 selected,
4590 })
4591}
4592
4593fn classify_operator_gate_option_semantics(text: &str) -> OperatorGateOptionSemantics {
4601 let lower = text.to_ascii_lowercase();
4602 if lower.contains("review") {
4603 OperatorGateOptionSemantics::Inspect
4604 } else if lower.contains("don't trust")
4605 || lower.contains("do not trust")
4606 || lower.contains("without trusting")
4607 || lower.contains("decline")
4608 {
4609 OperatorGateOptionSemantics::Decline
4610 } else if lower.contains("trust") || lower.contains("continue") || lower.contains("proceed") {
4611 OperatorGateOptionSemantics::Accept
4612 } else if lower.contains("exit") || lower.contains("quit") || lower.contains("cancel") {
4613 OperatorGateOptionSemantics::Exit
4614 } else {
4615 OperatorGateOptionSemantics::Unknown
4616 }
4617}
4618
4619fn looks_like_shell_prompt_line(line: &str) -> bool {
4624 matches!(line.trim_end().chars().last(), Some('$' | '%' | '#' | '>'))
4625}
4626
4627fn screen_failure(contents: &str) -> Option<&'static str> {
4650 let normalized = normalize_screen_text(contents);
4651
4652 if ["panicked at", "unhandled exception", "traceback (most recent call last)"]
4661 .iter()
4662 .any(|marker| normalized.contains(marker))
4663 {
4664 return Some("crash");
4665 }
4666
4667 if normalized.contains("command not found")
4673 || normalized.contains("is not recognized as an internal or external command")
4674 || (normalized.contains("no such file or directory")
4675 && contents.lines().any(looks_like_shell_prompt_line))
4676 {
4677 return Some("missing command");
4678 }
4679
4680 if normalized.contains("api key required") && normalized.contains("grok_api_key") {
4691 return Some("missing api key");
4692 }
4693
4694 None
4695}
4696
4697fn screen_failure_for_generation(contents: &str, ever_reached_ready: bool) -> Option<&'static str> {
4704 if ever_reached_ready {
4705 None
4706 } else {
4707 screen_failure(contents)
4708 }
4709}
4710
4711#[derive(Clone, Debug, Eq, PartialEq)]
4714enum ForegroundVerdict {
4715 Agent,
4717 Foreign { process: String },
4719}
4720
4721fn classify_pty_screen_state(
4747 foreground: Option<&ForegroundVerdict>,
4748 gate: Option<&OperatorGateState>,
4749 failure: Option<&'static str>,
4750) -> PtyScreenState {
4751 if let Some(ForegroundVerdict::Foreign { process }) = foreground {
4752 return PtyScreenState::NotAgent {
4753 observed_process: process.clone(),
4754 };
4755 }
4756 if let Some(reason) = failure {
4757 return PtyScreenState::Failing {
4758 reason: reason.to_owned(),
4759 };
4760 }
4761 if let Some(gate) = gate {
4762 return PtyScreenState::OperatorGate { gate: gate.clone() };
4763 }
4764 if foreground.is_some() {
4765 PtyScreenState::Ready
4766 } else {
4767 PtyScreenState::Unknown
4768 }
4769}
4770
4771fn resolve_foreground_verdict(
4787 spec: &AgentSpec,
4788 observation: &PtyForegroundObservation,
4789 platform: RuntimePlatform,
4790) -> ForegroundVerdict {
4791 let process_name = observation
4792 .readiness
4793 .process_name
4794 .as_deref()
4795 .unwrap_or(observation.observed_process.as_str());
4796 if is_expected_agent_process(spec, process_name, platform)
4797 || is_agent_foreground_wrapper(process_name, platform)
4798 {
4799 ForegroundVerdict::Agent
4800 } else {
4801 ForegroundVerdict::Foreign {
4802 process: observation.observed_process.clone(),
4803 }
4804 }
4805}
4806
4807#[derive(Clone, Copy, Debug, Eq, PartialEq)]
4813enum ForegroundProbeSchedule {
4814 Disarmed,
4816 Armed,
4818}
4819
4820fn foreground_probe_schedule(state: &PtyScreenState) -> ForegroundProbeSchedule {
4821 if matches!(state, PtyScreenState::Ready) {
4822 ForegroundProbeSchedule::Disarmed
4823 } else {
4824 ForegroundProbeSchedule::Armed
4825 }
4826}
4827
4828fn foreground_probe_rearms_immediately(previous: &PtyScreenState, next: &PtyScreenState) -> bool {
4836 matches!(previous, PtyScreenState::Ready) && !matches!(next, PtyScreenState::Ready)
4837}
4838
4839fn observe_readiness_event(
4840 tracker: &mut ReadinessTracker<'_>,
4841 diagnostics: &mut ReadinessDiagnostics,
4842 event: PtyEvent,
4843 elapsed_ms: u64,
4844) -> Result<(), String> {
4845 match event {
4846 PtyEvent::Output(data) => {
4847 diagnostics.observe_output(&data);
4848 tracker.observe_output(&data, elapsed_ms);
4849 }
4850 PtyEvent::ForegroundProcess(observation) => {
4851 diagnostics.observe_foreground(&observation.readiness);
4852 tracker.observe_foreground(&observation.readiness, elapsed_ms);
4853 }
4854 PtyEvent::DataGap { .. } => {
4855 return Err("PTY replay gap prevents positive readiness proof".to_owned());
4856 }
4857 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
4858 return Err(message);
4859 }
4860 PtyEvent::Exited { code } => {
4861 return Err(format!("PTY exited with code {code} before readiness"));
4862 }
4863 PtyEvent::Started | PtyEvent::Resized(_) | PtyEvent::SnapshotAvailable { .. } => {}
4864 }
4865 Ok(())
4866}
4867
4868#[derive(Default)]
4869struct ReadinessDiagnostics {
4870 draft_signal: Option<gate4agent_types::DraftReadySignal>,
4871 output_bytes: usize,
4872 output_chunks: usize,
4873 tail: Vec<u8>,
4874 saw_bracketed_paste: bool,
4875 saw_cursor_show: bool,
4876 saw_cursor_hide: bool,
4877 saw_alternate_screen: bool,
4878 saw_clear_screen: bool,
4879 saw_claude_composer: bool,
4880 saw_codex_composer: bool,
4881 saw_named_foreground: bool,
4882 operator_gate: Option<OperatorGateState>,
4883}
4884
4885impl ReadinessDiagnostics {
4886 fn observe_output(&mut self, data: &[u8]) {
4887 const SIGNAL_TAIL_BYTES: usize = 4_096;
4888 self.output_bytes = self.output_bytes.saturating_add(data.len());
4889 self.output_chunks = self.output_chunks.saturating_add(1);
4890 let mut combined = Vec::with_capacity(self.tail.len().saturating_add(data.len()));
4891 combined.extend_from_slice(&self.tail);
4892 combined.extend_from_slice(data);
4893 self.saw_bracketed_paste |= readiness_bytes_contain(&combined, b"\x1b[?2004h");
4894 self.saw_cursor_show |= readiness_bytes_contain(&combined, b"\x1b[?25h");
4895 self.saw_cursor_hide |= readiness_bytes_contain(&combined, b"\x1b[?25l");
4896 self.saw_alternate_screen |= readiness_bytes_contain(&combined, b"\x1b[?1049h");
4897 self.saw_clear_screen |= readiness_bytes_contain(&combined, b"\x1b[2J");
4898 self.saw_claude_composer |= readiness_bytes_contain(&combined, "❯".as_bytes());
4899 self.saw_codex_composer |= readiness_bytes_contain(&combined, "›".as_bytes());
4900 let text = String::from_utf8_lossy(&combined);
4901 self.operator_gate = self
4902 .operator_gate
4903 .take()
4904 .or_else(|| startup_operator_gate(&strip_ansi_codes(&text)));
4905 self.tail = combined[combined.len().saturating_sub(SIGNAL_TAIL_BYTES)..].to_vec();
4906 }
4907
4908 fn observe_foreground(&mut self, foreground: &gate4agent::agent::ForegroundObservation) {
4909 self.saw_named_foreground |= foreground.process_name.is_some();
4910 }
4911
4912 fn summary(&self) -> String {
4913 format!(
4914 "draft_signal={:?} output_bytes={} output_chunks={} named_foreground={} bracketed_paste={} cursor_show={} cursor_hide={} alternate_screen={} clear_screen={} claude_composer={} codex_composer={} csi={}",
4915 self.draft_signal,
4916 self.output_bytes,
4917 self.output_chunks,
4918 self.saw_named_foreground,
4919 self.saw_bracketed_paste,
4920 self.saw_cursor_show,
4921 self.saw_cursor_hide,
4922 self.saw_alternate_screen,
4923 self.saw_clear_screen,
4924 self.saw_claude_composer,
4925 self.saw_codex_composer,
4926 readiness_csi_signatures(&self.tail),
4927 )
4928 }
4929}
4930
4931fn readiness_csi_signatures(bytes: &[u8]) -> String {
4932 let mut signatures = Vec::new();
4933 let mut index = 0;
4934 while index + 2 < bytes.len() && signatures.len() < 32 {
4935 if bytes[index] != 0x1b || bytes[index + 1] != b'[' {
4936 index += 1;
4937 continue;
4938 }
4939 let mut end = index + 2;
4940 while end < bytes.len() && end.saturating_sub(index) <= 24 {
4941 let byte = bytes[end];
4942 if (0x40..=0x7e).contains(&byte) {
4943 let signature = String::from_utf8_lossy(&bytes[index + 2..=end]).into_owned();
4944 if !signatures.iter().any(|existing| existing == &signature) {
4945 signatures.push(signature);
4946 }
4947 index = end;
4948 break;
4949 }
4950 if !(0x20..=0x3f).contains(&byte) {
4951 break;
4952 }
4953 end += 1;
4954 }
4955 index += 1;
4956 }
4957 if signatures.is_empty() {
4958 "none".to_owned()
4959 } else {
4960 signatures.join("|")
4961 }
4962}
4963
4964fn readiness_bytes_contain(haystack: &[u8], needle: &[u8]) -> bool {
4965 haystack
4966 .windows(needle.len())
4967 .any(|window| window == needle)
4968}
4969
4970fn readiness_complete(
4971 status: ReadinessStatus,
4972 diagnostics: &ReadinessDiagnostics,
4973) -> Result<bool, String> {
4974 match status {
4975 ReadinessStatus::Waiting => Ok(false),
4976 ReadinessStatus::Ready(_) => Ok(true),
4977 ReadinessStatus::TimedOut => Err(format!(
4978 "PTY readiness timed out ({})",
4979 diagnostics.summary()
4980 )),
4981 }
4982}
4983
4984fn elapsed_ms(started: Instant) -> u64 {
4985 u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX)
4986}
4987
4988
4989pub const ACP_BUSY_PROMPT_ENV: &str = "GATE4AGENT_ACP_BUSY_PROMPT";
4992
4993fn busy_prompt_queues(value: Option<&str>) -> bool {
4994 value.is_some_and(|v| v.trim().eq_ignore_ascii_case("queue"))
4995}
4996
4997async fn submit_acp_prompt(session: &gate4agent::acp::AcpSession, prompt: &str) -> Result<(), gate4agent::acp::AcpError> {
5000 if busy_prompt_queues(std::env::var(ACP_BUSY_PROMPT_ENV).ok().as_deref()) {
5001 return session.start_prompt(prompt).await;
5002 }
5003 let delivery = session.submit_prompt(prompt).await?;
5004 match &delivery {
5005 gate4agent::acp::PromptDelivery::Queued { reason } => tracing::info!(
5006 session = session.session_id(),
5007 %reason,
5008 "ACP prompt queued behind the running turn"
5009 ),
5010 other => tracing::debug!(session = session.session_id(), delivery = ?other, "ACP prompt delivered"),
5011 }
5012 Ok(())
5013}
5014
5015#[cfg(test)]
5016mod busy_prompt_env_tests {
5017 use super::busy_prompt_queues;
5018
5019 #[test]
5020 fn only_queue_opts_out_of_steering() {
5021 assert!(busy_prompt_queues(Some("queue")));
5022 assert!(busy_prompt_queues(Some(" QUEUE ")));
5023 assert!(!busy_prompt_queues(Some("steer")));
5024 assert!(!busy_prompt_queues(Some("")));
5025 assert!(!busy_prompt_queues(None));
5026 }
5027}
5028
5029#[cfg(test)]
5030mod tests {
5031 use super::{
5032 acp_approval_level_args,
5033 approval_level_not_offered_message,
5034 classify_operator_gate_option_semantics,
5035 classify_pty_screen_state,
5036 defers_permission_requests,
5037 foreground_probe_rearms_immediately, foreground_probe_schedule,
5038 argument_looks_like_credential, host_policy_for_approval_level,
5039 mcp_server_acp_entry,
5040 parse_operator_gate_options, prepare_fresh_pty_provider_session,
5041 prompt_render_probe, prompt_rendered, required_acp_mode,
5042 reserve_provider_gap_sequence, resolve_foreground_verdict, screen_failure,
5043 screen_failure_for_generation, with_pty_terminal_capability_defaults,
5044 should_attach_pty_provider_stream, should_probe_pty_identity, startup_operator_gate,
5045 terminal_frame, terminal_frame_byte_len, terminal_state_capture_should_skip,
5046 validate_instance_launch_arguments, validate_spawn_runtime_policy,
5047 ForegroundProbeSchedule, ForegroundVerdict, ReadinessDiagnostics, RateLimitFeed,
5048 Utf8ChunkDecoder,
5049 };
5050 use gate4agent::acp::protocol::{McpServerConfig, SessionMode};
5051 use gate4agent::HostPolicy;
5052 use gate4agent_adapters::builtin_adapter_registry;
5053 use gate4agent_catalog::{EnvMutation, McpServerSpec, ModeId};
5054 use gate4agent::agent::ForegroundObservation;
5055 use gate4agent::core::types::{
5056 AgentEvent, ContextWindowUsage as AgentContextWindowUsage, HostDecisionAuthority,
5057 HostRequestDecision, HostRequestOutcome, RateLimitType,
5058 };
5059 use gate4agent::pty::event::PtyMouseProtocolEncoding;
5060 use gate4agent::pty::{PtyForegroundObservation, PtyForegroundSource, RateLimitDetector};
5061 use gate4agent::CliTool;
5062 use gate4agent_types::{
5063 AdapterFamily, AgentId, ApprovalLevel,
5064 HostDecisionAuthority as ProviderHostDecisionAuthority,
5065 HostRequestDecision as ProviderHostRequestDecision,
5066 HostRequestOutcome as ProviderHostRequestOutcome, OperatorGateInput,
5067 OperatorGateKind, OperatorGateOptionSemantics, OperatorGateState, OperatorGateSubject,
5068 ProviderEvent, ProviderInteractionKind, ProviderInteractionOption, ProviderRuntimePolicy,
5069 PtyScreenState, RuntimePlatform, TerminalMouseProtocolEncoding, TransportKind,
5070 };
5071 use std::ffi::{OsStr, OsString};
5072
5073 fn snapshot(sequence: u64, contents: &str) -> super::PtyTerminalSnapshot {
5074 super::PtyTerminalSnapshot {
5075 pty_id: "fixture".to_owned(),
5076 provider_revision: "fixture-r1".to_owned(),
5077 generation: 1,
5078 sequence,
5079 size: gate4agent::pty::PtySize { rows: 24, cols: 80 },
5080 cursor: (0, 0),
5081 bracketed_paste: false,
5082 contents: contents.to_owned(),
5083 formatted: Vec::new(),
5084 scrollback_formatted: Vec::new(),
5085 alternate_screen: false,
5086 mouse_protocol_enabled: false,
5087 mouse_protocol_encoding: PtyMouseProtocolEncoding::Default,
5088 produced_at_unix_ms: 0,
5089 }
5090 }
5091
5092 #[test]
5093 fn terminal_frame_preserves_scrollback_and_terminal_input_metadata() {
5094 let mut snapshot = snapshot(7, "visible");
5095 snapshot.scrollback_formatted = vec![b"older".to_vec()];
5096 snapshot.alternate_screen = true;
5097 snapshot.mouse_protocol_enabled = true;
5098 snapshot.mouse_protocol_encoding = PtyMouseProtocolEncoding::Sgr;
5099 snapshot.produced_at_unix_ms = 1_700_000_000_000;
5100
5101 let frame = terminal_frame(snapshot, PtyScreenState::default());
5102 assert_eq!(frame.scrollback_formatted, vec![b"older".to_vec()]);
5103 assert!(frame.alternate_screen);
5104 assert!(frame.mouse_protocol_enabled);
5105 assert_eq!(frame.mouse_protocol_encoding, TerminalMouseProtocolEncoding::Sgr);
5106 assert_eq!(frame.produced_at_unix_ms, 1_700_000_000_000);
5108 }
5109
5110 #[test]
5111 fn terminal_frame_byte_len_sums_formatted_and_every_scrollback_row() {
5112 let mut snapshot = snapshot(9, "visible");
5113 snapshot.formatted = b"\x1b[2Jvisible".to_vec();
5114 snapshot.scrollback_formatted =
5115 vec![b"row one".to_vec(), b"row two, longer".to_vec()];
5116 let expected = snapshot.formatted.len()
5117 + snapshot.scrollback_formatted[0].len()
5118 + snapshot.scrollback_formatted[1].len();
5119
5120 let frame = terminal_frame(snapshot, PtyScreenState::default());
5121 assert_eq!(terminal_frame_byte_len(&frame), expected as u64);
5122 }
5123
5124 #[test]
5125 fn the_sequence_gate_skips_only_when_the_sequence_did_not_advance() {
5126 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(5), 5));
5127 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(4), 5));
5128 assert!(!terminal_state_capture_should_skip(Ok::<u64, ()>(6), 5));
5129 assert!(!terminal_state_capture_should_skip(Err::<u64, ()>(()), 5));
5132 }
5133
5134 #[test]
5135 fn structured_context_usage_maps_without_pty_inference() {
5136 let mapped = super::provider_event(
5137 AgentEvent::ContextWindowUsage {
5138 usage: AgentContextWindowUsage {
5139 uncached_input_tokens: 70,
5140 cache_read_tokens: 20,
5141 cache_write_tokens: 0,
5142 output_tokens: 10,
5143 unattributed_tokens: 5,
5144 used_tokens: 105,
5145 capacity_tokens: 100,
5146 },
5147 },
5148 &[],
5149 );
5150 assert_eq!(
5151 mapped,
5152 Some(ProviderEvent::ContextWindowUsage {
5153 usage: gate4agent_types::ContextWindowUsage {
5154 uncached_input_tokens: 70,
5155 cache_read_tokens: 20,
5156 cache_write_tokens: 0,
5157 output_tokens: 10,
5158 unattributed_tokens: 5,
5159 used_tokens: 105,
5160 capacity_tokens: 100,
5161 }
5162 })
5163 );
5164 assert_eq!(
5165 ProviderEvent::ContextWindowUsage {
5166 usage: gate4agent_types::ContextWindowUsage {
5167 uncached_input_tokens: 70,
5168 cache_read_tokens: 20,
5169 cache_write_tokens: 0,
5170 output_tokens: 10,
5171 unattributed_tokens: 5,
5172 used_tokens: 104,
5173 capacity_tokens: 100,
5174 },
5175 }
5176 .validate_ingress(),
5177 Err(gate4agent_types::ProviderEventValidationError::ContextWindowSegmentsMismatch {
5178 segment_sum: 105,
5179 used_tokens: 104,
5180 })
5181 );
5182 assert!(
5183 super::provider_event(AgentEvent::PtyRaw { data: b"105/100".to_vec() }, &[]).is_none()
5184 );
5185 }
5186
5187 #[test]
5196 fn turn_interrupted_maps_to_the_provider_event_that_unblocks_the_next_prompt() {
5197 let mapped = super::provider_event(
5198 AgentEvent::TurnInterrupted {
5199 reason: "session/prompt timed out after 120s".to_owned(),
5200 },
5201 &[],
5202 );
5203 assert_eq!(mapped, Some(ProviderEvent::TurnInterrupted));
5204 }
5205
5206 #[test]
5207 fn tool_result_non_execution_kind_carries_through_to_tool_completed() {
5208 let mapped = super::provider_event(
5209 AgentEvent::ToolResult {
5210 id: "t1".to_owned(),
5211 output: "denied".to_owned(),
5212 is_error: true,
5213 duration_ms: None,
5214 non_execution_kind: Some("permission-rule".to_owned()),
5215 },
5216 &[],
5217 );
5218 assert_eq!(
5219 mapped,
5220 Some(ProviderEvent::ToolCompleted {
5221 id: "t1".to_owned(),
5222 output: "denied".to_owned(),
5223 is_error: true,
5224 duration_ms: None,
5225 agent_id: None,
5226 non_execution_kind: Some("permission-rule".to_owned()),
5227 })
5228 );
5229 }
5230
5231 #[test]
5232 fn session_end_stop_reason_carries_through_to_session_ended() {
5233 use gate4agent::StopReason;
5234
5235 let refusal = super::provider_event(
5236 AgentEvent::SessionEnd {
5237 result: "refusal".to_owned(),
5238 cost_usd: None,
5239 is_error: true,
5240 stop_reason: Some(StopReason::Refusal),
5241 },
5242 &[],
5243 );
5244 assert_eq!(
5245 refusal,
5246 Some(ProviderEvent::SessionEnded {
5247 result: "refusal".to_owned(),
5248 cost_usd: None,
5249 is_error: true,
5250 stop_reason: Some(gate4agent_types::ProviderStopReason::Refusal),
5251 })
5252 );
5253
5254 let quota = super::provider_event(
5255 AgentEvent::SessionEnd {
5256 result: "JSON-RPC error -32603: Internal error".to_owned(),
5257 cost_usd: None,
5258 is_error: true,
5259 stop_reason: Some(StopReason::ProviderError {
5260 code: -32603,
5261 message: "You've hit your usage limit.".to_owned(),
5262 vendor_code: Some("usageLimitExceeded".to_owned()),
5263 }),
5264 },
5265 &[],
5266 );
5267 assert_eq!(
5268 quota,
5269 Some(ProviderEvent::SessionEnded {
5270 result: "JSON-RPC error -32603: Internal error".to_owned(),
5271 cost_usd: None,
5272 is_error: true,
5273 stop_reason: Some(gate4agent_types::ProviderStopReason::ProviderError {
5274 code: -32603,
5275 message: "You've hit your usage limit.".to_owned(),
5276 vendor_code: Some("usageLimitExceeded".to_owned()),
5277 }),
5278 })
5279 );
5280 }
5281
5282 #[test]
5283 fn host_request_reaches_the_operator_with_method_and_host_decision() {
5284 let denied = super::provider_event(
5285 AgentEvent::RpcIncomingRequest {
5286 id: gate4agent::rpc::message::RpcId::Number(1),
5287 method: "fs/read_text_file".to_owned(),
5288 params: None,
5289 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Policy },
5290 outcome: HostRequestOutcome::Executed,
5291 reason: None,
5292 },
5293 &[],
5294 );
5295 assert_eq!(
5296 denied,
5297 Some(ProviderEvent::HostRequestObserved {
5298 method: "fs/read_text_file".to_owned(),
5299 params_json: String::new(),
5300 decision: ProviderHostRequestDecision::Denied {
5301 by: ProviderHostDecisionAuthority::Policy
5302 },
5303 outcome: ProviderHostRequestOutcome::Executed,
5304 reason: None,
5305 })
5306 );
5307
5308 let granted = super::provider_event(
5309 AgentEvent::RpcIncomingRequest {
5310 id: gate4agent::rpc::message::RpcId::Number(2),
5311 method: "terminal/create".to_owned(),
5312 params: None,
5313 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5314 outcome: HostRequestOutcome::Executed,
5315 reason: None,
5316 },
5317 &[],
5318 );
5319 assert_eq!(
5320 granted,
5321 Some(ProviderEvent::HostRequestObserved {
5322 method: "terminal/create".to_owned(),
5323 params_json: String::new(),
5324 decision: ProviderHostRequestDecision::Granted {
5325 by: ProviderHostDecisionAuthority::Policy
5326 },
5327 outcome: ProviderHostRequestOutcome::Executed,
5328 reason: None,
5329 })
5330 );
5331
5332 let gate_denied = super::provider_event(
5336 AgentEvent::RpcIncomingRequest {
5337 id: gate4agent::rpc::message::RpcId::Number(3),
5338 method: "terminal/create".to_owned(),
5339 params: None,
5340 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5341 outcome: HostRequestOutcome::Executed,
5342 reason: None,
5343 },
5344 &[],
5345 );
5346 assert_eq!(
5347 gate_denied,
5348 Some(ProviderEvent::HostRequestObserved {
5349 method: "terminal/create".to_owned(),
5350 params_json: String::new(),
5351 decision: ProviderHostRequestDecision::Denied {
5352 by: ProviderHostDecisionAuthority::Gate
5353 },
5354 outcome: ProviderHostRequestOutcome::Executed,
5355 reason: None,
5356 })
5357 );
5358
5359 let operator_granted = super::provider_event(
5360 AgentEvent::RpcIncomingRequest {
5361 id: gate4agent::rpc::message::RpcId::Number(4),
5362 method: "session/request_permission".to_owned(),
5363 params: None,
5364 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Operator },
5365 outcome: HostRequestOutcome::Executed,
5366 reason: None,
5367 },
5368 &[],
5369 );
5370 assert_eq!(
5371 operator_granted,
5372 Some(ProviderEvent::HostRequestObserved {
5373 method: "session/request_permission".to_owned(),
5374 params_json: String::new(),
5375 decision: ProviderHostRequestDecision::Granted {
5376 by: ProviderHostDecisionAuthority::Operator
5377 },
5378 outcome: ProviderHostRequestOutcome::Executed,
5379 reason: None,
5380 })
5381 );
5382
5383 let deadline_denied = super::provider_event(
5384 AgentEvent::RpcIncomingRequest {
5385 id: gate4agent::rpc::message::RpcId::Number(5),
5386 method: "session/request_permission".to_owned(),
5387 params: None,
5388 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::DeadlinePolicy },
5389 outcome: HostRequestOutcome::Executed,
5390 reason: None,
5391 },
5392 &[],
5393 );
5394 assert_eq!(
5395 deadline_denied,
5396 Some(ProviderEvent::HostRequestObserved {
5397 method: "session/request_permission".to_owned(),
5398 params_json: String::new(),
5399 decision: ProviderHostRequestDecision::Denied {
5400 by: ProviderHostDecisionAuthority::DeadlinePolicy
5401 },
5402 outcome: ProviderHostRequestOutcome::Executed,
5403 reason: None,
5404 })
5405 );
5406
5407 }
5413
5414 #[test]
5421 fn granted_host_request_execution_failure_carries_through_as_a_failed_outcome() {
5422 let spawn_error = "terminal/create spawn failed: os error 3";
5423 let mapped = super::provider_event(
5424 AgentEvent::RpcIncomingRequest {
5425 id: gate4agent::rpc::message::RpcId::Number(10),
5426 method: "terminal/create".to_owned(),
5427 params: None,
5428 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5429 outcome: HostRequestOutcome::Failed { error: spawn_error.to_owned() },
5430 reason: None,
5431 },
5432 &[],
5433 );
5434 assert_eq!(
5435 mapped,
5436 Some(ProviderEvent::HostRequestObserved {
5437 method: "terminal/create".to_owned(),
5438 params_json: String::new(),
5439 decision: ProviderHostRequestDecision::Granted {
5440 by: ProviderHostDecisionAuthority::Policy
5441 },
5442 outcome: ProviderHostRequestOutcome::Failed { error: spawn_error.to_owned() },
5443 reason: None,
5444 })
5445 );
5446 mapped.expect("mapped").validate_ingress().expect("bounded free-text error validates");
5447 }
5448
5449 #[test]
5456 fn host_request_reason_carries_through_to_the_operator() {
5457 let gate_text =
5458 "blocked by dangerous-command gate: rule=filesystem-wipe, argument=rm -rf /";
5459 let denied = super::provider_event(
5460 AgentEvent::RpcIncomingRequest {
5461 id: gate4agent::rpc::message::RpcId::Number(9),
5462 method: "terminal/create".to_owned(),
5463 params: None,
5464 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5465 outcome: HostRequestOutcome::Executed,
5466 reason: Some(gate_text.to_owned()),
5467 },
5468 &[],
5469 );
5470 assert_eq!(
5471 denied,
5472 Some(ProviderEvent::HostRequestObserved {
5473 method: "terminal/create".to_owned(),
5474 params_json: String::new(),
5475 decision: ProviderHostRequestDecision::Denied {
5476 by: ProviderHostDecisionAuthority::Gate
5477 },
5478 outcome: ProviderHostRequestOutcome::Executed,
5479 reason: Some(gate_text.to_owned()),
5480 })
5481 );
5482
5483 denied.expect("mapped").validate_ingress().expect("bounded free-text reason validates");
5488 }
5489
5490 #[test]
5491 fn deferred_acp_permission_request_becomes_an_interaction_with_its_id() {
5492 let with_title = super::provider_event(
5493 AgentEvent::RpcIncomingRequest {
5494 id: gate4agent::rpc::message::RpcId::Number(6),
5495 method: "session/request_permission".to_owned(),
5496 params: Some(serde_json::json!({
5497 "sessionId": "s1",
5498 "toolCall": {"toolCallId": "t1", "kind": "edit", "title": "Edit src/main.rs"},
5499 "options": [
5500 {"optionId": "allow", "name": "Allow", "kind": "allow_once"},
5501 {"optionId": "reject", "name": "Reject", "kind": "reject_once"},
5502 ],
5503 })),
5504 decision: HostRequestDecision::Deferred,
5505 outcome: HostRequestOutcome::Executed,
5506 reason: None,
5507 },
5508 &[],
5509 );
5510 assert_eq!(
5519 with_title,
5520 Some(ProviderEvent::InteractionRequested {
5521 request_id: Some("number:6".to_owned()),
5522 interaction_kind: ProviderInteractionKind::Approval,
5523 tool_name: "edit".to_owned(),
5524 title: Some("Edit src/main.rs".to_owned()),
5525 prompt: "Edit src/main.rs".to_owned(),
5526 options: vec![
5527 ProviderInteractionOption {
5528 option_id: "allow".to_owned(),
5529 name: "Allow".to_owned(),
5530 kind: "allow_once".to_owned(),
5531 },
5532 ProviderInteractionOption {
5533 option_id: "reject".to_owned(),
5534 name: "Reject".to_owned(),
5535 kind: "reject_once".to_owned(),
5536 },
5537 ],
5538 agent_id: None,
5539 })
5540 );
5541
5542 let without_title = super::provider_event(
5548 AgentEvent::RpcIncomingRequest {
5549 id: gate4agent::rpc::message::RpcId::String("agent-7".to_owned()),
5550 method: "session/request_permission".to_owned(),
5551 params: None,
5552 decision: HostRequestDecision::Deferred,
5553 outcome: HostRequestOutcome::Executed,
5554 reason: None,
5555 },
5556 &[],
5557 );
5558 assert_eq!(
5559 without_title,
5560 Some(ProviderEvent::InteractionRequested {
5561 request_id: Some("string:agent-7".to_owned()),
5562 interaction_kind: ProviderInteractionKind::Approval,
5563 tool_name: "session/request_permission".to_owned(),
5564 title: None,
5565 prompt: String::new(),
5566 options: Vec::new(),
5567 agent_id: None,
5568 })
5569 );
5570
5571 let resolved = super::provider_event(
5575 AgentEvent::RpcIncomingRequest {
5576 id: gate4agent::rpc::message::RpcId::Number(6),
5577 method: "session/request_permission".to_owned(),
5578 params: None,
5579 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Operator },
5580 outcome: HostRequestOutcome::Executed,
5581 reason: None,
5582 },
5583 &[],
5584 );
5585 assert_eq!(
5586 resolved,
5587 Some(ProviderEvent::HostRequestObserved {
5588 method: "session/request_permission".to_owned(),
5589 params_json: String::new(),
5590 decision: ProviderHostRequestDecision::Denied {
5591 by: ProviderHostDecisionAuthority::Operator
5592 },
5593 outcome: ProviderHostRequestOutcome::Executed,
5594 reason: None,
5595 })
5596 );
5597 }
5598
5599 #[test]
5600 fn unrecognized_notification_reaches_the_operator_as_a_raw_event_instead_of_vanishing() {
5601 let mapped = super::provider_event(
5602 AgentEvent::RpcNotification {
5603 method: "session/update".to_owned(),
5604 params: Default::default(),
5605 },
5606 &[],
5607 );
5608 assert_eq!(
5609 mapped,
5610 Some(ProviderEvent::UnrecognizedNotification {
5611 method: "session/update".to_owned(),
5612 payload_json: "null".to_owned(),
5613 })
5614 );
5615 }
5616
5617 #[test]
5618 fn pty_terminal_capability_defaults_never_override_a_caller_supplied_term() {
5619 let caller_supplied = vec![EnvMutation {
5620 key: OsString::from("TERM"),
5621 value: Some(OsString::from("dumb")),
5622 }];
5623 let filled = with_pty_terminal_capability_defaults(caller_supplied);
5624
5625 let term_values: Vec<_> = filled
5626 .iter()
5627 .filter(|mutation| mutation.key.as_os_str() == OsStr::new("TERM"))
5628 .collect();
5629 assert_eq!(term_values.len(), 1, "TERM must not be duplicated");
5630 assert_eq!(term_values[0].value.as_deref(), Some(OsStr::new("dumb")));
5631
5632 let colorterm = filled
5633 .iter()
5634 .find(|mutation| mutation.key.as_os_str() == OsStr::new("COLORTERM"))
5635 .expect("COLORTERM default is filled in when the caller left it unset");
5636 assert_eq!(colorterm.value.as_deref(), Some(OsStr::new("truecolor")));
5637 }
5638
5639 #[test]
5645 fn mcp_server_acp_entry_translates_a_spec_into_one_stdio_entry() {
5646 let spec = McpServerSpec::new(
5647 "test-mcp-server",
5648 OsString::from("C:\\example\\example-mcp-server.exe"),
5649 vec![OsString::from("--session-proxy")],
5650 vec![
5651 (
5652 OsString::from("TEST_MCP_SESSION_ENDPOINT"),
5653 OsString::from("\\\\.\\pipe\\example-mcp-server-s1"),
5654 ),
5655 (
5656 OsString::from("TEST_MCP_SESSION_TOKEN"),
5657 OsString::from("tok-abc"),
5658 ),
5659 ],
5660 )
5661 .unwrap();
5662
5663 let server = mcp_server_acp_entry(&spec);
5664 match server {
5665 McpServerConfig::Stdio { name, command, args, env } => {
5666 assert_eq!(name, "test-mcp-server", "ACP v1 requires a name; the adapter registers by it");
5667 assert_eq!(command, "C:\\example\\example-mcp-server.exe");
5668 assert_eq!(args, vec!["--session-proxy".to_string()]);
5669 assert_eq!(env.len(), 2, "exactly the entries the spec was given, nothing else");
5670 assert_eq!(
5671 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_ENDPOINT").map(|pair| pair.value.as_str()),
5672 Some("\\\\.\\pipe\\example-mcp-server-s1")
5673 );
5674 assert_eq!(
5675 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_TOKEN").map(|pair| pair.value.as_str()),
5676 Some("tok-abc")
5677 );
5678 }
5679 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5680 }
5681 }
5682
5683 #[test]
5684 fn mcp_server_acp_entry_carries_zero_env_pairs_when_the_spec_carries_none() {
5685 let spec = McpServerSpec::new(
5686 "test-mcp-server",
5687 OsString::from("C:\\example\\example-mcp-server.exe"),
5688 vec![OsString::from("--session-proxy")],
5689 Vec::new(),
5690 )
5691 .unwrap();
5692
5693 let server = mcp_server_acp_entry(&spec);
5694 match server {
5695 McpServerConfig::Stdio { env, .. } => assert!(env.is_empty()),
5696 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5697 }
5698 }
5699
5700 #[test]
5701 fn credential_shape_rule_matches_prefixed_hex64_not_bare_digest_or_uuid() {
5702 let hex64 = "a1b2c3d4e5f6".repeat(5) + "a1b2";
5703 assert_eq!(hex64.len(), 64);
5704
5705 let prefixed_token = format!("g4aho_{hex64}");
5706 assert!(
5707 argument_looks_like_credential(&prefixed_token),
5708 "a short lowercase prefix plus '_' plus 64 lowercase hex chars is a credential"
5709 );
5710
5711 assert!(
5712 !argument_looks_like_credential(&hex64),
5713 "a bare 64-hex digest with no prefix is a legitimate diagnostic, not a credential"
5714 );
5715
5716 assert!(
5717 !argument_looks_like_credential("550e8400-e29b-41d4-a716-446655440000"),
5718 "a UUID must not be mistaken for a prefixed-hex64 credential"
5719 );
5720 }
5721
5722 #[test]
5723 fn native_instance_launch_arguments_fail_closed_before_shell_spawn() {
5724 let claude = AgentId::new("claude").unwrap();
5725 assert_eq!(
5726 validate_instance_launch_arguments(
5727 &claude,
5728 TransportKind::Pipe,
5729 &[OsString::from("--bundle-mode")],
5730 )
5731 .unwrap_err(),
5732 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
5733 );
5734 assert_eq!(
5735 validate_instance_launch_arguments(
5736 &claude,
5737 TransportKind::Pty,
5738 &[OsString::from("--resume=session-secret")],
5739 )
5740 .unwrap_err(),
5741 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
5742 );
5743 assert!(validate_instance_launch_arguments(
5744 &claude,
5745 TransportKind::Pty,
5746 &[
5747 OsString::from("--permission-mode"),
5748 OsString::from("default"),
5749 ],
5750 )
5751 .is_ok());
5752 }
5753
5754 fn kind_of(contents: &str) -> Option<OperatorGateKind> {
5758 startup_operator_gate(contents).map(|gate| gate.kind)
5759 }
5760
5761 #[test]
5762 fn startup_operator_gates_are_classified_without_returning_terminal_text() {
5763 assert_eq!(kind_of(" Trust this\nfolder? "), Some(OperatorGateKind::WorkspaceTrust));
5764 assert_eq!(
5765 kind_of("No auth type is selected"),
5766 Some(OperatorGateKind::Authentication)
5767 );
5768 assert_eq!(
5769 kind_of("Sign in with OpenAI to use Codex"),
5770 Some(OperatorGateKind::Authentication)
5771 );
5772 assert_eq!(
5778 kind_of(
5779 "Claude Code can be used with your Claude subscription or billed based on \
5780 API usage through your Console account.\n\
5781 Select login method:\n\
5782 \u{276f} 1. Claude ...\n\
5783 2. API usage billing\n\
5784 3. 3rd-party platform \u{b7} Amazon Bedrock ..."
5785 ),
5786 Some(OperatorGateKind::Authentication)
5787 );
5788 assert_eq!(
5789 kind_of(
5790 "Browser didn't open? Use the url below to sign in (c to copy)\n\
5791 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
5792 Paste code here"
5793 ),
5794 Some(OperatorGateKind::Authentication)
5795 );
5796 assert_eq!(
5801 kind_of(
5802 "Once you sign in, copy the generated token and paste it into your .env file; \
5803 no code entry happens on this screen."
5804 ),
5805 None
5806 );
5807 assert_eq!(
5808 kind_of("Kimi Code Update Available\nInstall update now (0.32.0)\nEnter confirm"),
5809 Some(OperatorGateKind::VendorUpdate)
5810 );
5811 assert_eq!(
5812 kind_of(
5813 "Welcome to Claude Code\nChoose the text style that looks best with your terminal"
5814 ),
5815 Some(OperatorGateKind::TerminalAppearance)
5816 );
5817 assert_eq!(
5818 kind_of(
5819 "Welcome to Claude Code for VS Code\nClaude has context of open files and selected lines"
5820 ),
5821 Some(OperatorGateKind::Onboarding)
5822 );
5823 assert_eq!(
5824 kind_of("Welcome to Claude Code\n❯ Press Enter to continue"),
5825 Some(OperatorGateKind::Onboarding)
5826 );
5827 assert_eq!(kind_of("Welcome to Claude Code\n❯ ready\nEnter to send"), None);
5828 assert_eq!(
5829 kind_of(
5830 "Quick safety check: Is this a project you trust?\nYes, I trust this folder\nNo, continue without these permissions"
5831 ),
5832 Some(OperatorGateKind::WorkspaceTrust)
5833 );
5834 assert_eq!(kind_of("ready for a prompt"), None);
5835 assert_eq!(
5840 kind_of(
5841 "Updating Codex via `npm install -g @openai/codex`...\n\
5842 npm warn cleanup Failed to remove some directories\n\
5843 Update ran successfully! Please restart Codex."
5844 ),
5845 Some(OperatorGateKind::VendorUpdate)
5846 );
5847 assert_eq!(
5857 kind_of(
5858 " Hooks need review\n\
5859 6 hooks are new or changed.\n\
5860 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5861 2. Trust all and continue\n\
5862 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5863 ),
5864 Some(OperatorGateKind::HookTrust)
5865 );
5866 assert_eq!(
5869 kind_of(
5870 " Hooks need review\n\
5871 42 hooks are new or changed.\n\
5872 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5873 2. Trust all and continue\n\
5874 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5875 ),
5876 Some(OperatorGateKind::HookTrust)
5877 );
5878 assert_eq!(
5882 kind_of(
5883 "I reviewed the pre-commit hooks in this repo and they look safe to trust; \
5884 I'll leave the hooks config as-is and continue with the refactor."
5885 ),
5886 None
5887 );
5888 }
5889
5890 #[test]
5897 fn startup_operator_gate_parses_a_numbered_hook_trust_option_list() {
5898 let contents = "Hooks need review\n\
5899 \u{203a} 1. Review hooks\n \
5900 2. Trust all and continue\n \
5901 3. Continue without trusting (hooks won't run)\n\
5902 Press enter to confirm or esc to go back";
5903 let gate = startup_operator_gate(contents).expect("hook trust must classify");
5904 assert_eq!(gate.kind, OperatorGateKind::HookTrust);
5905 assert_eq!(gate.input, OperatorGateInput::NumberedList);
5906 assert_eq!(
5907 gate.options,
5908 vec![
5909 gate4agent_types::OperatorGateOption {
5910 text: "Review hooks".to_owned(),
5911 semantics: OperatorGateOptionSemantics::Inspect,
5912 selected: true,
5913 },
5914 gate4agent_types::OperatorGateOption {
5915 text: "Trust all and continue".to_owned(),
5916 semantics: OperatorGateOptionSemantics::Accept,
5917 selected: false,
5918 },
5919 gate4agent_types::OperatorGateOption {
5920 text: "Continue without trusting (hooks won't run)".to_owned(),
5921 semantics: OperatorGateOptionSemantics::Decline,
5922 selected: false,
5923 },
5924 ],
5925 );
5926 }
5927
5928 #[test]
5935 fn startup_operator_gate_parses_an_arrow_workspace_trust_option_list() {
5936 let contents = "Do you trust the files in this folder?\n \
5937 Trust this folder\n \
5938 Enable project MCP servers. Remembered for this folder.\n\u{276f} \
5939 Don't trust\n \
5940 Exit Kimi Code. Asked again next launch.\n \
5941 \u{2191}\u{2193} navigate \u{b7} Enter select \u{b7} Esc exit";
5942 let gate = startup_operator_gate(contents).expect("workspace trust must classify");
5943 assert_eq!(gate.kind, OperatorGateKind::WorkspaceTrust);
5944 assert_eq!(gate.input, OperatorGateInput::ArrowList);
5945 assert_eq!(
5946 gate.options,
5947 vec![
5948 gate4agent_types::OperatorGateOption {
5949 text: "Trust this folder".to_owned(),
5950 semantics: OperatorGateOptionSemantics::Accept,
5951 selected: false,
5952 },
5953 gate4agent_types::OperatorGateOption {
5954 text: "Don't trust".to_owned(),
5955 semantics: OperatorGateOptionSemantics::Decline,
5956 selected: true,
5957 },
5958 ],
5959 );
5960 }
5961
5962 #[test]
5966 fn startup_operator_gate_without_a_recognized_option_list_reports_unknown_input() {
5967 let gate = startup_operator_gate("No auth type is selected")
5968 .expect("authentication must classify");
5969 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5970 assert_eq!(gate.input, OperatorGateInput::Unknown);
5971 assert!(gate.options.is_empty());
5972 }
5973
5974 #[test]
5983 fn startup_operator_gate_parses_claudes_login_method_chooser_including_its_cursor_row() {
5984 let contents = "Select login method:\n\
5985 \u{276f} 1. Claude ...\n\
5986 2. API usage billing\n\
5987 3. 3rd-party platform \u{b7} Amazon Bedrock ...";
5988 let gate = startup_operator_gate(contents).expect("authentication must classify");
5989 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5990 assert_eq!(gate.subject, OperatorGateSubject::Account);
5991 assert_eq!(gate.input, OperatorGateInput::NumberedList);
5992 assert_eq!(
5993 gate.options,
5994 vec![
5995 gate4agent_types::OperatorGateOption {
5996 text: "Claude ...".to_owned(),
5997 semantics: OperatorGateOptionSemantics::Unknown,
5998 selected: true,
5999 },
6000 gate4agent_types::OperatorGateOption {
6001 text: "API usage billing".to_owned(),
6002 semantics: OperatorGateOptionSemantics::Unknown,
6003 selected: false,
6004 },
6005 gate4agent_types::OperatorGateOption {
6006 text: "3rd-party platform \u{b7} Amazon Bedrock ...".to_owned(),
6007 semantics: OperatorGateOptionSemantics::Unknown,
6008 selected: false,
6009 },
6010 ],
6011 );
6012 }
6013
6014 #[test]
6019 fn startup_operator_gate_oauth_wait_screen_reports_text_entry_input() {
6020 let contents = "Browser didn't open? Use the url below to sign in (c to copy)\n\
6021 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
6022 Paste code here";
6023 let gate = startup_operator_gate(contents).expect("oauth wait screen must classify");
6024 assert_eq!(gate.kind, OperatorGateKind::Authentication);
6025 assert_eq!(gate.subject, OperatorGateSubject::Account);
6026 assert_eq!(gate.input, OperatorGateInput::TextEntry);
6027 assert!(gate.options.is_empty());
6028 }
6029
6030 #[test]
6036 fn parse_operator_gate_options_recognizes_numbered_and_arrow_shapes_and_nothing_else() {
6037 assert_eq!(
6038 parse_operator_gate_options("Press enter to confirm or esc to go back"),
6039 (OperatorGateInput::Unknown, Vec::new()),
6040 );
6041 let (input, options) = parse_operator_gate_options(
6042 "\u{203a} 1. Review hooks\n 2. Trust all and continue",
6043 );
6044 assert_eq!(input, OperatorGateInput::NumberedList);
6045 assert_eq!(options.len(), 2);
6046 let (input, options) = parse_operator_gate_options(
6047 " Trust this folder\n Enable project MCP servers. Remembered for this folder.\n\u{276f} Don't trust",
6048 );
6049 assert_eq!(input, OperatorGateInput::ArrowList);
6050 assert_eq!(options.len(), 2);
6051 }
6052
6053 #[test]
6054 fn classify_operator_gate_option_semantics_reads_the_verb_not_the_position() {
6055 assert_eq!(
6056 classify_operator_gate_option_semantics("Review hooks"),
6057 OperatorGateOptionSemantics::Inspect,
6058 );
6059 assert_eq!(
6060 classify_operator_gate_option_semantics("Trust all and continue"),
6061 OperatorGateOptionSemantics::Accept,
6062 );
6063 assert_eq!(
6064 classify_operator_gate_option_semantics("Continue without trusting (hooks won't run)"),
6065 OperatorGateOptionSemantics::Decline,
6066 );
6067 assert_eq!(
6068 classify_operator_gate_option_semantics("Don't trust"),
6069 OperatorGateOptionSemantics::Decline,
6070 );
6071 assert_eq!(
6072 classify_operator_gate_option_semantics("Exit Kimi Code"),
6073 OperatorGateOptionSemantics::Exit,
6074 );
6075 assert_eq!(
6076 classify_operator_gate_option_semantics("Something unrecognized"),
6077 OperatorGateOptionSemantics::Unknown,
6078 );
6079 }
6080
6081 #[test]
6082 fn screen_failure_recognizes_crash_and_missing_command_banners() {
6083 assert_eq!(
6084 screen_failure("thread 'main' panicked at 'index out of bounds', src/main.rs:12:5"),
6085 Some("crash")
6086 );
6087 assert_eq!(
6088 screen_failure("Traceback (most recent call last):\n File \"a.py\", line 1"),
6089 Some("crash")
6090 );
6091 assert_eq!(
6092 screen_failure("bash: fooagent: command not found"),
6093 Some("missing command")
6094 );
6095 assert_eq!(
6096 screen_failure("C:\\workspace> fooagent\n'fooagent' is not recognized as an internal or external command"),
6097 Some("missing command")
6098 );
6099 assert_eq!(
6100 screen_failure(
6101 "workspace/project $ fooagent: no such file or directory\nworkspace/project $"
6102 ),
6103 Some("missing command")
6104 );
6105 assert_eq!(
6108 screen_failure("The build log mentions no such file or directory near line 40."),
6109 None
6110 );
6111 assert_eq!(
6115 screen_failure("fooagent-installer: fatal error: missing header <stdio.h>"),
6116 None
6117 );
6118 }
6119
6120 #[test]
6121 fn screen_failure_recognizes_grok_missing_api_key_banner() {
6122 assert_eq!(
6127 screen_failure(
6128 "\u{274c} Error: API key required. Set GROK_API_KEY environment variable, \
6129 use --api-key flag, or set \"apiKey\" field in ~/.grok/user-settings.json"
6130 ),
6131 Some("missing api key")
6132 );
6133 assert_eq!(
6137 screen_failure(
6138 "You'll need an API key for this provider before it works; check the docs \
6139 for how to configure one."
6140 ),
6141 None
6142 );
6143 }
6144
6145 #[test]
6146 fn screen_failure_no_longer_has_an_authentication_expired_bucket() {
6147 assert_eq!(
6152 screen_failure("Your session token has expired. Please re-authenticate."),
6153 None
6154 );
6155 assert_eq!(
6156 screen_failure("The stored credential was revoked by the workspace admin."),
6157 None
6158 );
6159 }
6160
6161 #[test]
6162 fn screen_failure_does_not_false_positive_on_an_agent_narrating_an_error() {
6163 let narration = "I looked at the traceback you pasted -- it's a Python \
6168 exception, a plain ValueError from a retry loop, not a real crash. \
6169 Our harness logs the word fatal in its own banner for visibility, \
6170 but nothing actually panicked. The command definitely exists; it \
6171 just needed different flags, and your token is still valid.";
6172 assert_eq!(screen_failure(narration), None);
6173 }
6174
6175 #[test]
6176 fn screen_failure_for_generation_ignores_every_marker_once_the_session_was_ever_ready() {
6177 let shell_command_not_found = "$ frobnicate --help\nbash: frobnicate: command not found\n$";
6182 assert_eq!(
6183 screen_failure_for_generation(shell_command_not_found, true),
6184 None
6185 );
6186
6187 let python_traceback_from_a_ran_script = "$ python broken.py\n\
6188 Traceback (most recent call last):\n File \"broken.py\", line 3, in <module>\n\
6189 ValueError: bad input\n$";
6190 assert_eq!(
6191 screen_failure_for_generation(python_traceback_from_a_ran_script, true),
6192 None
6193 );
6194
6195 let cargo_test_panic = "running 1 test\n\
6196 error[E0308]: mismatched types\n\
6197 thread 'tests::it_fails' panicked at 'assertion failed', src/lib.rs:9:5\n\
6198 test result: FAILED. 0 passed; 1 failed";
6199 assert_eq!(screen_failure_for_generation(cargo_test_panic, true), None);
6200
6201 let agent_narrating_an_expired_token = "The API token has expired; \
6202 I revoked the old credential and issued a new one for you.";
6203 assert_eq!(
6204 screen_failure_for_generation(agent_narrating_an_expired_token, true),
6205 None
6206 );
6207
6208 assert_eq!(
6213 screen_failure_for_generation(shell_command_not_found, false),
6214 Some("missing command")
6215 );
6216 assert_eq!(
6217 screen_failure_for_generation(python_traceback_from_a_ran_script, false),
6218 Some("crash")
6219 );
6220 assert_eq!(screen_failure_for_generation(cargo_test_panic, false), Some("crash"));
6221 }
6222
6223 #[test]
6224 fn classify_pty_screen_state_lets_a_foreign_process_win_over_a_matching_gate_text() {
6225 let foreign = ForegroundVerdict::Foreign {
6230 process: "npm".to_owned(),
6231 };
6232 assert_eq!(
6233 classify_pty_screen_state(Some(&foreign), None, None),
6234 PtyScreenState::NotAgent {
6235 observed_process: "npm".to_owned()
6236 }
6237 );
6238 let vendor_update_gate = OperatorGateState::new(OperatorGateKind::VendorUpdate);
6239 assert_eq!(
6240 classify_pty_screen_state(Some(&foreign), Some(&vendor_update_gate), None),
6241 PtyScreenState::NotAgent {
6242 observed_process: "npm".to_owned()
6243 }
6244 );
6245 }
6246
6247 #[test]
6248 fn classify_pty_screen_state_reports_a_gate_only_when_foreground_matches() {
6249 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6250 assert_eq!(
6251 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), Some(&authentication_gate), None),
6252 PtyScreenState::OperatorGate {
6253 gate: authentication_gate.clone()
6254 }
6255 );
6256 }
6257
6258 #[test]
6259 fn classify_pty_screen_state_reports_failing_for_a_matched_foreground() {
6260 assert_eq!(
6261 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, Some("crash")),
6262 PtyScreenState::Failing {
6263 reason: "crash".to_owned()
6264 }
6265 );
6266 }
6267
6268 #[test]
6269 fn classify_pty_screen_state_prefers_failing_over_a_co_occurring_gate() {
6270 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6274 assert_eq!(
6275 classify_pty_screen_state(
6276 Some(&ForegroundVerdict::Agent),
6277 Some(&authentication_gate),
6278 Some("crash")
6279 ),
6280 PtyScreenState::Failing {
6281 reason: "crash".to_owned()
6282 }
6283 );
6284 }
6285
6286 #[test]
6287 fn classify_pty_screen_state_reaches_ready_only_with_matched_foreground_and_clean_text() {
6288 assert_eq!(
6289 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, None),
6290 PtyScreenState::Ready
6291 );
6292 }
6293
6294 #[test]
6295 fn classify_pty_screen_state_never_reaches_ready_without_a_foreground_observation() {
6296 assert_eq!(classify_pty_screen_state(None, None, None), PtyScreenState::Unknown);
6299 }
6300
6301 #[test]
6302 fn resolve_foreground_verdict_tolerates_a_spawning_wrapper_like_readiness_does() {
6303 let spec = gate4agent_testkit::interactive_agent_spec();
6311 let observation = PtyForegroundObservation {
6312 root_pid: 1,
6313 observed_pid: 2,
6314 observed_process: "node".to_owned(),
6315 readiness: ForegroundObservation {
6316 process_name: Some("node".to_owned()),
6317 has_child_processes: true,
6318 is_shell: false,
6319 },
6320 source: PtyForegroundSource::ProcessTree,
6321 };
6322 let verdict = resolve_foreground_verdict(&spec, &observation, RuntimePlatform::current());
6323 assert_eq!(verdict, ForegroundVerdict::Agent);
6324 assert_eq!(
6325 classify_pty_screen_state(Some(&verdict), None, None),
6326 PtyScreenState::Ready
6327 );
6328 }
6329
6330 #[test]
6331 fn foreground_probe_disarms_only_once_ready_and_rearms_on_a_fresh_gate() {
6332 assert_eq!(
6333 foreground_probe_schedule(&PtyScreenState::Ready),
6334 ForegroundProbeSchedule::Disarmed
6335 );
6336 assert_eq!(
6337 foreground_probe_schedule(&PtyScreenState::Unknown),
6338 ForegroundProbeSchedule::Armed
6339 );
6340 assert_eq!(
6341 foreground_probe_schedule(&PtyScreenState::OperatorGate {
6342 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate)
6343 }),
6344 ForegroundProbeSchedule::Armed
6345 );
6346 }
6347
6348 #[test]
6349 fn text_only_gate_transition_rearms_the_probe_only_when_leaving_ready() {
6350 let gate = PtyScreenState::OperatorGate {
6351 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate),
6352 };
6353 assert!(foreground_probe_rearms_immediately(
6354 &PtyScreenState::Ready,
6355 &gate
6356 ));
6357 assert!(!foreground_probe_rearms_immediately(
6360 &PtyScreenState::Unknown,
6361 &gate
6362 ));
6363 }
6364
6365 #[test]
6366 fn readiness_diagnostics_detects_an_ansi_split_gate_without_exposing_text() {
6367 let mut diagnostics = ReadinessDiagnostics::default();
6368 diagnostics.observe_output(b"\x1b[31mNo auth ");
6369 diagnostics.observe_output(b"\x1b[0mtype is selected");
6370 assert_eq!(
6371 diagnostics.operator_gate.as_ref().map(|gate| gate.kind),
6372 Some(OperatorGateKind::Authentication)
6373 );
6374 assert!(!diagnostics.summary().contains("No auth"));
6375 }
6376
6377 #[test]
6378 fn semantic_utf8_decoder_preserves_codepoints_split_across_pty_reads() {
6379 let mut decoder = Utf8ChunkDecoder::default();
6380 let bytes = "ready Привет".as_bytes();
6381 let split = bytes
6382 .windows(2)
6383 .position(|window| window[0] >= 0x80 && window[1] >= 0x80)
6384 .expect("Cyrillic text contains adjacent UTF-8 bytes")
6385 + 1;
6386 let first = decoder.push(&bytes[..split]);
6387 let second = decoder.push(&bytes[split..]);
6388 assert_eq!(format!("{first}{second}"), "ready Привет");
6389 assert!(!first.contains('\u{fffd}'));
6390 assert!(!second.contains('\u{fffd}'));
6391 }
6392
6393 #[test]
6394 fn semantic_utf8_decoder_replaces_invalid_bytes_without_stalling() {
6395 let mut decoder = Utf8ChunkDecoder::default();
6396 assert_eq!(decoder.push(b"ok\xfftail"), "ok\u{fffd}tail");
6397 assert_eq!(decoder.push(" Привет".as_bytes()), " Привет");
6398 }
6399
6400 #[test]
6401 fn fresh_claude_pty_preassigns_the_exact_vendor_session_id_argv() {
6402 let claude = builtin_adapter_registry()
6403 .binding(AdapterFamily::PtySemantic, "claude-code")
6404 .expect("Claude PTY binding");
6405 let mut args = Vec::new();
6406 let identity = prepare_fresh_pty_provider_session(Some(claude), false, true, &mut args)
6407 .expect("fresh Claude provider identity");
6408 let parsed = uuid::Uuid::parse_str(&identity.id).expect("valid Claude UUID");
6409 assert_eq!(parsed.get_version_num(), 4);
6410 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
6411 assert!(identity.transcript_path.is_none());
6412 assert_eq!(args, [OsString::from("--session-id"), OsString::from(identity.id)]);
6413 }
6414
6415 #[test]
6416 fn fresh_codex_and_resumed_claude_do_not_preassign_a_second_identity() {
6417 let adapters = builtin_adapter_registry();
6418 let codex = adapters
6419 .binding(AdapterFamily::PtySemantic, "codex")
6420 .expect("Codex PTY binding");
6421 let claude = adapters
6422 .binding(AdapterFamily::PtySemantic, "claude-code")
6423 .expect("Claude PTY binding");
6424 let mut codex_args = Vec::new();
6425 assert!(prepare_fresh_pty_provider_session(Some(codex), false, true, &mut codex_args)
6426 .is_none());
6427 assert!(codex_args.is_empty());
6428
6429 let mut resume_args = vec![OsString::from("--resume"), OsString::from("vendor-id")];
6430 assert!(prepare_fresh_pty_provider_session(Some(claude), true, true, &mut resume_args)
6431 .is_none());
6432 assert_eq!(
6433 resume_args,
6434 [OsString::from("--resume"), OsString::from("vendor-id")]
6435 );
6436 }
6437
6438 #[test]
6439 fn raw_pty_policy_omits_all_identity_and_semantic_startup_paths() {
6440 let adapters = builtin_adapter_registry();
6441 let claude = adapters
6442 .binding(AdapterFamily::PtySemantic, "claude-code")
6443 .expect("Claude PTY binding");
6444 let codex = adapters
6445 .binding(AdapterFamily::PtySemantic, "codex")
6446 .expect("Codex PTY binding");
6447 let kimi = adapters
6448 .binding(AdapterFamily::PtySemantic, "kimi")
6449 .expect("Kimi PTY binding");
6450 let policy = ProviderRuntimePolicy::raw_pty();
6451 let mut args = Vec::new();
6452
6453 assert!(prepare_fresh_pty_provider_session(Some(claude), false, false, &mut args)
6454 .is_none());
6455 assert!(args.is_empty());
6456 assert!(!should_probe_pty_identity(policy, Some(codex), false, "codex"));
6457 assert!(!should_probe_pty_identity(policy, Some(kimi), false, "kimi"));
6458 assert!(!should_attach_pty_provider_stream(policy));
6459 }
6460
6461 #[test]
6462 fn identity_probe_requires_structured_prompt_for_codex_and_kimi() {
6463 let adapters = builtin_adapter_registry();
6464 let codex = adapters
6465 .binding(AdapterFamily::PtySemantic, "codex")
6466 .expect("Codex PTY binding");
6467 let kimi = adapters
6468 .binding(AdapterFamily::PtySemantic, "kimi")
6469 .expect("Kimi PTY binding");
6470 let without_structured_prompt =
6471 ProviderRuntimePolicy::new(true, true, false, true, false, false)
6472 .expect("identity observation policy without structured prompt");
6473
6474 assert!(!should_probe_pty_identity(
6475 without_structured_prompt,
6476 Some(codex),
6477 false,
6478 "codex",
6479 ));
6480 assert!(!should_probe_pty_identity(
6481 without_structured_prompt,
6482 Some(kimi),
6483 false,
6484 "kimi",
6485 ));
6486
6487 let with_structured_prompt =
6488 ProviderRuntimePolicy::new(true, true, true, true, false, false)
6489 .expect("identity probe policy");
6490 assert!(should_probe_pty_identity(
6491 with_structured_prompt,
6492 Some(codex),
6493 false,
6494 "codex",
6495 ));
6496 assert!(should_probe_pty_identity(
6497 with_structured_prompt,
6498 Some(kimi),
6499 false,
6500 "kimi",
6501 ));
6502 }
6503
6504 #[test]
6505 fn runtime_policy_admits_raw_native_resume_but_denies_unverified_prompt_injection() {
6506 let raw = ProviderRuntimePolicy::raw_pty();
6507 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, false).is_ok());
6508 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, false)
6509 .unwrap_err()
6510 .contains("SemanticReadiness"));
6511 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, true).is_ok());
6512 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, true)
6513 .unwrap_err()
6514 .contains("SemanticReadiness"));
6515
6516 let resume_without_prompt =
6517 ProviderRuntimePolicy::new(true, false, false, true, true, false)
6518 .expect("identity and resume policy");
6519 assert!(validate_spawn_runtime_policy(
6520 resume_without_prompt,
6521 TransportKind::Pty,
6522 false,
6523 true,
6524 )
6525 .is_ok());
6526 assert!(validate_spawn_runtime_policy(
6527 resume_without_prompt,
6528 TransportKind::Pty,
6529 true,
6530 true,
6531 )
6532 .unwrap_err()
6533 .contains("SemanticReadiness"));
6534 }
6535
6536 #[test]
6537 fn acp_transport_bypasses_the_pty_semantic_policy_gate_pty_and_pipe_still_enforce_it() {
6538 let no_pty_capabilities_at_all = ProviderRuntimePolicy::new(
6544 false, false, false, false, false, false,
6545 )
6546 .expect("an all-false policy is internally valid");
6547 assert!(validate_spawn_runtime_policy(
6548 no_pty_capabilities_at_all,
6549 TransportKind::Acp,
6550 false,
6551 false,
6552 )
6553 .is_ok());
6554 assert!(validate_spawn_runtime_policy(
6558 no_pty_capabilities_at_all,
6559 TransportKind::Pty,
6560 false,
6561 false,
6562 )
6563 .unwrap_err()
6564 .contains("RawPtyLifecycle"));
6565 assert!(validate_spawn_runtime_policy(
6566 no_pty_capabilities_at_all,
6567 TransportKind::Pipe,
6568 false,
6569 false,
6570 )
6571 .unwrap_err()
6572 .contains("RawPtyLifecycle"));
6573 }
6574
6575 #[test]
6576 fn prompt_render_probe_ignores_terminal_wrapping_and_uses_the_tail() {
6577 let prompt = "prefix with spaces\nand punctuation: final-render-token-1234567890";
6578 let probe = prompt_render_probe(prompt);
6579 assert!("screen prefix with spaces and punctuation final render token 1234567890"
6580 .chars()
6581 .filter(|character| character.is_alphanumeric())
6582 .flat_map(char::to_lowercase)
6583 .collect::<String>()
6584 .contains(&probe));
6585 assert!(probe.chars().count() <= 32);
6586 }
6587
6588 #[test]
6589 fn prompt_render_requires_new_sequence_and_visible_tail_evidence() {
6590 let probe = prompt_render_probe("final render token");
6591 let baseline = snapshot(7, "old composer");
6592 assert!(!prompt_rendered(
6593 &snapshot(7, "final\nrender\ntoken"),
6594 &baseline,
6595 &probe
6596 ));
6597 assert!(!prompt_rendered(
6598 &snapshot(8, "unrelated redraw"),
6599 &baseline,
6600 &probe
6601 ));
6602 assert!(prompt_rendered(
6603 &snapshot(8, "composer\nfinal\nrender\ntoken"),
6604 &baseline,
6605 &probe
6606 ));
6607 assert!(prompt_rendered(
6608 &snapshot(8, "composer [Pasted Content 4096 chars]"),
6609 &baseline,
6610 &probe
6611 ));
6612 assert!(prompt_rendered(
6613 &snapshot(8, "composer [Pasted text #1 +6 lines]"),
6614 &baseline,
6615 &probe
6616 ));
6617 }
6618
6619 #[test]
6620 fn an_existing_paste_placeholder_cannot_pass_on_an_unrelated_redraw() {
6621 let probe = prompt_render_probe("a new long prompt");
6622 assert!(!prompt_rendered(
6623 &snapshot(8, "composer [Pasted Content 4096 chars]\nunrelated redraw"),
6624 &snapshot(7, "composer [Pasted Content 4096 chars]"),
6625 &probe
6626 ));
6627 assert!(!prompt_rendered(
6628 &snapshot(8, "composer [Pasted text #1 +6 lines]\nunrelated redraw"),
6629 &snapshot(7, "composer [Pasted text #1 +6 lines]"),
6630 &probe
6631 ));
6632 }
6633
6634 #[test]
6635 fn punctuation_only_prompt_cannot_pass_on_an_unrelated_redraw() {
6636 let probe = prompt_render_probe("!?---");
6637 assert!(probe.is_empty());
6638 assert!(!prompt_rendered(
6639 &snapshot(2, "unrelated redraw"),
6640 &snapshot(1, "old composer"),
6641 &probe
6642 ));
6643 }
6644
6645 #[test]
6646 fn prompt_probe_matches_the_sanitized_terminal_payload() {
6647 let prompt = "payload\u{1b}tail";
6648 let sanitized = gate4agent_types::sanitize_prompt_text(prompt);
6649 let probe = prompt_render_probe(&sanitized);
6650 assert!(prompt_rendered(
6651 &snapshot(2, "composer payload<ESC>tail"),
6652 &snapshot(1, "old composer"),
6653 &probe
6654 ));
6655 }
6656
6657 #[test]
6658 fn lag_and_data_gap_reserve_missed_provider_source_positions() {
6659 let mut next = 7;
6660 assert_eq!(reserve_provider_gap_sequence(&mut next, 3), Some(9));
6661 assert_eq!(next, 10);
6662 assert_eq!(reserve_provider_gap_sequence(&mut next, 0), None);
6663 assert_eq!(next, 10);
6664
6665 next = u64::MAX;
6666 assert_eq!(reserve_provider_gap_sequence(&mut next, 1), None);
6667 assert_eq!(next, u64::MAX);
6668 }
6669
6670 const CODEX_STATUS_RAW_ANSI: &str = "│ 5h limit: \x1b[m[████████████████████] 100% left\x1b[2m (resets 00:08 on 31 Aug) │\r\n│ Weekly limit: \x1b[m[████████████████████] 100% left\x1b[2m (resets 19:08 on 6 Sep) │";
6683
6684 #[test]
6685 fn bare_detector_misses_the_live_ansi_sample_that_rate_limit_feed_catches() {
6686 let bare = RateLimitDetector::new_for_tool(CliTool::Codex);
6689 assert!(bare.detect(CODEX_STATUS_RAW_ANSI).is_none());
6690
6691 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6694 let info = feed
6695 .detect(CODEX_STATUS_RAW_ANSI)
6696 .expect("quota-state line must be recognized once ANSI is stripped");
6697 assert_eq!(info.limit_type, RateLimitType::Session);
6698 assert_eq!(info.usage_percent, Some(0.0));
6699 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6700 }
6701
6702 #[test]
6703 fn rate_limit_feed_reassembles_a_quota_state_line_split_mid_escape_and_mid_row() {
6704 let first =
6708 "│ 5h limit: \x1b[m[████████████████████] 100% left\x1b";
6709 let second = "[2m (resets 00:08 on 31 Aug) │\r\n";
6710
6711 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6712 assert!(
6713 feed.detect(first).is_none(),
6714 "the row is not complete yet, so nothing should match on the first chunk"
6715 );
6716 let info = feed
6717 .detect(second)
6718 .expect("the row completes once the second chunk arrives");
6719 assert_eq!(info.limit_type, RateLimitType::Session);
6720 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6721 }
6722
6723 #[test]
6724 fn rate_limit_feed_strips_ansi_before_matching_a_colored_failure_message() {
6725 let raw = "\x1b[31mError: rate limit exceeded\x1b[0m. Please wait.";
6729 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6730 let info = feed
6731 .detect(raw)
6732 .expect("a colored refusal message must still be recognized");
6733 assert_eq!(info.limit_type, RateLimitType::Unknown);
6734 }
6735
6736 #[test]
6737 fn rate_limit_feed_bounds_its_buffer_across_a_newline_free_redraw() {
6738 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6743 let noise = "x".repeat(super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES * 3);
6744 assert!(feed.detect(&noise).is_none());
6745 assert!(feed.buffer.len() <= super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES);
6746
6747 let info = feed
6748 .detect(CODEX_STATUS_RAW_ANSI)
6749 .expect("a real quota-state line must still be recognized after the noise");
6750 assert_eq!(info.limit_type, RateLimitType::Session);
6751 }
6752
6753 #[test]
6758 fn full_auto_maps_to_the_permissive_host_policy() {
6759 assert_eq!(host_policy_for_approval_level(ApprovalLevel::FullAuto), HostPolicy::Yolo);
6763 }
6764
6765 #[test]
6766 fn read_only_maps_to_the_read_only_host_policy() {
6767 assert_eq!(
6768 host_policy_for_approval_level(ApprovalLevel::ReadOnly),
6769 HostPolicy::ReadOnly
6770 );
6771 }
6772
6773 #[test]
6774 fn moderate_and_unmanaged_both_fall_back_to_the_default_host_policy() {
6775 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Moderate), HostPolicy::Auto);
6776 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Unmanaged), HostPolicy::Auto);
6777 assert_eq!(HostPolicy::default(), HostPolicy::Auto);
6778 }
6779
6780 #[test]
6781 fn no_approval_level_ever_maps_to_a_refusing_policy_except_read_only_itself() {
6782 for level in [
6787 ApprovalLevel::FullAuto,
6788 ApprovalLevel::Moderate,
6789 ApprovalLevel::ReadOnly,
6790 ApprovalLevel::Unmanaged,
6791 ] {
6792 assert_ne!(
6793 host_policy_for_approval_level(level),
6794 HostPolicy::Deny,
6795 "{level:?} must never map to HostPolicy::Deny"
6796 );
6797 }
6798 }
6799
6800 #[test]
6808 fn defers_permission_requests_matches_the_verified_provider_table() {
6809 let claude = AgentId::new("claude").unwrap();
6814 assert!(!defers_permission_requests(&claude, ApprovalLevel::FullAuto));
6815 assert!(defers_permission_requests(&claude, ApprovalLevel::Moderate));
6816 assert!(defers_permission_requests(&claude, ApprovalLevel::ReadOnly));
6820 assert!(!defers_permission_requests(&claude, ApprovalLevel::Unmanaged));
6824
6825 let codex = AgentId::new("codex").unwrap();
6826 assert!(!defers_permission_requests(&codex, ApprovalLevel::FullAuto));
6827 assert!(!defers_permission_requests(&codex, ApprovalLevel::Moderate));
6832 assert!(defers_permission_requests(&codex, ApprovalLevel::ReadOnly));
6833 assert!(!defers_permission_requests(&codex, ApprovalLevel::Unmanaged));
6835
6836 let grok = AgentId::new("grok").unwrap();
6837 assert!(!defers_permission_requests(&grok, ApprovalLevel::FullAuto));
6838 assert!(defers_permission_requests(&grok, ApprovalLevel::Moderate));
6839 assert!(defers_permission_requests(&grok, ApprovalLevel::ReadOnly));
6843 assert!(!defers_permission_requests(&grok, ApprovalLevel::Unmanaged));
6845
6846 let kimi = AgentId::new("kimi").unwrap();
6847 assert!(!defers_permission_requests(&kimi, ApprovalLevel::FullAuto));
6848 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Moderate));
6851 assert!(!defers_permission_requests(&kimi, ApprovalLevel::ReadOnly));
6855 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Unmanaged));
6857 }
6858
6859 fn session_mode(id: &str) -> SessionMode {
6866 SessionMode { id: id.to_owned(), name: id.to_owned(), description: None }
6867 }
6868
6869 #[test]
6870 fn required_acp_mode_matches_the_sourced_table() {
6871 let claude = AgentId::new("claude").unwrap();
6876 assert_eq!(
6877 required_acp_mode(&claude, ApprovalLevel::FullAuto),
6878 Ok(Some(ModeId::new("bypassPermissions")))
6879 );
6880 assert_eq!(
6881 required_acp_mode(&claude, ApprovalLevel::Moderate),
6882 Ok(Some(ModeId::new("acceptEdits")))
6883 );
6884 assert_eq!(
6888 required_acp_mode(&claude, ApprovalLevel::ReadOnly),
6889 Ok(Some(ModeId::new("default")))
6890 );
6891 assert_eq!(required_acp_mode(&claude, ApprovalLevel::Unmanaged), Ok(None));
6892
6893 let codex = AgentId::new("codex").unwrap();
6894 assert_eq!(
6895 required_acp_mode(&codex, ApprovalLevel::FullAuto),
6896 Ok(Some(ModeId::new("agent-full-access")))
6897 );
6898 assert_eq!(
6899 required_acp_mode(&codex, ApprovalLevel::Moderate),
6900 Ok(Some(ModeId::new("agent")))
6901 );
6902 assert_eq!(
6903 required_acp_mode(&codex, ApprovalLevel::ReadOnly),
6904 Ok(Some(ModeId::new("read-only")))
6905 );
6906 assert_eq!(required_acp_mode(&codex, ApprovalLevel::Unmanaged), Ok(None));
6907
6908 let kimi = AgentId::new("kimi").unwrap();
6920 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::FullAuto), Ok(None));
6921 assert_eq!(
6922 acp_approval_level_args(&kimi, ApprovalLevel::FullAuto),
6923 vec!["--auto".to_owned()],
6924 "kimi's FullAuto must reach the process through argv, since it has no ACP mode"
6925 );
6926 for level in [ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
6927 assert!(
6928 required_acp_mode(&kimi, level).is_err(),
6929 "kimi at {level:?} has neither a sourced ACP mode id nor vendor flags, so it must refuse"
6930 );
6931 }
6932 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::Unmanaged), Ok(None));
6933 assert!(
6934 acp_approval_level_args(&kimi, ApprovalLevel::Unmanaged).is_empty(),
6935 "Unmanaged imposes nothing, so it must add no argv flags either"
6936 );
6937
6938 let grok = AgentId::new("grok").unwrap();
6945 assert_eq!(required_acp_mode(&grok, ApprovalLevel::FullAuto), Ok(None));
6946 assert_eq!(
6947 acp_approval_level_args(&grok, ApprovalLevel::FullAuto),
6948 vec!["--always-approve".to_owned()],
6949 );
6950 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Moderate), Ok(None));
6951 assert_eq!(
6952 acp_approval_level_args(&grok, ApprovalLevel::Moderate),
6953 vec!["--permission-mode".to_owned(), "auto".to_owned()],
6954 );
6955 assert!(
6956 required_acp_mode(&grok, ApprovalLevel::ReadOnly).is_err(),
6957 "grok at ReadOnly is Unsupported outright, so it must refuse"
6958 );
6959 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Unmanaged), Ok(None));
6960 }
6961
6962 #[test]
6973 fn required_acp_mode_never_silently_permits_auto_except_for_unmanaged() {
6974 for id in ["claude", "codex", "grok", "kimi"] {
6975 let agent = AgentId::new(id).unwrap();
6976 for level in [ApprovalLevel::FullAuto, ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
6977 match required_acp_mode(&agent, level) {
6978 Ok(Some(mode_id)) => assert_ne!(
6979 mode_id.as_str(),
6980 "auto",
6981 "{id} at {level:?} must never silently resolve the vendor's own default 'auto'"
6982 ),
6983 Ok(None) => assert!(
6984 !acp_approval_level_args(&agent, level).is_empty(),
6985 "{id} at {level:?} resolved Ok(None) while carrying no vendor flags -- \
6986 that leaves the session at the agent's own default. Only Unmanaged, or a \
6987 level argv actually applies, may resolve to no mode"
6988 ),
6989 Err(_) => {} }
6991 }
6992 assert_eq!(
6993 required_acp_mode(&agent, ApprovalLevel::Unmanaged),
6994 Ok(None),
6995 "{id}: Unmanaged is the one level allowed to apply nothing"
6996 );
6997 }
6998 }
6999
7000 #[test]
7004 fn opencode_and_mcode_acp_approval_is_host_policy_full_auto_only() {
7005 for id in ["opencode", "mcode"] {
7006 let agent = AgentId::new(id).unwrap();
7007 assert_eq!(required_acp_mode(&agent, ApprovalLevel::FullAuto), Ok(None), "{id}");
7008 assert!(acp_approval_level_args(&agent, ApprovalLevel::FullAuto).is_empty());
7009 assert_eq!(required_acp_mode(&agent, ApprovalLevel::Unmanaged), Ok(None), "{id}");
7010 assert!(required_acp_mode(&agent, ApprovalLevel::Moderate).is_err(), "{id}");
7011 assert!(required_acp_mode(&agent, ApprovalLevel::ReadOnly).is_err(), "{id}");
7012 }
7013 }
7014
7015 #[test]
7016 fn approval_level_not_offered_message_refuses_by_name_and_lists_what_was_offered() {
7017 let offered = vec![session_mode("bypassPermissions"), session_mode("default")];
7018 let mode_id = ModeId::new("plan");
7019 let message = approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered)
7020 .expect("'plan' was not among the offered modes");
7021 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
7022 assert!(message.contains("bypassPermissions"));
7023 assert!(message.contains("default"));
7024 assert!(message.contains("ReadOnly"));
7025 }
7026
7027 #[test]
7028 fn approval_level_not_offered_message_is_none_when_the_agent_announced_it() {
7029 let offered = vec![session_mode("plan")];
7030 let mode_id = ModeId::new("plan");
7031 assert_eq!(
7032 approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered),
7033 None
7034 );
7035 }
7036
7037 #[test]
7038 fn approval_level_not_offered_message_handles_an_agent_that_announces_no_modes_at_all() {
7039 let mode_id = ModeId::new("bypassPermissions");
7040 let message = approval_level_not_offered_message(ApprovalLevel::FullAuto, &mode_id, &[])
7041 .expect("an empty mode catalog never offers anything");
7042 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
7043 assert!(message.contains("offered: []"));
7044 }
7045
7046 use super::{NativeEffectShell, NativeSessionKey, OwnedProviderSession};
7063 use gate4agent_catalog::{AgentRegistry as FixtureAgentRegistry, AgentSpec as FixtureAgentSpec};
7064 use gate4agent_types::ControlObservation;
7065 use std::collections::VecDeque;
7066
7067 fn fixture_pipe_key() -> NativeSessionKey {
7068 NativeSessionKey {
7069 instance_id: gate4agent_types::AgentInstanceId(9_001),
7070 generation: gate4agent_types::SessionGeneration(1),
7071 }
7072 }
7073
7074 fn fixture_pipe_source() -> gate4agent_types::ProviderSource {
7075 gate4agent_types::ProviderSource {
7076 family: AdapterFamily::Pipe,
7077 binding: gate4agent_types::AdapterBinding::new(
7078 gate4agent_types::AdapterId::new("fixture").unwrap(),
7079 "1",
7080 gate4agent_types::AdapterVerification::SyntheticFixture,
7081 )
7082 .unwrap(),
7083 }
7084 }
7085
7086 #[cfg(windows)]
7087 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7088 gate4agent_types::LaunchSpec {
7089 program: "powershell.exe".to_owned(),
7090 fixed_args: vec![
7091 "-NoProfile".to_owned(),
7092 "-NonInteractive".to_owned(),
7093 "-Command".to_owned(),
7094 "[Console]::In.ReadToEnd() | Out-Null; exit 0".to_owned(),
7095 ],
7096 }
7097 }
7098
7099 #[cfg(not(windows))]
7100 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7101 gate4agent_types::LaunchSpec {
7102 program: "sh".to_owned(),
7103 fixed_args: vec!["-c".to_owned(), "cat >/dev/null; exit 0".to_owned()],
7104 }
7105 }
7106
7107 #[cfg(windows)]
7108 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7109 gate4agent_types::LaunchSpec {
7110 program: "powershell.exe".to_owned(),
7111 fixed_args: vec![
7112 "-NoProfile".to_owned(),
7113 "-NonInteractive".to_owned(),
7114 "-Command".to_owned(),
7115 "Start-Sleep -Seconds 30".to_owned(),
7116 ],
7117 }
7118 }
7119
7120 #[cfg(not(windows))]
7121 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7122 gate4agent_types::LaunchSpec {
7123 program: "sh".to_owned(),
7124 fixed_args: vec!["-c".to_owned(), "sleep 30".to_owned()],
7125 }
7126 }
7127
7128 async fn spawn_fixture_pipe_shell(
7129 launch: gate4agent_types::LaunchSpec,
7130 ) -> (NativeEffectShell, NativeSessionKey) {
7131 let session = gate4agent::PipeSession::spawn_with_launch(
7132 gate4agent::core::types::SessionConfig::default(),
7133 "prompt",
7134 &launch,
7135 gate4agent_types::PipePromptDelivery::StdinClose,
7136 )
7137 .await
7138 .expect("fixture pipe process must spawn");
7139 let events = session.subscribe();
7140 let key = fixture_pipe_key();
7141 let mut shell = NativeEffectShell::new(
7142 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7143 .expect("empty fixture catalog"),
7144 );
7145 shell.pipe_sessions.insert(
7146 key,
7147 OwnedProviderSession {
7148 source: fixture_pipe_source(),
7149 session,
7150 events,
7151 pending_events: VecDeque::new(),
7152 pending_provider_events: VecDeque::new(),
7153 next_provider_sequence: 1,
7154 observed_exit_code: None,
7155 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7156 },
7157 );
7158 (shell, key)
7159 }
7160
7161 #[tokio::test]
7162 async fn stop_native_pipe_session_reports_the_real_exit_code_when_not_forced() {
7163 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_graceful_exit_launch()).await;
7164
7165 match shell.stop_native(key, false).await {
7166 ControlObservation::StopCompleted {
7167 forced, exit_code, ..
7168 } => {
7169 assert!(!forced, "a process that exits on its own must not be forced");
7170 assert_eq!(exit_code, Some(0));
7171 }
7172 other => panic!("expected StopCompleted, got {other:?}"),
7173 }
7174 }
7175
7176 #[tokio::test]
7177 async fn stop_native_pipe_session_force_true_kills_immediately_without_waiting() {
7178 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_ignore_stdin_launch()).await;
7179
7180 let start = std::time::Instant::now();
7181 match shell.stop_native(key, true).await {
7182 ControlObservation::StopCompleted { forced, .. } => {
7183 assert!(forced, "force=true must always report forced");
7184 }
7185 other => panic!("expected StopCompleted, got {other:?}"),
7186 }
7187 assert!(
7188 start.elapsed()
7189 < std::time::Duration::from_secs(gate4agent::pipe::PIPE_GRACEFUL_STOP_BOUND_SECS),
7190 "force=true must not wait out the graceful bound"
7191 );
7192 }
7193
7194 #[cfg(windows)]
7210 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7211 gate4agent_types::LaunchSpec {
7212 program: "powershell.exe".to_owned(),
7213 fixed_args: vec![
7214 "-NoLogo".to_owned(),
7215 "-NoProfile".to_owned(),
7216 "-NonInteractive".to_owned(),
7217 "-ExecutionPolicy".to_owned(),
7218 "Bypass".to_owned(),
7219 "-Command".to_owned(),
7220 ACP_HANDSHAKE_SCRIPT.to_owned(),
7221 ],
7222 }
7223 }
7224
7225 #[cfg(not(windows))]
7226 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7227 gate4agent_types::LaunchSpec {
7228 program: "python3".to_owned(),
7229 fixed_args: vec!["-u".to_owned(), "-c".to_owned(), ACP_HANDSHAKE_SCRIPT.to_owned()],
7230 }
7231 }
7232
7233 #[cfg(windows)]
7234 const ACP_HANDSHAKE_SCRIPT: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7235function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7236$initialize = [Console]::ReadLine() | ConvertFrom-Json
7237Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7238$newSession = [Console]::ReadLine() | ConvertFrom-Json
7239Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{sessionId='fixture-acp-session'}}
7240while ($true) {
7241 $line = [Console]::ReadLine()
7242 if ($null -eq $line) { exit 0 }
7243}"#;
7244 #[cfg(not(windows))]
7245 const ACP_HANDSHAKE_SCRIPT: &str = r#"import json,sys
7246def read_message():
7247 line=sys.stdin.readline()
7248 if not line: return None
7249 return json.loads(line)
7250def write_message(message):
7251 print(json.dumps(message),flush=True)
7252
7253initialize=read_message()
7254write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7255new_session=read_message()
7256write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{'sessionId':'fixture-acp-session'}})
7257while True:
7258 msg=read_message()
7259 if msg is None:
7260 sys.exit(0)"#;
7261
7262 fn fixture_acp_key() -> NativeSessionKey {
7263 NativeSessionKey {
7264 instance_id: gate4agent_types::AgentInstanceId(9_002),
7265 generation: gate4agent_types::SessionGeneration(1),
7266 }
7267 }
7268
7269 fn fixture_acp_source() -> gate4agent_types::ProviderSource {
7270 gate4agent_types::ProviderSource {
7271 family: AdapterFamily::Acp,
7272 binding: gate4agent_types::AdapterBinding::new(
7273 gate4agent_types::AdapterId::new("fixture").unwrap(),
7274 "1",
7275 gate4agent_types::AdapterVerification::SyntheticFixture,
7276 )
7277 .unwrap(),
7278 }
7279 }
7280
7281 async fn spawn_fixture_acp_shell() -> (NativeEffectShell, NativeSessionKey) {
7282 let session = gate4agent::acp::AcpSession::spawn_with_launch(
7283 gate4agent::CliTool::ClaudeCode,
7284 &std::env::current_dir().expect("cwd"),
7285 gate4agent::acp::AcpSessionOptions::default(),
7286 &acp_fixture_launch(),
7287 )
7288 .await
7289 .expect("fixture ACP handshake must succeed");
7290 let events = session.subscribe();
7291 let key = fixture_acp_key();
7292 let mut shell = NativeEffectShell::new(
7293 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7294 .expect("empty fixture catalog"),
7295 );
7296 shell.acp_sessions.insert(
7297 key,
7298 OwnedProviderSession {
7299 source: fixture_acp_source(),
7300 session,
7301 events,
7302 pending_events: VecDeque::new(),
7303 pending_provider_events: VecDeque::new(),
7304 next_provider_sequence: 1,
7305 observed_exit_code: None,
7306 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7307 },
7308 );
7309 (shell, key)
7310 }
7311
7312 #[tokio::test]
7313 async fn stop_native_acp_session_reports_the_real_exit_code_when_not_forced() {
7314 let (mut shell, key) = spawn_fixture_acp_shell().await;
7315
7316 match shell.stop_native(key, false).await {
7317 ControlObservation::StopCompleted {
7318 forced, exit_code, ..
7319 } => {
7320 assert!(!forced, "a process that exits on its own must not be forced");
7321 assert_eq!(exit_code, Some(0));
7322 }
7323 other => panic!("expected StopCompleted, got {other:?}"),
7324 }
7325 }
7326
7327 #[cfg(windows)]
7345 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7346 gate4agent_types::LaunchSpec {
7347 program: "powershell.exe".to_owned(),
7348 fixed_args: vec![
7349 "-NoLogo".to_owned(),
7350 "-NoProfile".to_owned(),
7351 "-NonInteractive".to_owned(),
7352 "-ExecutionPolicy".to_owned(),
7353 "Bypass".to_owned(),
7354 "-Command".to_owned(),
7355 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7356 ],
7357 }
7358 }
7359
7360 #[cfg(not(windows))]
7361 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7362 gate4agent_types::LaunchSpec {
7363 program: "python3".to_owned(),
7364 fixed_args: vec![
7365 "-u".to_owned(),
7366 "-c".to_owned(),
7367 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7368 ],
7369 }
7370 }
7371
7372 #[cfg(windows)]
7373 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7374function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7375$initialize = [Console]::ReadLine() | ConvertFrom-Json
7376Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7377$newSession = [Console]::ReadLine() | ConvertFrom-Json
7378Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{}}
7379while ($true) {
7380 $line = [Console]::ReadLine()
7381 if ($null -eq $line) { exit 0 }
7382}"#;
7383 #[cfg(not(windows))]
7384 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"import json,sys
7385def read_message():
7386 line=sys.stdin.readline()
7387 if not line: return None
7388 return json.loads(line)
7389def write_message(message):
7390 print(json.dumps(message),flush=True)
7391
7392initialize=read_message()
7393write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7394new_session=read_message()
7395write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{}})
7396while True:
7397 msg=read_message()
7398 if msg is None:
7399 sys.exit(0)"#;
7400
7401 fn fixture_acp_spawn_agent_id() -> AgentId {
7402 AgentId::new("claude").expect("builtin catalog names 'claude'")
7403 }
7404
7405 fn fixture_acp_spawn_agent_spec(launch: gate4agent_types::LaunchSpec) -> FixtureAgentSpec {
7411 let mut spec = gate4agent_catalog::builtin_registry()
7412 .get(&fixture_acp_spawn_agent_id())
7413 .cloned()
7414 .expect("builtin catalog must declare claude");
7415 spec.capabilities
7416 .transports
7417 .acp
7418 .as_mut()
7419 .expect("claude must declare ACP capability")
7420 .launch_override = Some(launch);
7421 spec
7422 }
7423
7424 fn fixture_acp_spawn_key() -> NativeSessionKey {
7425 NativeSessionKey {
7426 instance_id: gate4agent_types::AgentInstanceId(9_101),
7427 generation: gate4agent_types::SessionGeneration(1),
7428 }
7429 }
7430
7431 async fn spawn_native_acp_fixture(
7437 launch: gate4agent_types::LaunchSpec,
7438 provider_session_identity: bool,
7439 ) -> (NativeEffectShell, NativeSessionKey, ControlObservation) {
7440 let mut policy = ProviderRuntimePolicy::none();
7441 policy.provider_session_identity = provider_session_identity;
7442 let key = fixture_acp_spawn_key();
7443 let mut shell = NativeEffectShell::new(
7444 FixtureAgentRegistry::new([fixture_acp_spawn_agent_spec(launch)])
7445 .expect("single-agent fixture catalog"),
7446 );
7447 let envelope = gate4agent_types::EffectEnvelope {
7448 operation_id: gate4agent_types::OperationId(1),
7449 instance_id: key.instance_id,
7450 generation: key.generation,
7451 effect: gate4agent_types::ControlEffect::Spawn {
7452 agent_id: fixture_acp_spawn_agent_id(),
7453 transport: TransportKind::Acp,
7454 runtime_policy: policy,
7455 request: gate4agent_types::StartRequest {
7456 working_directory: std::env::current_dir()
7457 .expect("cwd")
7458 .to_string_lossy()
7459 .into_owned(),
7460 terminal_size: gate4agent_types::TerminalSize {
7461 rows: 24,
7462 columns: 80,
7463 },
7464 initial_prompt: None,
7465 session_options: None,
7466 approval_level: ApprovalLevel::Unmanaged,
7467 },
7468 },
7469 };
7470 let observation = shell.execute(envelope).await.observation;
7471 (shell, key, observation)
7472 }
7473
7474 #[tokio::test]
7475 async fn acp_spawn_with_a_real_sessionid_emits_session_identity_observed_after_session_start() {
7476 let (mut shell, key, spawned) =
7477 spawn_native_acp_fixture(acp_fixture_launch(), true).await;
7478 match spawned {
7479 ControlObservation::Spawned { .. } => {}
7480 other => panic!("expected Spawned, got {other:?}"),
7481 }
7482
7483 let mut provider_events = shell
7484 .collect_provider_events()
7485 .into_iter()
7486 .filter_map(|envelope| match envelope.observation {
7487 ControlObservation::ProviderEvent { event, .. } => Some(event),
7488 _ => None,
7489 });
7490
7491 match provider_events.next() {
7492 Some(ProviderEvent::SessionStarted { .. }) => {}
7493 other => panic!("expected SessionStarted first, got {other:?}"),
7494 }
7495 match provider_events.next() {
7496 Some(ProviderEvent::SessionIdentityObserved { identity }) => {
7497 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
7498 assert_eq!(identity.id, "fixture-acp-session");
7499 assert!(identity.transcript_path.is_none());
7500 }
7501 other => panic!("expected SessionIdentityObserved second, got {other:?}"),
7502 }
7503 assert!(
7504 provider_events.next().is_none(),
7505 "expected exactly one SessionIdentityObserved and nothing after it"
7506 );
7507
7508 let _ = shell.stop_native(key, true).await;
7509 }
7510
7511 #[tokio::test]
7512 async fn acp_spawn_with_no_sessionid_emits_no_session_identity_observed() {
7513 let (mut shell, key, spawned) =
7514 spawn_native_acp_fixture(acp_fixture_launch_no_session_id(), true).await;
7515 match spawned {
7516 ControlObservation::Spawned { .. } => {}
7517 other => panic!("expected Spawned, got {other:?}"),
7518 }
7519
7520 let provider_events: Vec<_> = shell
7521 .collect_provider_events()
7522 .into_iter()
7523 .filter_map(|envelope| match envelope.observation {
7524 ControlObservation::ProviderEvent { event, .. } => Some(event),
7525 _ => None,
7526 })
7527 .collect();
7528
7529 assert!(
7530 provider_events
7531 .iter()
7532 .any(|event| matches!(event, ProviderEvent::SessionStarted { .. })),
7533 "expected SessionStarted even when the agent reported no sessionId, got {provider_events:?}"
7534 );
7535 assert!(
7536 !provider_events
7537 .iter()
7538 .any(|event| matches!(event, ProviderEvent::SessionIdentityObserved { .. })),
7539 "an agent that violates ACP's sessionId MUST must not be granted an identity: \
7540 got {provider_events:?}"
7541 );
7542
7543 let _ = shell.stop_native(key, true).await;
7544 }
7545}
7546
7547#[cfg(test)]
7548mod resume_tests;