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 self.execute_with_launch_context_mcp_servers(
479 envelope,
480 environment,
481 extra_args,
482 one_shot_session_persistence,
483 mcp_server.into_iter().collect(),
484 )
485 .await
486 }
487
488 pub async fn execute_with_launch_context_mcp_servers(
493 &mut self,
494 envelope: EffectEnvelope,
495 environment: Vec<EnvMutation>,
496 extra_args: Vec<OsString>,
497 one_shot_session_persistence: OneShotSessionPersistence,
498 mcp_servers: Vec<McpServerSpec>,
499 ) -> ObservationEnvelope {
500 let EffectEnvelope {
501 operation_id,
502 instance_id,
503 generation,
504 effect,
505 } = envelope;
506 let key = NativeSessionKey {
507 instance_id,
508 generation,
509 };
510
511 let observation = {
512 match effect {
513 ControlEffect::Spawn {
514 agent_id,
515 transport,
516 runtime_policy,
517 request,
518 } => {
519 self.spawn_native(
520 key,
521 operation_id,
522 NativeSpawnRequest {
523 agent_id,
524 transport,
525 request,
526 runtime_policy,
527 launch_extra_args: Vec::new(),
528 instance_extra_args: extra_args,
529 resumed_provider_session: None,
530 one_shot_session_persistence,
531 },
532 environment,
533 mcp_servers,
534 )
535 .await
536 }
537 ControlEffect::SpawnResume {
538 agent_id,
539 transport,
540 provider_session,
541 runtime_policy,
542 request,
543 } => {
544 self.spawn_resume(
545 key,
546 operation_id,
547 agent_id,
548 transport,
549 provider_session,
550 runtime_policy,
551 request,
552 environment,
553 extra_args,
554 one_shot_session_persistence,
555 mcp_servers,
556 )
557 .await
558 }
559 ControlEffect::Stop { force } => self.stop_native(key, force).await,
560 ControlEffect::WriteInput {
561 input,
562 required_foreground,
563 } => match self.pty_sessions.get(&key) {
564 Some(owned) => match required_foreground {
565 ForegroundRequirement::Any
566 if matches!(
567 input.kind(),
568 PreparedInputKind::TerminalText
569 | PreparedInputKind::TerminalBytes
570 | PreparedInputKind::TerminalControl
571 ) =>
572 {
573 match owned.session.send_terminal_input(input).await {
574 Ok(()) => ControlObservation::InputCompleted,
575 Err(error) => ControlObservation::InputFailed {
576 message: error.to_string(),
577 },
578 }
579 }
580 ForegroundRequirement::Shell
581 if input.kind() == PreparedInputKind::ShellCommand =>
582 {
583 if !owned.runtime_policy.semantic_readiness {
584 ControlObservation::InputFailed {
585 message: "semantic shell input is not admitted by the provider runtime policy"
586 .to_owned(),
587 }
588 } else {
589 match owned.session.send_shell_input(input).await {
590 Ok(()) => ControlObservation::InputCompleted,
591 Err(error) => ControlObservation::InputFailed {
592 message: error.to_string(),
593 },
594 }
595 }
596 }
597 ForegroundRequirement::Agent { agent_id }
598 if matches!(
599 input.kind(),
600 PreparedInputKind::InsertDraft
601 | PreparedInputKind::SubmitPrompt
602 | PreparedInputKind::AgentCommand
603 ) && &agent_id == owned.session.agent_id() =>
604 {
605 if !owned.runtime_policy.semantic_readiness
606 || !owned.runtime_policy.structured_prompt
607 {
608 return completion_observation(
609 operation_id,
610 instance_id,
611 generation,
612 ControlObservation::InputFailed {
613 message: "semantic input is not admitted by the provider runtime policy"
614 .to_owned(),
615 },
616 );
617 }
618 let intent = match input.kind() {
619 PreparedInputKind::InsertDraft
620 | PreparedInputKind::AgentCommand => ReadinessIntent::DraftPaste,
621 PreparedInputKind::SubmitPrompt => ReadinessIntent::FollowupPrompt,
622 PreparedInputKind::ShellCommand
623 | PreparedInputKind::TerminalText
624 | PreparedInputKind::TerminalBytes
625 | PreparedInputKind::TerminalControl => unreachable!(),
626 };
627 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
628 return completion_observation(
629 operation_id,
630 instance_id,
631 generation,
632 ControlObservation::InputFailed {
633 message: "session agent disappeared from native catalog"
634 .to_owned(),
635 },
636 );
637 };
638 match wait_for_readiness(&owned.session, &spec, intent, false).await {
639 Ok(permit) => {
640 let result = if input.kind() == PreparedInputKind::AgentCommand
641 {
642 owned.session.send_agent_command_input(input, permit).await
643 } else {
644 owned.session.send_prepared_input(input, permit).await
645 };
646 match result {
647 Ok(()) => ControlObservation::InputCompleted,
648 Err(error) => ControlObservation::InputFailed {
649 message: error.to_string(),
650 },
651 }
652 }
653 Err(message) => ControlObservation::InputFailed { message },
654 }
655 }
656 required_foreground => ControlObservation::InputFailed {
657 message: format!(
658 "prepared input kind {:?} does not satisfy route {:?}",
659 input.kind(),
660 required_foreground
661 ),
662 },
663 },
664 None => ControlObservation::InputFailed {
665 message: "typed PTY input requires a PTY session".to_owned(),
666 },
667 },
668 ControlEffect::SubmitPrompt { prompt } => match self.acp_sessions.get(&key) {
669 Some(owned) if !owned.runtime_policy.structured_prompt => {
670 ControlObservation::InputFailed {
671 message: "structured prompt is not admitted by the provider runtime policy"
672 .to_owned(),
673 }
674 }
675 Some(owned) => match submit_acp_prompt(&owned.session, &prompt).await {
676 Ok(()) => ControlObservation::InputCompleted,
677 Err(error) => ControlObservation::InputFailed {
678 message: error.to_string(),
679 },
680 },
681 None => ControlObservation::InputFailed {
682 message: "semantic follow-up prompts require an ACP session".to_owned(),
683 },
684 },
685 ControlEffect::Interrupt => match self.acp_sessions.get(&key) {
686 Some(owned) => match owned.session.cancel().await {
687 Ok(()) => ControlObservation::InputCompleted,
688 Err(error) => ControlObservation::InputFailed {
689 message: error.to_string(),
690 },
691 },
692 None => ControlObservation::InputFailed {
693 message: "semantic interrupt requires an ACP session".to_owned(),
694 },
695 },
696 ControlEffect::ResolveInteraction { target, response } => {
697 resolve_acp_interaction_observation(
698 self.acp_sessions.get(&key).map(|owned| &owned.session),
699 target,
700 response,
701 )
702 }
703 ControlEffect::SetSessionMode { mode_id } => {
704 set_acp_session_mode_observation(
705 self.acp_sessions.get(&key).map(|owned| &owned.session),
706 mode_id,
707 )
708 .await
709 }
710 ControlEffect::SetSessionConfigOption {
711 option_id,
712 value_json,
713 } => {
714 set_acp_session_config_option_observation(
715 self.acp_sessions.get(&key).map(|owned| &owned.session),
716 option_id,
717 value_json,
718 )
719 .await
720 }
721 ControlEffect::SetSessionModel { model_id } => {
722 set_acp_session_model_observation(
723 self.acp_sessions.get(&key).map(|owned| &owned.session),
724 model_id,
725 )
726 }
727 ControlEffect::Resize { size } if !size.is_valid() => {
728 ControlObservation::ResizeFailed {
729 message: "terminal size is outside the supported range".to_owned(),
730 }
731 }
732 ControlEffect::Resize { size } => match self.pty_sessions.get(&key) {
733 Some(owned) => match owned.session.resize(size.rows, size.columns).await {
734 Ok(()) => ControlObservation::ResizeCompleted { size },
735 Err(error) => ControlObservation::ResizeFailed {
736 message: error.to_string(),
737 },
738 },
739 None => ControlObservation::ResizeFailed {
740 message: "terminal resize requires a PTY session".to_owned(),
741 },
742 },
743 ControlEffect::ObserveForeground => match self.pty_sessions.get(&key) {
744 Some(owned) => match owned.session.observe_foreground().await {
745 Ok(observation) => ControlObservation::ForegroundObserved {
746 process: canonical_foreground(
747 owned.session.agent_id().clone(),
748 &observation,
749 ),
750 },
751 Err(error) => ControlObservation::ForegroundFailed {
752 message: error.to_string(),
753 },
754 },
755 None => ControlObservation::ForegroundFailed {
756 message: "foreground observation requires a PTY session".to_owned(),
757 },
758 },
759 ControlEffect::ProbeCapabilities { .. } => {
760 ControlObservation::CapabilityProbeFailed {
761 failure: CapabilityProbeFailure::ExecutorUnavailable,
762 }
763 }
764 ControlEffect::DiscoverHistory { .. } | ControlEffect::LoadHistory { .. } => {
765 ControlObservation::HistoryFailed {
766 message: "history effects require the dedicated native history authority"
767 .to_owned(),
768 }
769 }
770 ControlEffect::AuthorizeResume { .. } => ControlObservation::ResumeFailed {
771 message: "resume authorization requires the dedicated native authority"
772 .to_owned(),
773 },
774 }
775 };
776
777 completion_observation(operation_id, instance_id, generation, observation)
778 }
779
780 async fn spawn_native(
781 &mut self,
782 key: NativeSessionKey,
783 operation_id: OperationId,
784 spawn: NativeSpawnRequest,
785 pty_env: Vec<EnvMutation>,
786 mcp_servers: Vec<McpServerSpec>,
787 ) -> ControlObservation {
788 let NativeSpawnRequest {
789 agent_id,
790 transport,
791 request,
792 runtime_policy,
793 mut launch_extra_args,
794 instance_extra_args,
795 resumed_provider_session,
796 one_shot_session_persistence,
797 } = spawn;
798 if let Err(message) =
799 validate_instance_launch_arguments(&agent_id, transport, &instance_extra_args)
800 {
801 return ControlObservation::SpawnFailed { message };
802 }
803 if let Err(message) = validate_spawn_runtime_policy(
804 runtime_policy,
805 transport,
806 request.initial_prompt.is_some(),
807 resumed_provider_session.is_some(),
808 ) {
809 return ControlObservation::SpawnFailed { message };
810 }
811 if self.session_exists(key) {
812 return ControlObservation::SpawnFailed {
813 message: format!(
814 "native session {:?}/{:?} already exists",
815 key.instance_id, key.generation
816 ),
817 };
818 }
819 if !request.terminal_size.is_valid() {
820 return ControlObservation::SpawnFailed {
821 message: "terminal size is outside the supported range".to_owned(),
822 };
823 }
824 if request.working_directory.is_empty()
825 || request.working_directory.len() > WORKING_DIRECTORY_MAX_BYTES
826 || request.working_directory.contains('\0')
827 {
828 return ControlObservation::SpawnFailed {
829 message: "working directory is invalid".to_owned(),
830 };
831 }
832 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
833 return ControlObservation::SpawnFailed {
834 message: format!("agent '{agent_id}' is absent from native catalog"),
835 };
836 };
837 let working_dir = PathBuf::from(&request.working_directory);
838
839 match transport {
840 TransportKind::Pty if !spec.capabilities.transports.pty => {
841 ControlObservation::SpawnFailed {
842 message: format!("agent '{agent_id}' does not support PTY transport"),
843 }
844 }
845 TransportKind::Pty => {
846 let pty_env = with_pty_terminal_capability_defaults(pty_env);
851 let fresh_provider_session = prepare_fresh_pty_provider_session(
852 spec.capabilities.transports.pty_adapter.as_ref(),
853 resumed_provider_session.is_some(),
854 runtime_policy.provider_session_identity,
855 &mut launch_extra_args,
856 );
857 launch_extra_args.extend(instance_extra_args);
858 let mut authoritative_provider_session = resumed_provider_session
859 .clone()
860 .or(fresh_provider_session);
861 let probe_kimi_identity = should_probe_pty_identity(
862 runtime_policy,
863 spec.capabilities.transports.pty_adapter.as_ref(),
864 authoritative_provider_session.is_some(),
865 "kimi",
866 );
867 let probe_codex_identity = should_probe_pty_identity(
868 runtime_policy,
869 spec.capabilities.transports.pty_adapter.as_ref(),
870 authoritative_provider_session.is_some(),
871 "codex",
872 );
873 tracing::info!(
886 agent_id = %agent_id,
887 instance_id = ?key.instance_id,
888 generation = ?key.generation,
889 terminal_size = ?request.terminal_size,
890 program = %spec.launch.program,
891 fixed_args = ?spec.launch.fixed_args,
892 extra_args = ?redact_provider_arguments(&launch_extra_args),
893 has_initial_prompt = request.initial_prompt.is_some(),
894 "spawning provider process over a PTY",
895 );
896 match PtySession::spawn_agent_with_size(
897 &spec,
898 LaunchRequest {
899 working_dir,
900 env: pty_env,
901 platform: RuntimePlatform::current(),
902 prompt: request.initial_prompt,
903 session_options: request.session_options,
904 extra_args: launch_extra_args,
905 },
906 request.terminal_size.rows,
907 request.terminal_size.columns,
908 )
909 .await
910 {
911 Ok(mut session) => {
912 if probe_kimi_identity {
913 match probe_fresh_kimi_session_identity(&session, &spec).await {
914 Ok(Some(identity)) => authoritative_provider_session = Some(identity),
915 Ok(None) => {}
916 Err(error) => {
917 let message = match session.shutdown().await {
918 Ok(_) => error,
919 Err(shutdown_error) => {
920 format!("{error}; PTY cleanup failed: {shutdown_error}")
921 }
922 };
923 return ControlObservation::SpawnFailed { message };
924 }
925 }
926 }
927 if probe_codex_identity {
928 match probe_fresh_codex_session_identity(&session, &spec).await {
929 Ok(Some(identity)) => authoritative_provider_session = Some(identity),
930 Ok(None) => {}
931 Err(error) => {
932 let message = match session.shutdown().await {
933 Ok(_) => error,
934 Err(shutdown_error) => {
935 format!("{error}; PTY cleanup failed: {shutdown_error}")
936 }
937 };
938 return ControlObservation::SpawnFailed { message };
939 }
940 }
941 }
942 if let Err(error) = deliver_pending_initial_prompt(&mut session, &spec).await {
943 let message = match session.shutdown().await {
944 Ok(_) => error,
945 Err(shutdown_error) => {
946 format!("{error}; PTY cleanup failed: {shutdown_error}")
947 }
948 };
949 return ControlObservation::SpawnFailed { message };
950 }
951 let process_id = session.root_pid();
952 let provider = match spec.capabilities.transports.pty_adapter.as_ref() {
953 _ if !should_attach_pty_provider_stream(runtime_policy) => None,
954 Some(adapter) => {
955 let tool = match self
956 .legacy_adapters
957 .resolve(AdapterFamily::PtySemantic, adapter)
958 {
959 Ok(tool) => *tool,
960 Err(error) => {
961 let _ = session.shutdown().await;
962 return ControlObservation::SpawnFailed {
963 message: error.to_string(),
964 };
965 }
966 };
967 match session.attach_events(session.beginning_cursor()) {
968 Ok(attachment) => {
969 let mut pending_events = VecDeque::new();
970 let mut provider_session_started = false;
971 if let Some(identity) = authoritative_provider_session {
972 pending_events.push_back(ProviderEvent::SessionStarted {
973 session_id: identity.id.clone(),
974 model: String::new(),
975 tools: Vec::new(),
976 });
977 pending_events.push_back(
978 ProviderEvent::SessionIdentityObserved { identity },
979 );
980 provider_session_started = true;
981 }
982 let is_kimi = tool == CliTool::KimiCode;
983 Some(OwnedPtyProvider {
984 source: ProviderSource {
985 family: AdapterFamily::PtySemantic,
986 binding: adapter.clone(),
987 },
988 receiver: attachment.receiver,
989 replay: attachment.replay.into(),
990 pending_events,
991 utf8: Utf8ChunkDecoder::default(),
992 pipeline: Mutex::new(create_pipeline(tool)),
993 rate_limits: RateLimitFeed::new_for_tool(tool),
994 kimi_identity: (runtime_policy.provider_session_identity
995 && is_kimi
996 && !provider_session_started)
997 .then(KimiPtySessionIdentityExtractor::default),
998 semantic_events: runtime_policy.semantic_readiness,
999 provider_session_started,
1000 next_provider_sequence: 1,
1001 })
1002 }
1003 Err(error) => {
1004 let _ = session.shutdown().await;
1005 return ControlObservation::SpawnFailed {
1006 message: error.to_string(),
1007 };
1008 }
1009 }
1010 }
1011 None => None,
1012 };
1013 self.pty_sessions.insert(
1014 key,
1015 OwnedPtySession {
1016 session,
1017 spawn_operation_id: operation_id,
1018 last_terminal_sequence: 0,
1019 terminal_stale_published: false,
1020 runtime_policy,
1021 provider,
1022 agent_id,
1023 last_screen_gate: None,
1024 last_screen_failure: None,
1025 last_foreground_verdict: None,
1026 last_screen_state: PtyScreenState::default(),
1027 ever_reached_ready: false,
1028 screen_had_content: false,
1029 next_foreground_probe: Some(Instant::now()),
1034 },
1035 );
1036 ControlObservation::Spawned { process_id }
1037 }
1038 Err(error) => {
1039 let message = error.to_string();
1040 tracing::warn!(
1041 agent_id = %agent_id,
1042 instance_id = ?key.instance_id,
1043 generation = ?key.generation,
1044 program = %spec.launch.program,
1045 fixed_args = ?spec.launch.fixed_args,
1046 cause = %message,
1047 "provider process failed to start",
1048 );
1049 ControlObservation::SpawnFailed { message }
1050 }
1051 }
1052 }
1053 TransportKind::Pipe => {
1054 let Some(pipe_spec) = spec.capabilities.transports.pipe.as_ref() else {
1055 return ControlObservation::SpawnFailed {
1056 message: format!("agent '{agent_id}' does not support Pipe transport"),
1057 };
1058 };
1059 let prompt = request.initial_prompt.unwrap_or_default();
1060 if pipe_spec.protocol == PipeProtocol::OneShotText {
1061 let Some(binding) = spec.capabilities.adapters.one_shot.as_ref() else {
1062 return ControlObservation::SpawnFailed {
1063 message: format!(
1064 "agent '{agent_id}' does not declare OneShot capability"
1065 ),
1066 };
1067 };
1068 if binding != &pipe_spec.adapter {
1069 return ControlObservation::SpawnFailed {
1070 message: format!(
1071 "agent '{agent_id}' has mismatched OneShot transport bindings"
1072 ),
1073 };
1074 }
1075 return match NativeOneShotSession::spawn_with_environment_and_persistence(
1076 &spec,
1077 binding,
1078 &prompt,
1079 request.session_options.as_ref(),
1080 &working_dir,
1081 &pty_env,
1082 one_shot_session_persistence,
1083 )
1084 .await
1085 {
1086 Ok(session) => {
1087 let process_id = session.process_id();
1088 let events = session.subscribe();
1089 self.one_shot_sessions.insert(
1090 key,
1091 OwnedProviderSession {
1092 source: ProviderSource {
1093 family: AdapterFamily::OneShot,
1094 binding: binding.clone(),
1095 },
1096 session,
1097 events,
1098 pending_events: VecDeque::new(),
1099 pending_provider_events: VecDeque::new(),
1100 next_provider_sequence: 1,
1101 observed_exit_code: None,
1102 runtime_policy,
1103 },
1104 );
1105 ControlObservation::Spawned { process_id }
1106 }
1107 Err(error) => ControlObservation::SpawnFailed {
1108 message: error.to_string(),
1109 },
1110 };
1111 }
1112 let tool = match self
1113 .legacy_adapters
1114 .resolve(AdapterFamily::Pipe, &pipe_spec.adapter)
1115 {
1116 Ok(tool) => *tool,
1117 Err(error) => {
1118 return ControlObservation::SpawnFailed {
1119 message: error.to_string(),
1120 }
1121 }
1122 };
1123 let source = ProviderSource {
1124 family: AdapterFamily::Pipe,
1125 binding: pipe_spec.adapter.clone(),
1126 };
1127 let config = SessionConfig {
1128 tool,
1129 working_dir,
1130 env_vars: Vec::new(),
1131 name: None,
1132 };
1133 if resumed_provider_session.is_some() && pipe_spec.launch_override.is_some() {
1134 return ControlObservation::SpawnFailed {
1135 message: format!(
1136 "agent '{agent_id}' cannot resume through a catalog launch override"
1137 ),
1138 };
1139 }
1140 let mut options = PipeProcessOptions::default();
1141 if let Some(identity) = resumed_provider_session.as_ref() {
1142 options.claude.resume_session_id = Some(identity.id.clone());
1143 }
1144 let spawned = match pipe_spec.launch_override.as_ref() {
1145 Some(launch) => {
1146 PipeSession::spawn_with_launch(
1147 config,
1148 &prompt,
1149 launch,
1150 pipe_spec.prompt_delivery,
1151 )
1152 .await
1153 }
1154 None => {
1155 PipeSession::spawn(config, &prompt, options).await
1156 }
1157 };
1158 match spawned {
1159 Ok(session) => {
1160 let process_id = session.process_id();
1161 let events = session.subscribe();
1162 let pending_events = if pipe_spec.protocol == PipeProtocol::SemanticNdjson {
1163 VecDeque::from([AgentEvent::SessionStart {
1164 session_id: session.session_id().to_owned(),
1165 model: String::new(),
1166 tools: Vec::new(),
1167 }])
1168 } else {
1169 VecDeque::new()
1170 };
1171 self.pipe_sessions.insert(
1172 key,
1173 OwnedProviderSession {
1174 source,
1175 session,
1176 events,
1177 pending_events,
1178 pending_provider_events: VecDeque::new(),
1179 next_provider_sequence: 1,
1180 observed_exit_code: None,
1181 runtime_policy,
1182 },
1183 );
1184 ControlObservation::Spawned { process_id }
1185 }
1186 Err(error) => ControlObservation::SpawnFailed {
1187 message: error.to_string(),
1188 },
1189 }
1190 }
1191 TransportKind::Acp => {
1192 let Some(acp_spec) = spec.capabilities.transports.acp else {
1193 return ControlObservation::SpawnFailed {
1194 message: format!("agent '{agent_id}' does not support ACP transport"),
1195 };
1196 };
1197 let tool = match self
1198 .legacy_adapters
1199 .resolve(AdapterFamily::Acp, &acp_spec.adapter)
1200 {
1201 Ok(tool) => *tool,
1202 Err(error) => {
1203 return ControlObservation::SpawnFailed {
1204 message: error.to_string(),
1205 }
1206 }
1207 };
1208 let source = ProviderSource {
1209 family: AdapterFamily::Acp,
1210 binding: acp_spec.adapter.clone(),
1211 };
1212 let acp_mode_id = match required_acp_mode(&agent_id, request.approval_level) {
1241 Ok(mode_id) => mode_id,
1242 Err(message) => return ControlObservation::SpawnFailed { message },
1243 };
1244 let mcp_servers: Vec<McpServerConfig> =
1253 mcp_servers.iter().map(mcp_server_acp_entry).collect();
1254 if !mcp_servers.is_empty() {
1255 tracing::info!(
1263 agent_id = %agent_id,
1264 instance_id = ?key.instance_id,
1265 mcp_server_names = ?mcp_servers.iter().map(McpServerConfig::name).collect::<Vec<_>>(),
1266 "acp session/new carries {} mcp server(s)",
1267 mcp_servers.len(),
1268 );
1269 }
1270 let mut approval_level_args =
1274 acp_approval_level_args(&agent_id, request.approval_level);
1275 for argument in &instance_extra_args {
1276 approval_level_args.push(argument.to_string_lossy().into_owned());
1277 }
1278 let acp_options = AcpSessionOptions {
1279 host_policy: host_policy_for_approval_level(request.approval_level),
1280 approval_level_args,
1295 defer_permission_requests: defers_permission_requests(
1296 &agent_id,
1297 request.approval_level,
1298 ),
1299 mcp_servers,
1300 ..AcpSessionOptions::default()
1301 };
1302 let spawned = match acp_spec.launch_override.as_ref() {
1303 Some(launch) => {
1304 AcpSession::spawn_with_launch(tool, &working_dir, acp_options, launch)
1305 .await
1306 }
1307 None => AcpSession::spawn(tool, &working_dir, acp_options).await,
1308 };
1309 match spawned {
1310 Ok(session) => {
1311 let events = session.subscribe();
1313 tracing::info!(capabilities = ?session.capability_names(),
1314 "ACP initialize capabilities");
1315 if let Some(identity) = resumed_provider_session.as_ref() {
1316 if !session.supports_load_session() {
1317 let _ = session.kill().await;
1318 return ControlObservation::SpawnFailed {
1319 message: "ACP session/load unsupported".to_owned(),
1320 };
1321 }
1322 if let Err(error) = session.load_session(&identity.id).await {
1323 let _ = session.kill().await;
1324 return ControlObservation::SpawnFailed { message: error.to_string() };
1325 }
1326 }
1327 if let Some(mode_id) = acp_mode_id.as_ref() {
1328 if let Err(message) =
1329 apply_acp_approval_mode(&session, mode_id, request.approval_level)
1330 .await
1331 {
1332 let _ = session.kill().await;
1333 return ControlObservation::SpawnFailed { message };
1334 }
1335 }
1336 let process_id = session.process_id();
1337 let session_id = session
1338 .acp_session_id()
1339 .await
1340 .unwrap_or_else(|| session.session_id().to_owned());
1341 let identity_observed = if runtime_policy.provider_session_identity {
1371 match session.provider_reported_session_id().await {
1372 Some(id) => Some(ProviderEvent::SessionIdentityObserved {
1373 identity: ProviderSessionIdentity {
1374 key: ProviderSessionKey::SessionId,
1375 id,
1376 transcript_path: None,
1377 },
1378 }),
1379 None => {
1380 tracing::warn!(
1381 agent_id = %agent_id,
1382 adapter = %acp_spec.adapter.id,
1383 "ACP session/new returned no sessionId; provider \
1384 session identity stays IdentityPending",
1385 );
1386 None
1387 }
1388 }
1389 } else {
1390 None
1391 };
1392 if let Some(prompt) = request.initial_prompt {
1393 if let Err(error) = session.start_prompt(&prompt).await {
1394 let _ = session.kill().await;
1395 return ControlObservation::SpawnFailed {
1396 message: error.to_string(),
1397 };
1398 }
1399 }
1400 let announced_mode = session.current_mode_id();
1402 self.acp_sessions.insert(
1403 key,
1404 OwnedProviderSession {
1405 source,
1406 session,
1407 events,
1408 pending_events: {
1409 let mut seeded = VecDeque::from([AgentEvent::SessionStart {
1410 session_id,
1411 model: String::new(),
1412 tools: Vec::new(),
1413 }]);
1414 if let Some(mode_id) = announced_mode {
1437 seeded.push_back(AgentEvent::ModeChanged { mode_id });
1438 }
1439 seeded
1440 },
1441 pending_provider_events: VecDeque::from_iter(identity_observed),
1442 next_provider_sequence: 1,
1443 observed_exit_code: None,
1444 runtime_policy,
1445 },
1446 );
1447 ControlObservation::Spawned { process_id }
1448 }
1449 Err(error) => ControlObservation::SpawnFailed {
1450 message: error.to_string(),
1451 },
1452 }
1453 }
1454 }
1455 }
1456
1457 async fn spawn_resume(
1458 &mut self,
1459 key: NativeSessionKey,
1460 operation_id: OperationId,
1461 agent_id: AgentId,
1462 transport: TransportKind,
1463 provider_session: gate4agent_types::ProviderSessionIdentity,
1464 runtime_policy: ProviderRuntimePolicy,
1465 request: ResumeLaunchRequest,
1466 pty_env: Vec<EnvMutation>,
1467 instance_extra_args: Vec<OsString>,
1468 one_shot_session_persistence: OneShotSessionPersistence,
1469 mcp_servers: Vec<McpServerSpec>,
1470 ) -> ControlObservation {
1471 if let Err(message) = validate_spawn_runtime_policy(
1472 runtime_policy,
1473 transport,
1474 request.initial_prompt.is_some(),
1475 true,
1476 ) {
1477 return ControlObservation::SpawnFailed { message };
1478 }
1479 if let Err(error) = request.validate() {
1480 return ControlObservation::SpawnFailed {
1481 message: error.to_string(),
1482 };
1483 }
1484 let Some(spec) = self.catalog.get(&agent_id) else {
1485 return ControlObservation::SpawnFailed {
1486 message: format!("agent '{agent_id}' is absent from native catalog"),
1487 };
1488 };
1489 let Some(binding) = spec.capabilities.adapters.resume.as_ref() else {
1490 return ControlObservation::SpawnFailed {
1491 message: format!("agent '{agent_id}' does not declare Resume capability"),
1492 };
1493 };
1494 let plan = match build_resume_plan_for_identity(&binding.id, &provider_session) {
1495 Ok(Some(plan)) => plan,
1496 Ok(None) => {
1497 return ControlObservation::SpawnFailed {
1498 message: format!("agent '{agent_id}' has no live Resume plan"),
1499 }
1500 }
1501 Err(error) => {
1502 return ControlObservation::SpawnFailed {
1503 message: error.to_string(),
1504 }
1505 }
1506 };
1507 if transport == TransportKind::Pipe {
1508 let Some(pipe) = spec.capabilities.transports.pipe.as_ref() else {
1509 return ControlObservation::SpawnFailed {
1510 message: format!("agent '{agent_id}' does not support Pipe transport"),
1511 };
1512 };
1513 if pipe.protocol != PipeProtocol::StructuredJsonl {
1514 return ControlObservation::SpawnFailed {
1515 message: format!(
1516 "agent '{agent_id}' does not expose a resumable structured Pipe contract"
1517 ),
1518 };
1519 }
1520 }
1521 let start = StartRequest {
1522 working_directory: request.working_directory,
1523 terminal_size: request.terminal_size,
1524 initial_prompt: request.initial_prompt,
1525 session_options: None,
1531 approval_level: ApprovalLevel::default(),
1532 };
1533 self.spawn_native(
1534 key,
1535 operation_id,
1536 NativeSpawnRequest {
1537 agent_id,
1538 transport,
1539 request: start,
1540 runtime_policy,
1541 launch_extra_args: if transport == TransportKind::Pty {
1542 plan.args.into_iter().map(OsString::from).collect()
1543 } else {
1544 Vec::new()
1545 },
1546 instance_extra_args,
1547 resumed_provider_session: Some(provider_session),
1548 one_shot_session_persistence,
1549 },
1550 pty_env,
1551 mcp_servers,
1552 )
1553 .await
1554 }
1555
1556 async fn stop_native(&mut self, key: NativeSessionKey, force: bool) -> ControlObservation {
1557 if let Some(owned) = self.pty_sessions.remove(&key) {
1558 let shutdown = owned.session.shutdown().await;
1559 return match shutdown {
1560 Ok(outcome) => ControlObservation::StopCompleted {
1561 forced: force || outcome.termination.is_some(),
1562 exit_code: outcome.exit_code,
1563 final_terminal: Some(terminal_frame(outcome.terminal, owned.last_screen_state.clone())),
1567 },
1568 Err(error) => {
1569 eprintln!(
1570 "[gate4agent-shell-native] PTY stop failed for {key:?} (force={force}): {error}",
1571 );
1572 ControlObservation::StopFailed {
1573 message: error.to_string(),
1574 }
1575 }
1576 };
1577 }
1578 if let Some(owned) = self.pipe_sessions.remove(&key) {
1579 return match owned.session.stop(force).await {
1592 Ok(outcome) => ControlObservation::StopCompleted {
1593 forced: outcome.forced,
1594 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1595 final_terminal: None,
1596 },
1597 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1598 forced: false,
1599 exit_code: owned.observed_exit_code,
1600 final_terminal: None,
1601 },
1602 Err(error) => ControlObservation::StopFailed {
1603 message: error.to_string(),
1604 },
1605 };
1606 }
1607 if let Some(mut owned) = self.one_shot_sessions.remove(&key) {
1608 return match owned.session.kill().await {
1609 Ok(()) => ControlObservation::StopCompleted {
1610 forced: true,
1611 exit_code: owned.observed_exit_code,
1612 final_terminal: None,
1613 },
1614 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1615 forced: false,
1616 exit_code: owned.observed_exit_code,
1617 final_terminal: None,
1618 },
1619 Err(error) => ControlObservation::StopFailed {
1620 message: error.to_string(),
1621 },
1622 };
1623 }
1624 if let Some(owned) = self.acp_sessions.remove(&key) {
1625 return match owned.session.stop(force).await {
1636 Ok(outcome) => ControlObservation::StopCompleted {
1637 forced: outcome.forced,
1638 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1639 final_terminal: None,
1640 },
1641 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1642 forced: false,
1643 exit_code: owned.observed_exit_code,
1644 final_terminal: None,
1645 },
1646 Err(error) => ControlObservation::StopFailed {
1647 message: error.to_string(),
1648 },
1649 };
1650 }
1651 eprintln!("[gate4agent-shell-native] stop skipped: no session owns {key:?} in any transport map");
1657 ControlObservation::StopFailed {
1658 message: missing_session_message(key),
1659 }
1660 }
1661
1662 fn session_exists(&self, key: NativeSessionKey) -> bool {
1663 self.pty_sessions.contains_key(&key)
1664 || self.pipe_sessions.contains_key(&key)
1665 || self.one_shot_sessions.contains_key(&key)
1666 || self.acp_sessions.contains_key(&key)
1667 }
1668
1669 pub async fn collect_exits(&mut self) -> Vec<ObservationEnvelope> {
1672 let completed: Vec<_> = self
1673 .pty_sessions
1674 .iter()
1675 .filter_map(|(key, owned)| owned.session.reader_finished().then_some(*key))
1676 .collect();
1677 let mut observations = Vec::with_capacity(completed.len());
1678 for key in completed {
1679 let owned = self
1680 .pty_sessions
1681 .remove(&key)
1682 .expect("completed key came from the owned session map");
1683 let last_screen_state = owned.last_screen_state.clone();
1684 let (exit_code, final_terminal) = match owned.session.shutdown().await {
1685 Ok(outcome) => (
1686 outcome.exit_code,
1687 Some(terminal_frame(outcome.terminal, last_screen_state)),
1688 ),
1689 Err(_) => (None, None),
1690 };
1691 observations.push(ObservationEnvelope {
1692 operation_id: None,
1693 instance_id: key.instance_id,
1694 generation: key.generation,
1695 observation: ControlObservation::ProcessExited {
1696 exit_code,
1697 final_terminal,
1698 },
1699 });
1700 }
1701 collect_provider_exits(&mut self.pipe_sessions, &mut observations, |session| {
1702 session.reader_finished()
1703 });
1704 collect_provider_exits(&mut self.one_shot_sessions, &mut observations, |session| {
1705 session.reader_finished()
1706 });
1707 collect_provider_exits(&mut self.acp_sessions, &mut observations, |session| {
1708 session.reader_finished()
1709 });
1710 observations
1711 }
1712
1713 pub fn collect_provider_events(&mut self) -> Vec<ObservationEnvelope> {
1716 let mut observations = self.pending_observations.drain(..).collect::<Vec<_>>();
1717 for (key, owned) in &mut self.pty_sessions {
1718 if let Some(provider) = &mut owned.provider {
1719 drain_pty_provider(*key, provider, &mut observations);
1720 }
1721 }
1722 collect_provider_map(&mut self.pipe_sessions, &mut observations, |_| Vec::new());
1723 collect_provider_map(&mut self.one_shot_sessions, &mut observations, |_| Vec::new());
1724 for owned in self.acp_sessions.values() {
1736 owned.session.expire_deadlines();
1737 }
1738 collect_provider_map(&mut self.acp_sessions, &mut observations, AcpSession::available_modes);
1739 observations
1740 }
1741
1742 pub fn collect_terminal_frames(&mut self) -> Vec<ObservationEnvelope> {
1756 let mut observations = Vec::new();
1757 let pty_sessions = &mut self.pty_sessions;
1763 let efficiency_facts = &mut self.efficiency_facts;
1764 for (key, owned) in pty_sessions {
1765 if terminal_state_capture_should_skip(
1766 owned.session.terminal_sequence(),
1767 owned.last_terminal_sequence,
1768 ) {
1769 efficiency_facts.record_terminal_state_skip();
1770 continue;
1771 }
1772 let capture_start = Instant::now();
1773 let terminal_state = owned.session.terminal_state();
1774 efficiency_facts.record_terminal_state_capture(capture_start.elapsed());
1775 match terminal_state {
1776 Ok(snapshot) if snapshot.sequence > owned.last_terminal_sequence => {
1777 owned.last_terminal_sequence = snapshot.sequence;
1778 owned.terminal_stale_published = false;
1779
1780 owned.last_screen_gate = startup_operator_gate(&snapshot.contents);
1784 owned.last_screen_failure =
1795 screen_failure_for_generation(&snapshot.contents, owned.ever_reached_ready);
1796 let merged = classify_pty_screen_state(
1797 owned.last_foreground_verdict.as_ref(),
1798 owned.last_screen_gate.as_ref(),
1799 owned.last_screen_failure,
1800 );
1801 if !snapshot.contents.trim().is_empty() {
1812 owned.screen_had_content = true;
1813 }
1814 if merged == PtyScreenState::Ready && owned.screen_had_content {
1815 owned.ever_reached_ready = true;
1816 }
1817 if merged != owned.last_screen_state {
1818 if foreground_probe_rearms_immediately(&owned.last_screen_state, &merged) {
1819 owned.next_foreground_probe = Some(Instant::now());
1820 }
1821 owned.last_screen_state = merged.clone();
1822 observations.push(ObservationEnvelope {
1823 operation_id: None,
1824 instance_id: key.instance_id,
1825 generation: key.generation,
1826 observation: ControlObservation::ScreenState {
1827 state: merged.clone(),
1828 },
1829 });
1830 }
1831
1832 let frame = terminal_frame(snapshot, merged);
1833 efficiency_facts.record_terminal_frame_published(terminal_frame_byte_len(&frame));
1834 observations.push(ObservationEnvelope {
1835 operation_id: None,
1836 instance_id: key.instance_id,
1837 generation: key.generation,
1838 observation: ControlObservation::TerminalFrame { frame },
1839 });
1840 }
1841 Ok(_) => {}
1842 Err(error) if !owned.terminal_stale_published => {
1843 owned.terminal_stale_published = true;
1844 observations.push(ObservationEnvelope {
1845 operation_id: None,
1846 instance_id: key.instance_id,
1847 generation: key.generation,
1848 observation: ControlObservation::TerminalStale {
1849 message: error.to_string(),
1850 },
1851 });
1852 }
1853 Err(_) => {}
1854 }
1855 }
1856 observations
1857 }
1858
1859 pub async fn reclassify_foreground(&mut self) -> Vec<ObservationEnvelope> {
1877 let catalog = &self.catalog;
1878 let now = Instant::now();
1879 let due: Vec<NativeSessionKey> = self
1880 .pty_sessions
1881 .iter()
1882 .filter(|(_, owned)| owned.next_foreground_probe.is_some_and(|at| now >= at))
1883 .map(|(key, _)| *key)
1884 .collect();
1885
1886 let mut observations = Vec::new();
1887 for key in due {
1888 let Some(owned) = self.pty_sessions.get_mut(&key) else {
1889 continue;
1890 };
1891 let probe_result = owned.session.observe_foreground_timed().await;
1892 match probe_result {
1893 Ok((observation, timing)) => {
1894 self.efficiency_facts.record_foreground_probe(timing);
1907 let verdict = match catalog.get(&owned.agent_id) {
1908 Some(spec) => resolve_foreground_verdict(
1909 spec,
1910 &observation,
1911 RuntimePlatform::current(),
1912 ),
1913 None => ForegroundVerdict::Foreign {
1919 process: observation.observed_process.clone(),
1920 },
1921 };
1922 owned.last_foreground_verdict = Some(verdict);
1923 let merged = classify_pty_screen_state(
1924 owned.last_foreground_verdict.as_ref(),
1925 owned.last_screen_gate.as_ref(),
1926 owned.last_screen_failure,
1927 );
1928 if merged == PtyScreenState::Ready && owned.screen_had_content {
1933 owned.ever_reached_ready = true;
1934 }
1935 if merged != owned.last_screen_state {
1936 owned.last_screen_state = merged.clone();
1937 observations.push(ObservationEnvelope {
1938 operation_id: None,
1939 instance_id: key.instance_id,
1940 generation: key.generation,
1941 observation: ControlObservation::ScreenState { state: merged },
1942 });
1943 }
1944 owned.next_foreground_probe =
1945 match foreground_probe_schedule(&owned.last_screen_state) {
1946 ForegroundProbeSchedule::Disarmed => None,
1947 ForegroundProbeSchedule::Armed => {
1948 Some(now + FOREGROUND_RECLASSIFY_INTERVAL)
1949 }
1950 };
1951 }
1952 Err(_) => {
1953 owned.next_foreground_probe = Some(now + FOREGROUND_RECLASSIFY_INTERVAL);
1960 }
1961 }
1962 }
1963 observations
1964 }
1965}
1966
1967const PTY_TERM_DEFAULT_KEY: &str = "TERM";
1974const PTY_TERM_DEFAULT_VALUE: &str = "xterm-256color";
1975const PTY_COLORTERM_DEFAULT_KEY: &str = "COLORTERM";
1976const PTY_COLORTERM_DEFAULT_VALUE: &str = "truecolor";
1977
1978fn with_pty_terminal_capability_defaults(mut pty_env: Vec<EnvMutation>) -> Vec<EnvMutation> {
1984 let already_mutated = |env: &[EnvMutation], key: &str| {
1985 env.iter()
1986 .any(|mutation| mutation.key.as_os_str() == OsStr::new(key))
1987 };
1988 if !already_mutated(&pty_env, PTY_TERM_DEFAULT_KEY) {
1989 pty_env.push(EnvMutation {
1990 key: OsString::from(PTY_TERM_DEFAULT_KEY),
1991 value: Some(OsString::from(PTY_TERM_DEFAULT_VALUE)),
1992 });
1993 }
1994 if !already_mutated(&pty_env, PTY_COLORTERM_DEFAULT_KEY) {
1995 pty_env.push(EnvMutation {
1996 key: OsString::from(PTY_COLORTERM_DEFAULT_KEY),
1997 value: Some(OsString::from(PTY_COLORTERM_DEFAULT_VALUE)),
1998 });
1999 }
2000 pty_env
2001}
2002
2003fn missing_session_message(key: NativeSessionKey) -> String {
2004 format!(
2005 "native session {:?}/{:?} does not exist",
2006 key.instance_id, key.generation
2007 )
2008}
2009
2010fn host_policy_for_approval_level(level: ApprovalLevel) -> HostPolicy {
2035 match level {
2036 ApprovalLevel::FullAuto => HostPolicy::Yolo,
2037 ApprovalLevel::ReadOnly => HostPolicy::ReadOnly,
2038 ApprovalLevel::Moderate | ApprovalLevel::Unmanaged => HostPolicy::Auto,
2039 }
2040}
2041
2042fn defers_permission_requests(agent_id: &AgentId, level: ApprovalLevel) -> bool {
2073 match approval_level_resolution(agent_id, level) {
2074 ApprovalLevelResolution::Supported {
2075 asks_for_permission,
2076 ..
2077 } => asks_for_permission,
2078 ApprovalLevelResolution::Unsupported => true,
2079 }
2080}
2081
2082const ACP_MODE_CONFIRMATION_TIMEOUT: Duration = Duration::from_secs(5);
2092
2093fn required_acp_mode(agent_id: &AgentId, level: ApprovalLevel) -> Result<Option<ModeId>, String> {
2110 let (acp_mode_id, carries_argv_flags) = match approval_level_resolution(agent_id, level) {
2111 ApprovalLevelResolution::Unsupported => (None, false),
2112 ApprovalLevelResolution::Supported { acp_mode_id, args, .. } => {
2113 (acp_mode_id, !args.is_empty())
2114 }
2115 };
2116 match (acp_mode_id, level) {
2117 (Some(mode_id), _) => Ok(Some(mode_id)),
2118 (None, ApprovalLevel::Unmanaged) => Ok(None),
2119 (None, _) if carries_argv_flags => Ok(None),
2128 (None, ApprovalLevel::FullAuto) if acp_full_auto_is_host_policy(agent_id) => Ok(None),
2133 (None, _) => Err(format!(
2134 "agent '{agent_id}' has no verified ACP mode for {level:?} and the level carries no \
2135 vendor flags to apply through argv either; refusing rather than launching at the \
2136 vendor's own (wider-authority) default"
2137 )),
2138 }
2139}
2140
2141fn acp_approval_level_args(agent_id: &AgentId, level: ApprovalLevel) -> Vec<String> {
2158 match approval_level_resolution(agent_id, level) {
2159 ApprovalLevelResolution::Supported { args, acp_mode_id: None, .. } => args,
2160 ApprovalLevelResolution::Supported { acp_mode_id: Some(_), .. } => Vec::new(),
2161 ApprovalLevelResolution::Unsupported => Vec::new(),
2162 }
2163}
2164
2165#[derive(Debug)]
2173struct ApprovalLevelNotOfferedByAgent {
2174 level: ApprovalLevel,
2175 offered: Vec<String>,
2176}
2177
2178impl std::fmt::Display for ApprovalLevelNotOfferedByAgent {
2179 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2180 write!(
2181 formatter,
2182 "ApprovalLevelNotOfferedByAgent {{ level: {:?}, offered: {:?} }}",
2183 self.level, self.offered
2184 )
2185 }
2186}
2187
2188fn approval_level_not_offered_message(
2194 level: ApprovalLevel,
2195 mode_id: &ModeId,
2196 offered: &[SessionMode],
2197) -> Option<String> {
2198 if offered.iter().any(|mode| mode.id == mode_id.as_str()) {
2199 None
2200 } else {
2201 Some(
2202 ApprovalLevelNotOfferedByAgent {
2203 level,
2204 offered: offered.iter().map(|mode| mode.id.clone()).collect(),
2205 }
2206 .to_string(),
2207 )
2208 }
2209}
2210
2211async fn apply_acp_approval_mode(
2229 session: &AcpSession,
2230 mode_id: &ModeId,
2231 level: ApprovalLevel,
2232) -> Result<(), String> {
2233 if let Some(message) =
2234 approval_level_not_offered_message(level, mode_id, &session.available_modes())
2235 {
2236 return Err(message);
2237 }
2238
2239 let mut confirmation = session.subscribe();
2242 session
2243 .set_mode(mode_id.as_str())
2244 .await
2245 .map_err(|error| format!("session/set_mode to '{mode_id}' failed: {error}"))?;
2246
2247 let _ = tokio::time::timeout(ACP_MODE_CONFIRMATION_TIMEOUT, async {
2248 loop {
2249 match confirmation.recv().await {
2250 Ok(AgentEvent::ModeChanged { mode_id: changed }) if changed == mode_id.as_str() => {
2251 return;
2252 }
2253 Ok(_) => continue,
2254 Err(_) => return,
2255 }
2256 }
2257 })
2258 .await;
2259
2260 Ok(())
2261}
2262
2263fn validate_spawn_runtime_policy(
2264 policy: ProviderRuntimePolicy,
2265 transport: TransportKind,
2266 has_initial_prompt: bool,
2267 is_resume: bool,
2268) -> Result<(), String> {
2269 policy
2270 .validate()
2271 .map_err(|error| format!("provider runtime policy is invalid: {error}"))?;
2272 if transport != TransportKind::Acp {
2281 require_runtime_capability(policy, ProviderRuntimeCapability::RawPtyLifecycle)?;
2282 if transport != TransportKind::Pty {
2283 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2284 }
2285 if has_initial_prompt {
2286 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2287 require_runtime_capability(policy, ProviderRuntimeCapability::StructuredPrompt)?;
2288 }
2289 if is_resume && has_initial_prompt {
2290 require_runtime_capability(policy, ProviderRuntimeCapability::ProviderSessionIdentity)?;
2291 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticResume)?;
2292 }
2293 }
2294 Ok(())
2295}
2296
2297
2298fn is_codex_config_c_overlay_args(arguments: &[OsString]) -> bool {
2299 if arguments.is_empty() || arguments.len() % 2 != 0 {
2300 return false;
2301 }
2302 arguments.chunks_exact(2).all(|pair| {
2303 pair[0].as_os_str() == "-c"
2304 && pair[1]
2305 .to_str()
2306 .is_some_and(|value| !value.is_empty() && value.contains('=') && !value.contains('\0'))
2307 })
2308}
2309
2310fn validate_instance_launch_arguments(
2311 agent_id: &AgentId,
2312 transport: TransportKind,
2313 arguments: &[OsString],
2314) -> Result<(), String> {
2315 if arguments.is_empty() {
2316 return Ok(());
2317 }
2318 let acp_codex_c_overlay = transport == TransportKind::Acp
2319 && agent_id.as_str() == "codex"
2320 && is_codex_config_c_overlay_args(arguments);
2321 if transport != TransportKind::Pty && !acp_codex_c_overlay {
2322 return Err(
2323 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
2324 .to_owned(),
2325 );
2326 }
2327 if arguments.len() > INSTANCE_LAUNCH_ARGS_MAX {
2328 return Err("native instance launch argument count exceeds its bound".to_owned());
2329 }
2330 let mut total_bytes = 0usize;
2331 for argument in arguments {
2332 let argument = argument.to_string_lossy();
2333 if argument.contains('\0') {
2334 return Err("native instance launch argument is invalid".to_owned());
2335 }
2336 if argument.len() > INSTANCE_LAUNCH_ARG_MAX_BYTES {
2337 return Err("native instance launch argument exceeds its bound".to_owned());
2338 }
2339 total_bytes = total_bytes.saturating_add(argument.len());
2340 if total_bytes > INSTANCE_LAUNCH_ARGS_TOTAL_MAX_BYTES {
2341 return Err("native instance launch argument payload exceeds its bound".to_owned());
2342 }
2343 if agent_id.as_str() == "claude"
2344 && RESERVED_CLAUDE_LAUNCH_FLAGS.iter().any(|reserved| {
2345 argument == *reserved
2346 || (reserved.starts_with("--")
2347 && argument
2348 .strip_prefix(reserved)
2349 .is_some_and(|suffix| suffix.starts_with('=')))
2350 || (reserved.len() == 2
2351 && argument
2352 .strip_prefix(reserved)
2353 .is_some_and(|suffix| {
2354 !suffix.is_empty() && !suffix.starts_with('-')
2355 }))
2356 })
2357 {
2358 return Err(
2359 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
2360 .to_owned(),
2361 );
2362 }
2363 }
2364 Ok(())
2365}
2366
2367fn argument_looks_like_credential(value: &str) -> bool {
2380 const CREDENTIAL_PREFIXES: &[&str] = &["sk-", "sk_", "ghp_", "gho_", "ghs_", "xox", "bearer "];
2381 const CREDENTIAL_MARKERS: &[&str] = &[
2382 "apikey", "api_key", "api-key", "secret", "password", "passwd", "token=",
2383 ];
2384 let lower = value.to_ascii_lowercase();
2385 CREDENTIAL_PREFIXES
2386 .iter()
2387 .any(|prefix| lower.starts_with(prefix))
2388 || CREDENTIAL_MARKERS
2389 .iter()
2390 .any(|marker| lower.contains(marker))
2391 || has_prefixed_hex64_credential_shape(&lower)
2392}
2393
2394fn has_prefixed_hex64_credential_shape(lower: &str) -> bool {
2403 let Some((prefix, digest)) = lower.split_once('_') else {
2404 return false;
2405 };
2406 (2..=8).contains(&prefix.len())
2407 && prefix
2408 .bytes()
2409 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
2410 && digest.len() == 64
2411 && digest
2412 .bytes()
2413 .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
2414}
2415
2416fn redact_provider_argument(value: &OsStr) -> String {
2420 let text = value.to_string_lossy();
2421 if argument_looks_like_credential(&text) {
2422 "[redacted-credential-shaped-argument]".to_owned()
2423 } else {
2424 text.into_owned()
2425 }
2426}
2427
2428fn redact_provider_arguments(values: &[OsString]) -> Vec<String> {
2431 values.iter().map(|value| redact_provider_argument(value)).collect()
2432}
2433
2434fn require_runtime_capability(
2435 policy: ProviderRuntimePolicy,
2436 capability: ProviderRuntimeCapability,
2437) -> Result<(), String> {
2438 if policy.admits(capability) {
2439 Ok(())
2440 } else {
2441 Err(format!(
2442 "provider runtime capability {capability:?} is not admitted"
2443 ))
2444 }
2445}
2446
2447fn should_attach_pty_provider_stream(policy: ProviderRuntimePolicy) -> bool {
2448 policy.semantic_readiness || policy.provider_session_identity
2449}
2450
2451fn should_probe_pty_identity(
2452 policy: ProviderRuntimePolicy,
2453 adapter: Option<&gate4agent_types::AdapterBinding>,
2454 authoritative_identity_present: bool,
2455 expected_adapter: &str,
2456) -> bool {
2457 !authoritative_identity_present
2458 && policy.semantic_readiness
2459 && policy.structured_prompt
2460 && policy.provider_session_identity
2461 && adapter.is_some_and(|adapter| adapter.id.as_str() == expected_adapter)
2462}
2463
2464fn prepare_fresh_pty_provider_session(
2465 adapter: Option<&gate4agent_types::AdapterBinding>,
2466 is_resume: bool,
2467 identity_permitted: bool,
2468 launch_extra_args: &mut Vec<OsString>,
2469) -> Option<ProviderSessionIdentity> {
2470 let adapter = adapter?;
2471 if is_resume || !identity_permitted || adapter.id.as_str() != "claude-code" {
2472 return None;
2473 }
2474 let identity = ProviderSessionIdentity {
2475 key: ProviderSessionKey::SessionId,
2476 id: Uuid::new_v4().to_string(),
2477 transcript_path: None,
2478 };
2479 launch_extra_args.push(OsString::from("--session-id"));
2480 launch_extra_args.push(OsString::from(&identity.id));
2481 Some(identity)
2482}
2483
2484fn drain_pty_provider(
2485 key: NativeSessionKey,
2486 provider: &mut OwnedPtyProvider,
2487 observations: &mut Vec<ObservationEnvelope>,
2488) {
2489 while let Some(event) = provider.pending_events.pop_front() {
2490 push_provider_observation(key, provider, event, observations);
2491 }
2492
2493 loop {
2494 let envelope = match provider.replay.pop_front() {
2495 Some(envelope) => Some(envelope),
2496 None => provider.receiver.try_recv().unwrap_or_default(),
2497 };
2498 let Some(envelope) = envelope else {
2499 break;
2500 };
2501 match envelope.event {
2502 PtyEvent::Output(data) => {
2503 let raw = provider.utf8.push(&data);
2504 if raw.is_empty() {
2505 continue;
2506 }
2507 if provider.semantic_events {
2508 if let Some(info) = provider.rate_limits.detect(&raw) {
2509 push_provider_observation(
2510 key,
2511 provider,
2512 rate_limit_event(info),
2513 observations,
2514 );
2515 }
2516 }
2517 let identity = provider
2518 .kimi_identity
2519 .as_mut()
2520 .and_then(|extractor| extractor.push(&raw));
2521 if let Some(identity) = identity {
2522 if !provider.provider_session_started {
2523 push_provider_observation(
2524 key,
2525 provider,
2526 ProviderEvent::SessionStarted {
2527 session_id: identity.id.clone(),
2528 model: String::new(),
2529 tools: Vec::new(),
2530 },
2531 observations,
2532 );
2533 provider.provider_session_started = true;
2534 }
2535 push_provider_observation(
2536 key,
2537 provider,
2538 ProviderEvent::SessionIdentityObserved { identity },
2539 observations,
2540 );
2541 }
2542 if provider.semantic_events {
2543 let messages = provider
2544 .pipeline
2545 .get_mut()
2546 .unwrap_or_else(|poisoned| poisoned.into_inner())
2547 .process(&raw);
2548 for message in messages {
2549 if let Some(event) = parsed_provider_event(message) {
2550 push_provider_observation(key, provider, event, observations);
2551 }
2552 }
2553 }
2554 }
2555 PtyEvent::DataGap {
2556 from_sequence,
2557 to_sequence,
2558 ..
2559 } => {
2560 provider.utf8.clear();
2561 if let Some(extractor) = &mut provider.kimi_identity {
2562 extractor.reset_stream();
2563 }
2564 provider
2565 .pipeline
2566 .get_mut()
2567 .unwrap_or_else(|poisoned| poisoned.into_inner())
2568 .clear();
2569 let missed = to_sequence
2570 .checked_sub(from_sequence)
2571 .and_then(|difference| difference.checked_add(1));
2572 if let Some((source_sequence, missed)) = missed.and_then(|missed| {
2573 reserve_provider_gap_sequence(&mut provider.next_provider_sequence, missed)
2574 .map(|source_sequence| (source_sequence, missed))
2575 }) {
2576 observations.push(ObservationEnvelope {
2577 operation_id: None,
2578 instance_id: key.instance_id,
2579 generation: key.generation,
2580 observation: ControlObservation::ProviderGap {
2581 source: provider.source.clone(),
2582 source_sequence,
2583 missed,
2584 },
2585 });
2586 }
2587 }
2588 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
2589 push_provider_observation(
2590 key,
2591 provider,
2592 ProviderEvent::Error { message },
2593 observations,
2594 );
2595 }
2596 PtyEvent::Started
2597 | PtyEvent::Resized(_)
2598 | PtyEvent::ForegroundProcess(_)
2599 | PtyEvent::SnapshotAvailable { .. }
2600 | PtyEvent::Exited { .. } => {}
2601 }
2602 }
2603}
2604
2605fn push_provider_observation(
2606 key: NativeSessionKey,
2607 provider: &mut OwnedPtyProvider,
2608 event: ProviderEvent,
2609 observations: &mut Vec<ObservationEnvelope>,
2610) {
2611 let sequence = provider.next_provider_sequence;
2612 provider.next_provider_sequence = provider.next_provider_sequence.saturating_add(1);
2613 observations.push(ObservationEnvelope {
2614 operation_id: None,
2615 instance_id: key.instance_id,
2616 generation: key.generation,
2617 observation: ControlObservation::ProviderEvent {
2618 source: provider.source.clone(),
2619 sequence,
2620 event,
2621 },
2622 });
2623}
2624
2625fn reserve_provider_gap_sequence(next_sequence: &mut u64, missed: u64) -> Option<u64> {
2626 if missed == 0 {
2627 return None;
2628 }
2629 let Some(source_sequence) = missed
2630 .checked_sub(1)
2631 .and_then(|offset| next_sequence.checked_add(offset))
2632 else {
2633 *next_sequence = u64::MAX;
2634 return None;
2635 };
2636 let Some(next) = source_sequence.checked_add(1) else {
2637 *next_sequence = u64::MAX;
2638 return None;
2639 };
2640 *next_sequence = next;
2641 Some(source_sequence)
2642}
2643
2644fn parsed_provider_event(message: ParsedMessage) -> Option<ProviderEvent> {
2645 match message.class {
2646 MessageClass::AiResponse => Some(ProviderEvent::Text {
2647 text: message.content,
2648 is_delta: message.metadata.is_partial,
2649 }),
2650 MessageClass::ThinkingIndicator => Some(ProviderEvent::Thinking {
2651 text: message.content,
2652 }),
2653 MessageClass::Error => Some(ProviderEvent::Error {
2654 message: message.content,
2655 }),
2656 MessageClass::PromptReady => Some(ProviderEvent::Ready),
2657 MessageClass::ToolApproval => Some(ProviderEvent::InteractionRequested {
2658 request_id: None,
2659 interaction_kind: ProviderInteractionKind::Approval,
2660 tool_name: message
2661 .metadata
2662 .tool_name
2663 .unwrap_or_else(|| "unknown".to_owned()),
2664 title: None,
2668 prompt: message.content,
2669 options: Vec::new(),
2670 agent_id: None,
2671 }),
2672 MessageClass::InfoMessage
2673 | MessageClass::UiElement
2674 | MessageClass::UserEcho
2675 | MessageClass::Menu
2676 | MessageClass::Raw => None,
2677 }
2678}
2679
2680fn rate_limit_event(info: gate4agent::core::types::RateLimitInfo) -> ProviderEvent {
2681 ProviderEvent::RateLimited {
2682 limit_type: provider_rate_limit_kind(info.limit_type),
2683 resets_at: info.resets_at.map(|value| value.to_rfc3339()),
2684 usage_percent: info.usage_percent.map(|value| value.to_string()),
2685 raw_message: info.raw_message,
2686 }
2687}
2688
2689fn provider_host_request_decision(decision: HostRequestDecision) -> ProviderHostRequestDecision {
2696 match decision {
2697 HostRequestDecision::Granted { by } => {
2698 ProviderHostRequestDecision::Granted { by: provider_host_decision_authority(by) }
2699 }
2700 HostRequestDecision::Denied { by } => {
2701 ProviderHostRequestDecision::Denied { by: provider_host_decision_authority(by) }
2702 }
2703 HostRequestDecision::Deferred => ProviderHostRequestDecision::Deferred,
2704 }
2705}
2706
2707fn provider_host_decision_authority(by: HostDecisionAuthority) -> ProviderHostDecisionAuthority {
2708 match by {
2709 HostDecisionAuthority::Gate => ProviderHostDecisionAuthority::Gate,
2710 HostDecisionAuthority::Policy => ProviderHostDecisionAuthority::Policy,
2711 HostDecisionAuthority::Operator => ProviderHostDecisionAuthority::Operator,
2712 HostDecisionAuthority::DeadlinePolicy => ProviderHostDecisionAuthority::DeadlinePolicy,
2713 }
2714}
2715
2716fn provider_host_request_outcome(outcome: HostRequestOutcome) -> ProviderHostRequestOutcome {
2724 match outcome {
2725 HostRequestOutcome::Executed => ProviderHostRequestOutcome::Executed,
2726 HostRequestOutcome::Failed { error } => ProviderHostRequestOutcome::Failed { error },
2727 }
2728}
2729
2730fn provider_rate_limit_kind(
2734 limit_type: gate4agent::core::types::RateLimitType,
2735) -> ProviderRateLimitKind {
2736 use gate4agent::core::types::RateLimitType;
2737 match limit_type {
2738 RateLimitType::Session => ProviderRateLimitKind::Session,
2739 RateLimitType::Daily => ProviderRateLimitKind::Daily,
2740 RateLimitType::Weekly => ProviderRateLimitKind::Weekly,
2741 RateLimitType::Unknown => ProviderRateLimitKind::Unknown,
2742 }
2743}
2744
2745fn collect_provider_map<S>(
2751 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2752 observations: &mut Vec<ObservationEnvelope>,
2753 mode_catalogue: impl Fn(&S) -> Vec<SessionMode>,
2754) {
2755 for (key, owned) in sessions {
2756 let available_modes = mode_catalogue(&owned.session);
2757 drain_provider_stream(
2758 *key,
2759 &owned.source,
2760 &mut owned.events,
2761 &mut owned.pending_events,
2762 &mut owned.pending_provider_events,
2763 &mut owned.next_provider_sequence,
2764 Some(&mut owned.observed_exit_code),
2765 observations,
2766 &available_modes,
2767 );
2768 }
2769}
2770
2771fn push_sequenced_provider_event(
2778 key: NativeSessionKey,
2779 source: &ProviderSource,
2780 next_provider_sequence: &mut u64,
2781 observations: &mut Vec<ObservationEnvelope>,
2782 event: ProviderEvent,
2783) {
2784 let sequence = *next_provider_sequence;
2785 *next_provider_sequence = next_provider_sequence.saturating_add(1);
2786 observations.push(ObservationEnvelope {
2787 operation_id: None,
2788 instance_id: key.instance_id,
2789 generation: key.generation,
2790 observation: ControlObservation::ProviderEvent {
2791 source: source.clone(),
2792 sequence,
2793 event,
2794 },
2795 });
2796}
2797
2798fn drain_provider_stream(
2799 key: NativeSessionKey,
2800 source: &ProviderSource,
2801 events: &mut broadcast::Receiver<AgentEvent>,
2802 pending_events: &mut VecDeque<AgentEvent>,
2803 pending_provider_events: &mut VecDeque<ProviderEvent>,
2804 next_provider_sequence: &mut u64,
2805 mut observed_exit_code: Option<&mut Option<i32>>,
2806 observations: &mut Vec<ObservationEnvelope>,
2807 available_modes: &[SessionMode],
2808) {
2809 loop {
2810 if let Some(event) = pending_events.pop_front() {
2820 match event {
2821 AgentEvent::Exited { code } => {
2822 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2823 *exit_code = Some(code);
2824 }
2825 }
2826 event => {
2827 if let Some(event) = provider_event(event, available_modes) {
2828 push_sequenced_provider_event(
2829 key,
2830 source,
2831 next_provider_sequence,
2832 observations,
2833 event,
2834 );
2835 }
2836 }
2837 }
2838 continue;
2839 }
2840 if let Some(event) = pending_provider_events.pop_front() {
2841 push_sequenced_provider_event(key, source, next_provider_sequence, observations, event);
2842 continue;
2843 }
2844 match events.try_recv() {
2845 Ok(AgentEvent::Exited { code }) => {
2846 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2847 *exit_code = Some(code);
2848 }
2849 }
2850 Ok(event) => {
2851 if let Some(event) = provider_event(event, available_modes) {
2852 push_sequenced_provider_event(
2853 key,
2854 source,
2855 next_provider_sequence,
2856 observations,
2857 event,
2858 );
2859 }
2860 }
2861 Err(broadcast::error::TryRecvError::Lagged(missed)) => {
2862 if let Some(source_sequence) =
2863 reserve_provider_gap_sequence(next_provider_sequence, missed)
2864 {
2865 observations.push(ObservationEnvelope {
2866 operation_id: None,
2867 instance_id: key.instance_id,
2868 generation: key.generation,
2869 observation: ControlObservation::ProviderGap {
2870 source: source.clone(),
2871 source_sequence,
2872 missed,
2873 },
2874 });
2875 }
2876 }
2877 Err(broadcast::error::TryRecvError::Empty | broadcast::error::TryRecvError::Closed) => {
2878 break
2879 }
2880 }
2881 }
2882}
2883
2884fn collect_provider_exits<S>(
2885 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2886 observations: &mut Vec<ObservationEnvelope>,
2887 finished: impl Fn(&S) -> bool,
2888) {
2889 let completed: Vec<_> = sessions
2890 .iter()
2891 .filter_map(|(key, owned)| {
2892 (owned.observed_exit_code.is_some() || finished(&owned.session)).then_some(*key)
2893 })
2894 .collect();
2895 for key in completed {
2896 let owned = sessions
2897 .remove(&key)
2898 .expect("completed provider key came from the owned session map");
2899 observations.push(ObservationEnvelope {
2900 operation_id: None,
2901 instance_id: key.instance_id,
2902 generation: key.generation,
2903 observation: ControlObservation::ProcessExited {
2904 exit_code: owned.observed_exit_code,
2905 final_terminal: None,
2906 },
2907 });
2908 }
2909}
2910
2911const RPC_REQUEST_ID_NUMBER_PREFIX: &str = "number:";
2917const RPC_REQUEST_ID_STRING_PREFIX: &str = "string:";
2918
2919fn encode_rpc_request_id(id: &RpcId) -> String {
2931 match id {
2932 RpcId::Number(number) => format!("{RPC_REQUEST_ID_NUMBER_PREFIX}{number}"),
2933 RpcId::String(value) => format!("{RPC_REQUEST_ID_STRING_PREFIX}{value}"),
2934 }
2935}
2936
2937fn decode_rpc_request_id(raw: &str) -> Option<RpcId> {
2942 if let Some(number) = raw.strip_prefix(RPC_REQUEST_ID_NUMBER_PREFIX) {
2943 return number.parse::<u64>().ok().map(RpcId::Number);
2944 }
2945 raw.strip_prefix(RPC_REQUEST_ID_STRING_PREFIX)
2946 .map(|value| RpcId::String(value.to_owned()))
2947}
2948
2949fn resolve_acp_interaction_observation(
2962 session: Option<&AcpSession>,
2963 target: ProviderInteractionTarget,
2964 response: ProviderInteractionResponse,
2965) -> ControlObservation {
2966 let interaction_id = target.interaction_id;
2967 let fail = |message: String| ControlObservation::InteractionResolutionFailed {
2968 interaction_id,
2969 message,
2970 };
2971 let Some(session) = session else {
2972 return fail("semantic interaction resolution requires an ACP session".to_owned());
2973 };
2974 let Some(provider_request_id) = target.provider_request_id.as_deref() else {
2975 return fail("ACP interaction resolution requires a provider request id".to_owned());
2976 };
2977 let Some(id) = decode_rpc_request_id(provider_request_id) else {
2978 return fail(format!(
2979 "ACP interaction resolution request id {provider_request_id:?} is not a valid JSON-RPC id"
2980 ));
2981 };
2982 match resolve_acp_permission_interaction(session, &id, response) {
2983 Ok(()) => ControlObservation::InteractionResolutionCompleted { interaction_id },
2984 Err(message) => fail(message),
2985 }
2986}
2987
2988fn resolve_acp_permission_interaction(
3012 session: &AcpSession,
3013 id: &RpcId,
3014 response: ProviderInteractionResponse,
3015) -> Result<(), String> {
3016 let choice = match response {
3017 ProviderInteractionResponse::ApproveOnce => OperatorPermissionChoice::Approve,
3018 ProviderInteractionResponse::Deny => OperatorPermissionChoice::Reject,
3019 ProviderInteractionResponse::Answer { .. } => {
3020 return Err("ACP permission interactions do not accept free-text answers".to_owned())
3021 }
3022 };
3023 session.resolve_pending_request_as(id, choice).map_err(|error| error.to_string())
3024}
3025
3026async fn set_acp_session_mode_observation(
3039 session: Option<&AcpSession>,
3040 mode_id: String,
3041) -> ControlObservation {
3042 let Some(session) = session else {
3043 return ControlObservation::SessionModeSetFailed {
3044 message: "session mode switch requires an ACP session".to_owned(),
3045 };
3046 };
3047 let catalogue = session.available_modes();
3048 if catalogue.is_empty() {
3049 return ControlObservation::SessionModeSetFailed {
3050 message: "the provider announces no session-mode capability".to_owned(),
3051 };
3052 }
3053 if !catalogue.iter().any(|mode| mode.id == mode_id) {
3054 return ControlObservation::SessionModeSetFailed {
3055 message: format!("the provider never offered mode {mode_id:?}"),
3056 };
3057 }
3058 match session.set_mode(&mode_id).await {
3059 Ok(()) => ControlObservation::SessionModeSet { mode_id },
3060 Err(error) => ControlObservation::SessionModeSetFailed {
3061 message: error.to_string(),
3062 },
3063 }
3064}
3065
3066async fn set_acp_session_config_option_observation(
3082 session: Option<&AcpSession>,
3083 option_id: String,
3084 value_json: String,
3085) -> ControlObservation {
3086 let Some(session) = session else {
3087 return ControlObservation::SessionConfigOptionSetFailed {
3088 message: "session config-option switch requires an ACP session".to_owned(),
3089 };
3090 };
3091 let catalogue = session.config_options();
3092 if catalogue.is_empty() {
3093 return ControlObservation::SessionConfigOptionSetFailed {
3094 message: "the provider announces no session config-option capability".to_owned(),
3095 };
3096 }
3097 if !catalogue.iter().any(|option| option.id == option_id) {
3098 return ControlObservation::SessionConfigOptionSetFailed {
3099 message: format!("the provider never offered config option {option_id:?}"),
3100 };
3101 }
3102 let value = match value_json.parse() {
3103 Ok(value) => value,
3104 Err(error) => {
3105 return ControlObservation::SessionConfigOptionSetFailed {
3106 message: format!("session config option value is not valid JSON: {error}"),
3107 }
3108 }
3109 };
3110 match session.set_config_option(&option_id, value).await {
3111 Ok(()) => ControlObservation::SessionConfigOptionSet { option_id },
3112 Err(error) => ControlObservation::SessionConfigOptionSetFailed {
3113 message: error.to_string(),
3114 },
3115 }
3116}
3117
3118fn set_acp_session_model_observation(
3127 session: Option<&AcpSession>,
3128 model_id: String,
3129) -> ControlObservation {
3130 if session.is_none() {
3131 return ControlObservation::SessionModelSetFailed {
3132 message: "session model switch requires an ACP session".to_owned(),
3133 };
3134 }
3135 ControlObservation::SessionModelSetFailed {
3136 message: format!(
3137 "this provider offers no host-invocable model-switch method (requested model {model_id:?})"
3138 ),
3139 }
3140}
3141
3142fn map_provider_stop_reason(reason: StopReason) -> ProviderStopReason {
3155 match reason {
3156 StopReason::EndTurn => ProviderStopReason::EndTurn,
3157 StopReason::MaxTokens => ProviderStopReason::MaxTokens,
3158 StopReason::MaxTurnRequests => ProviderStopReason::MaxTurnRequests,
3159 StopReason::Refusal => ProviderStopReason::Refusal,
3160 StopReason::Cancelled => ProviderStopReason::Cancelled,
3161 StopReason::Other(value) => ProviderStopReason::Other { value },
3162 StopReason::ProviderError { code, message, vendor_code } => {
3163 ProviderStopReason::ProviderError { code, message, vendor_code }
3164 }
3165 }
3166}
3167
3168fn provider_event(event: AgentEvent, available_modes: &[SessionMode]) -> Option<ProviderEvent> {
3169 match event {
3170 AgentEvent::SessionStart {
3171 session_id,
3172 model,
3173 tools,
3174 } => Some(ProviderEvent::SessionStarted {
3175 session_id,
3176 model,
3177 tools,
3178 }),
3179 AgentEvent::Text { text, is_delta } => Some(ProviderEvent::Text { text, is_delta }),
3180 AgentEvent::Thinking { text } => Some(ProviderEvent::Thinking { text }),
3181 AgentEvent::ToolStart { id, name, input } => Some(ProviderEvent::ToolStarted {
3182 id,
3183 name,
3184 input_json: input.to_string(),
3185 agent_id: None,
3186 }),
3187 AgentEvent::ToolResult {
3188 id,
3189 output,
3190 is_error,
3191 duration_ms,
3192 non_execution_kind,
3193 } => Some(ProviderEvent::ToolCompleted {
3194 id,
3195 output,
3196 is_error,
3197 duration_ms,
3198 agent_id: None,
3199 non_execution_kind,
3200 }),
3201 AgentEvent::TurnComplete {
3202 input_tokens,
3203 output_tokens,
3204 cache_read_tokens,
3205 cache_write_tokens,
3206 reasoning_tokens,
3207 context_window,
3208 is_cumulative,
3209 } => Some(ProviderEvent::TurnCompleted {
3210 usage: TokenUsage {
3211 input_tokens,
3212 output_tokens,
3213 cache_read_tokens,
3214 cache_write_tokens,
3215 reasoning_tokens,
3216 context_window,
3217 },
3218 is_cumulative,
3219 }),
3220 AgentEvent::ContextWindowUsage { usage } => {
3221 Some(ProviderEvent::ContextWindowUsage {
3222 usage: ProviderContextWindowUsage {
3223 uncached_input_tokens: usage.uncached_input_tokens,
3224 cache_read_tokens: usage.cache_read_tokens,
3225 cache_write_tokens: usage.cache_write_tokens,
3226 output_tokens: usage.output_tokens,
3227 unattributed_tokens: usage.unattributed_tokens,
3228 used_tokens: usage.used_tokens,
3229 capacity_tokens: usage.capacity_tokens,
3230 },
3231 })
3232 }
3233 AgentEvent::SessionEnd {
3234 result,
3235 cost_usd,
3236 is_error,
3237 stop_reason,
3238 } => Some(ProviderEvent::SessionEnded {
3239 result,
3240 cost_usd: cost_usd.map(|cost| cost.to_string()),
3241 is_error,
3242 stop_reason: stop_reason.map(map_provider_stop_reason),
3243 }),
3244 AgentEvent::Error { message } => Some(ProviderEvent::Error { message }),
3245 AgentEvent::TurnInterrupted { reason } => {
3255 tracing::warn!(reason = %reason, "acp turn interrupted");
3256 Some(ProviderEvent::TurnInterrupted)
3257 }
3258 AgentEvent::PtyParsed(message) => parsed_provider_event(message),
3259 AgentEvent::PtyReady => Some(ProviderEvent::Ready),
3260 AgentEvent::PtyToolApproval {
3261 tool_name,
3262 description,
3263 } => Some(ProviderEvent::InteractionRequested {
3264 request_id: None,
3265 interaction_kind: ProviderInteractionKind::Approval,
3266 tool_name,
3267 title: None,
3271 prompt: description.unwrap_or_default(),
3272 options: Vec::new(),
3273 agent_id: None,
3274 }),
3275 AgentEvent::RateLimit(info) => Some(rate_limit_event(info)),
3276 AgentEvent::RpcIncomingRequest {
3290 id,
3291 method,
3292 params,
3293 decision,
3294 reason: _,
3298 outcome: _,
3302 } if method == "session/request_permission"
3303 && matches!(decision, HostRequestDecision::Deferred) =>
3304 {
3305 let tool_call = params.as_ref().and_then(|params| params.get("toolCall"));
3306 let field = |name: &str| {
3307 tool_call
3308 .and_then(|tool_call| tool_call.get(name))
3309 .and_then(|value| value.as_str())
3310 .filter(|value| !value.is_empty())
3311 .map(str::to_owned)
3312 };
3313 let title = field("title");
3322 let options: Vec<ProviderInteractionOption> = params
3334 .as_ref()
3335 .and_then(|params| params.get("options"))
3336 .and_then(|options| options.as_array())
3337 .map(|options| {
3338 options
3339 .iter()
3340 .filter_map(|option| {
3341 let option_id = option.get("optionId")?.as_str()?.to_owned();
3342 let name = option.get("name")?.as_str()?.to_owned();
3343 let kind = option.get("kind")?.as_str()?.to_owned();
3344 Some(ProviderInteractionOption { option_id, name, kind })
3345 })
3346 .collect()
3347 })
3348 .unwrap_or_default();
3349 Some(ProviderEvent::InteractionRequested {
3350 request_id: Some(encode_rpc_request_id(&id)),
3351 interaction_kind: ProviderInteractionKind::Approval,
3352 tool_name: field("kind").unwrap_or(method),
3353 title,
3354 prompt: field("title").unwrap_or_default(),
3355 options,
3356 agent_id: None,
3357 })
3358 }
3359 AgentEvent::RpcIncomingRequest {
3360 id: _,
3361 method,
3362 params,
3363 decision,
3364 outcome,
3373 reason,
3374 } => Some(ProviderEvent::HostRequestObserved {
3375 method,
3376 params_json: params.map(|value| value.to_string()).unwrap_or_default(),
3377 decision: provider_host_request_decision(decision),
3378 outcome: provider_host_request_outcome(outcome),
3379 reason,
3380 }),
3381 AgentEvent::RpcNotification { method, params } => {
3382 Some(ProviderEvent::UnrecognizedNotification {
3383 method,
3384 payload_json: params.to_string(),
3385 })
3386 }
3387 AgentEvent::Started { .. } | AgentEvent::Exited { .. } | AgentEvent::PtyRaw { .. } => None,
3388 AgentEvent::UserMessage { text, is_delta } => {
3389 Some(ProviderEvent::UserMessage { text, is_delta })
3390 }
3391 AgentEvent::Plan { steps } => Some(ProviderEvent::Plan {
3392 steps: steps.into_iter().map(provider_plan_step).collect(),
3393 }),
3394 AgentEvent::AvailableCommandsUpdate { commands } => {
3395 Some(ProviderEvent::AvailableCommandsUpdated {
3396 commands: commands
3397 .into_iter()
3398 .map(|command| ProviderAvailableCommand {
3399 name: command.name,
3400 description: command.description,
3401 input_hint: command.input_hint,
3402 })
3403 .collect(),
3404 })
3405 }
3406 AgentEvent::ModeChanged { mode_id } => Some(ProviderEvent::ModeChanged {
3407 mode_id,
3408 available: available_modes.iter().cloned().map(provider_mode_info).collect(),
3409 }),
3410 AgentEvent::SessionInfoUpdate { title } => {
3411 Some(ProviderEvent::SessionInfoUpdated { title })
3412 }
3413 AgentEvent::UsageUpdate {
3414 used_tokens,
3415 context_window,
3416 cost_amount,
3417 cost_currency,
3418 } => Some(ProviderEvent::UsageUpdated {
3419 used_tokens,
3420 context_window,
3421 cost_amount: cost_amount.map(|amount| amount.to_string()),
3422 cost_currency,
3423 }),
3424 AgentEvent::ConfigOptionsUpdate { options } => Some(ProviderEvent::ConfigOptionsUpdated {
3425 options: options.into_iter().map(provider_config_option).collect(),
3426 }),
3427 AgentEvent::ModelsUpdate { .. }
3434 | AgentEvent::ProviderModelChanged { .. }
3435 | AgentEvent::SettingsUpdate { .. }
3436 | AgentEvent::HookExecutionUpdate { .. }
3437 | AgentEvent::McpServersUpdate { .. }
3438 | AgentEvent::McpInitProgress { .. }
3439 | AgentEvent::McpInitialized { .. }
3440 | AgentEvent::AnnouncementsUpdate { .. } => None,
3441 }
3442}
3443
3444fn provider_plan_priority(priority: gate4agent::core::types::PlanStepPriority) -> ProviderPlanPriority {
3448 use gate4agent::core::types::PlanStepPriority;
3449 match priority {
3450 PlanStepPriority::High => ProviderPlanPriority::High,
3451 PlanStepPriority::Medium => ProviderPlanPriority::Medium,
3452 PlanStepPriority::Low => ProviderPlanPriority::Low,
3453 }
3454}
3455
3456fn provider_plan_status(status: gate4agent::core::types::PlanStepStatus) -> ProviderPlanStatus {
3458 use gate4agent::core::types::PlanStepStatus;
3459 match status {
3460 PlanStepStatus::Pending => ProviderPlanStatus::Pending,
3461 PlanStepStatus::InProgress => ProviderPlanStatus::InProgress,
3462 PlanStepStatus::Completed => ProviderPlanStatus::Completed,
3463 }
3464}
3465
3466fn provider_plan_step(step: gate4agent::core::types::PlanStep) -> ProviderPlanStep {
3467 ProviderPlanStep {
3468 content: step.content,
3469 priority: provider_plan_priority(step.priority),
3470 status: provider_plan_status(step.status),
3471 }
3472}
3473
3474fn provider_mode_info(mode: SessionMode) -> ProviderModeInfo {
3478 ProviderModeInfo {
3479 id: mode.id,
3480 name: mode.name,
3481 description: mode.description,
3482 }
3483}
3484
3485fn provider_config_option_kind(
3488 kind: gate4agent::core::types::ConfigOptionKind,
3489) -> ProviderConfigOptionKind {
3490 use gate4agent::core::types::ConfigOptionKind;
3491 match kind {
3492 ConfigOptionKind::Select => ProviderConfigOptionKind::Select,
3493 ConfigOptionKind::Boolean => ProviderConfigOptionKind::Boolean,
3494 ConfigOptionKind::Unknown => ProviderConfigOptionKind::Unknown,
3495 }
3496}
3497
3498fn provider_config_option(option: gate4agent::core::types::ConfigOptionInfo) -> ProviderConfigOption {
3504 ProviderConfigOption {
3505 id: option.id,
3506 name: option.name,
3507 description: option.description,
3508 category: option.category,
3509 kind: provider_config_option_kind(option.kind),
3510 value_json: option.value.to_string(),
3511 choices: option
3512 .choices
3513 .into_iter()
3514 .map(|choice| ProviderConfigChoice {
3515 value_json: choice.value.to_string(),
3516 label: choice.label,
3517 })
3518 .collect(),
3519 }
3520}
3521
3522fn builtin_legacy_adapter_runtimes() -> AdapterRuntimeRegistry<CliTool> {
3523 let definitions = [
3529 ("claude-code", CliTool::ClaudeCode),
3530 ("codex", CliTool::Codex),
3531 ("kimi", CliTool::KimiCode),
3532 ("grok", CliTool::Grok),
3533 ("opencode", CliTool::Opencode),
3534 ("mcode", CliTool::Mcode),
3535 ];
3536 let mut runtimes = AdapterRuntimeRegistry::default();
3537 for (id, tool) in definitions {
3538 for family in [
3539 AdapterFamily::PtySemantic,
3540 AdapterFamily::Pipe,
3541 AdapterFamily::Acp,
3542 ] {
3543 let Some(binding) = builtin_adapter_registry().binding(family, id) else {
3544 continue;
3545 };
3546 runtimes
3547 .insert(family, binding.clone(), tool)
3548 .expect("built-in native adapter runtime must be unique");
3549 }
3550 }
3551
3552 runtimes
3553}
3554
3555fn terminal_frame(snapshot: PtyTerminalSnapshot, screen_state: PtyScreenState) -> TerminalFrame {
3556 TerminalFrame {
3557 sequence: snapshot.sequence,
3558 size: TerminalSize {
3559 rows: snapshot.size.rows,
3560 columns: snapshot.size.cols,
3561 },
3562 cursor_row: snapshot.cursor.0,
3563 cursor_column: snapshot.cursor.1,
3564 contents: snapshot.contents,
3565 formatted: snapshot.formatted,
3566 scrollback_formatted: snapshot.scrollback_formatted,
3567 alternate_screen: snapshot.alternate_screen,
3568 mouse_protocol_enabled: snapshot.mouse_protocol_enabled,
3569 mouse_protocol_encoding: match snapshot.mouse_protocol_encoding {
3570 PtyMouseProtocolEncoding::Default => TerminalMouseProtocolEncoding::Default,
3571 PtyMouseProtocolEncoding::Utf8 => TerminalMouseProtocolEncoding::Utf8,
3572 PtyMouseProtocolEncoding::Sgr => TerminalMouseProtocolEncoding::Sgr,
3573 },
3574 produced_at_unix_ms: snapshot.produced_at_unix_ms,
3577 screen_state,
3578 bracketed_paste: Some(snapshot.bracketed_paste),
3583 }
3584}
3585
3586fn terminal_state_capture_should_skip<E>(sequence: Result<u64, E>, last_captured: u64) -> bool {
3594 matches!(sequence, Ok(sequence) if sequence <= last_captured)
3595}
3596
3597fn terminal_frame_byte_len(frame: &TerminalFrame) -> u64 {
3603 let scrollback_bytes: usize = frame.scrollback_formatted.iter().map(Vec::len).sum();
3604 (frame.formatted.len() + scrollback_bytes) as u64
3605}
3606
3607fn canonical_foreground(
3608 agent_id: AgentId,
3609 observation: &PtyForegroundObservation,
3610) -> ForegroundProcess {
3611 let kind = if observation.readiness.process_name.as_deref() == Some(agent_id.as_str()) {
3612 ForegroundProcessKind::Agent { agent_id }
3613 } else if observation.readiness.is_shell {
3614 ForegroundProcessKind::Shell
3615 } else {
3616 ForegroundProcessKind::Other
3617 };
3618 ForegroundProcess {
3619 root_process_id: observation.root_pid,
3620 process_id: observation.observed_pid,
3621 process_name: observation.observed_process.clone(),
3622 kind,
3623 }
3624}
3625
3626fn completion_observation(
3627 operation_id: OperationId,
3628 instance_id: AgentInstanceId,
3629 generation: SessionGeneration,
3630 observation: ControlObservation,
3631) -> ObservationEnvelope {
3632 ObservationEnvelope {
3633 operation_id: Some(operation_id),
3634 instance_id,
3635 generation,
3636 observation,
3637 }
3638}
3639
3640async fn wait_for_readiness(
3641 session: &PtySession,
3642 spec: &AgentSpec,
3643 intent: ReadinessIntent,
3644 detect_startup_gates: bool,
3645) -> Result<ReadinessPermit, String> {
3646 let started = Instant::now();
3647 let (terminal, attachment) = attach_readiness_boundary(session)?;
3648 let mut receiver = attachment.receiver;
3649 let mut tracker = ReadinessTracker::new(spec, RuntimePlatform::current(), intent);
3650 let mut diagnostics = ReadinessDiagnostics {
3651 draft_signal: Some(spec.readiness.draft_signal),
3652 ..ReadinessDiagnostics::default()
3653 };
3654 seed_readiness_from_terminal(
3655 &terminal,
3656 &mut tracker,
3657 &mut diagnostics,
3658 elapsed_ms(started),
3659 )?;
3660 let interval = Duration::from_millis(spec.readiness.poll_interval_ms.max(1));
3661 let mut next_probe = Instant::now();
3662
3663 for event in attachment.replay {
3664 observe_readiness_event(
3665 &mut tracker,
3666 &mut diagnostics,
3667 event.event,
3668 elapsed_ms(started),
3669 )?;
3670 if detect_startup_gates {
3671 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3672 ensure_no_startup_operator_gate(session, spec)?;
3673 }
3674 }
3675
3676 loop {
3677 if detect_startup_gates {
3678 ensure_no_startup_operator_gate(session, spec)?;
3679 }
3680 if Instant::now() >= next_probe {
3681 let foreground = session
3682 .observe_foreground()
3683 .await
3684 .map_err(|error| error.to_string())?;
3685 diagnostics.observe_foreground(&foreground.readiness);
3686 tracker.observe_foreground(&foreground.readiness, elapsed_ms(started));
3687 next_probe = Instant::now() + interval;
3688 }
3689 tracker.poll(elapsed_ms(started));
3690 if readiness_complete(tracker.status(), &diagnostics)? {
3691 if detect_startup_gates {
3692 ensure_no_startup_operator_gate(session, spec)?;
3693 }
3694 return tracker
3695 .into_permit()
3696 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3697 }
3698
3699 let wait = next_probe.saturating_duration_since(Instant::now());
3700 match tokio::time::timeout(wait, receiver.recv()).await {
3701 Ok(Ok(event)) => {
3702 if matches!(&event.event, PtyEvent::DataGap { .. }) {
3703 let (terminal, attachment) = attach_readiness_boundary(session)?;
3704 receiver = attachment.receiver;
3705 tracker = ReadinessTracker::new(
3706 spec,
3707 RuntimePlatform::current(),
3708 intent,
3709 );
3710 diagnostics = ReadinessDiagnostics {
3711 draft_signal: Some(spec.readiness.draft_signal),
3712 ..ReadinessDiagnostics::default()
3713 };
3714 seed_readiness_from_terminal(
3715 &terminal,
3716 &mut tracker,
3717 &mut diagnostics,
3718 elapsed_ms(started),
3719 )?;
3720 for retained in attachment.replay {
3721 observe_readiness_event(
3722 &mut tracker,
3723 &mut diagnostics,
3724 retained.event,
3725 elapsed_ms(started),
3726 )?;
3727 }
3728 } else {
3729 observe_readiness_event(
3730 &mut tracker,
3731 &mut diagnostics,
3732 event.event,
3733 elapsed_ms(started),
3734 )?;
3735 }
3736 if detect_startup_gates {
3737 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3738 ensure_no_startup_operator_gate(session, spec)?;
3739 }
3740 }
3741 Ok(Err(error)) => return Err(error.to_string()),
3742 Err(_) => {
3743 tracker.poll(elapsed_ms(started));
3744 }
3745 }
3746 if readiness_complete(tracker.status(), &diagnostics)? {
3747 if detect_startup_gates {
3748 ensure_no_startup_operator_gate(session, spec)?;
3749 }
3750 return tracker
3751 .into_permit()
3752 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3753 }
3754 }
3755}
3756
3757fn attach_readiness_boundary(
3758 session: &PtySession,
3759) -> Result<(PtyTerminalSnapshot, PtyAttachment), String> {
3760 let terminal = session.terminal_state().map_err(|error| error.to_string())?;
3761 let cursor = PtyReplayCursor {
3762 provider_revision: terminal.provider_revision.clone(),
3763 generation: terminal.generation,
3764 next_sequence: terminal.sequence.saturating_add(1).max(1),
3765 };
3766 let attachment = session
3767 .attach_events(cursor)
3768 .map_err(|error| error.to_string())?;
3769 Ok((terminal, attachment))
3770}
3771
3772fn seed_readiness_from_terminal(
3773 terminal: &PtyTerminalSnapshot,
3774 tracker: &mut ReadinessTracker<'_>,
3775 diagnostics: &mut ReadinessDiagnostics,
3776 elapsed_ms: u64,
3777) -> Result<(), String> {
3778 const ENABLE_BRACKETED_PASTE: &[u8] = b"\x1b[?2004h";
3779 if terminal.bracketed_paste {
3780 diagnostics.observe_output(ENABLE_BRACKETED_PASTE);
3781 tracker.observe_output(ENABLE_BRACKETED_PASTE, elapsed_ms);
3782 }
3783 if !terminal.formatted.is_empty() {
3784 diagnostics.observe_output(&terminal.formatted);
3785 tracker.observe_output(&terminal.formatted, elapsed_ms);
3786 }
3787 Ok(())
3788}
3789
3790const STARTUP_GATE_SETTLE_MS: u64 = 350;
3791const STARTUP_GATE_POLL_MS: u64 = 25;
3792const FOREGROUND_RECLASSIFY_INTERVAL: Duration = Duration::from_secs(1);
3806const CODEX_PASTE_ENTER_SUPPRESSION_MS: u64 = 120;
3810const CODEX_POST_RENDER_MARGIN_MS: u64 = 30;
3811const CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3812const KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3813
3814async fn probe_fresh_codex_session_identity(
3815 session: &PtySession,
3816 spec: &AgentSpec,
3817) -> Result<Option<ProviderSessionIdentity>, String> {
3818 let permit = match wait_for_readiness(session, spec, ReadinessIntent::DraftPaste, true).await {
3819 Ok(permit) => permit,
3820 Err(_) => return Ok(None),
3821 };
3822 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3823 return Ok(None);
3824 }
3825 let baseline = session
3826 .terminal_state()
3827 .map_err(|error| error.to_string())?;
3828 let mut extractor = CodexPtySessionIdentityExtractor::default();
3829 session
3830 .send_input_action(
3831 InputAction::AgentCommand(AgentCommand {
3832 agent_id: spec.id.clone(),
3833 name: "status".to_owned(),
3834 arguments: Vec::new(),
3835 }),
3836 permit,
3837 )
3838 .await
3839 .map_err(|error| format!("Codex /status identity probe failed: {error}"))?;
3840
3841 let deadline = Instant::now()
3842 + Duration::from_millis(
3843 spec.readiness
3844 .timeout_ms
3845 .min(CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS)
3846 .max(1),
3847 );
3848 loop {
3849 let snapshot = session
3850 .terminal_state()
3851 .map_err(|error| error.to_string())?;
3852 if snapshot.sequence > baseline.sequence {
3853 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3854 return Ok(Some(identity));
3855 }
3856 }
3857 if Instant::now() >= deadline {
3858 return Ok(None);
3859 }
3860 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3861 }
3862}
3863
3864async fn probe_fresh_kimi_session_identity(
3865 session: &PtySession,
3866 spec: &AgentSpec,
3867) -> Result<Option<ProviderSessionIdentity>, String> {
3868 let permit = match wait_for_readiness(
3869 session,
3870 spec,
3871 ReadinessIntent::FollowupPrompt,
3872 true,
3873 )
3874 .await
3875 {
3876 Ok(permit) => permit,
3877 Err(_) => return Ok(None),
3878 };
3879 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3880 return Ok(None);
3881 }
3882 let baseline = session
3883 .terminal_state()
3884 .map_err(|error| error.to_string())?;
3885 let mut extractor = KimiPtySessionIdentityExtractor::default();
3886 if let Some(identity) = extractor.observe_screen(&baseline.contents) {
3887 return Ok(Some(identity));
3888 }
3889 session
3890 .send_input_action(
3891 InputAction::SubmitPrompt(PromptPayload {
3892 text: "/status".to_owned(),
3893 framing: PromptFraming::BracketedPaste,
3894 }),
3895 permit,
3896 )
3897 .await
3898 .map_err(|error| format!("Kimi /status identity probe failed: {error}"))?;
3899
3900 let deadline = Instant::now()
3901 + Duration::from_millis(
3902 spec.readiness
3903 .timeout_ms
3904 .min(KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS)
3905 .max(1),
3906 );
3907 loop {
3908 let snapshot = session
3909 .terminal_state()
3910 .map_err(|error| error.to_string())?;
3911 if snapshot.sequence > baseline.sequence {
3912 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3913 return Ok(Some(identity));
3914 }
3915 }
3916 if Instant::now() >= deadline {
3917 return Ok(None);
3918 }
3919 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3920 }
3921}
3922
3923async fn deliver_pending_initial_prompt(
3924 session: &mut PtySession,
3925 spec: &AgentSpec,
3926) -> Result<(), String> {
3927 if session.pending_followup_prompt().is_none() {
3928 return Ok(());
3929 }
3930 let mut permit =
3931 wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3932 wait_for_startup_operator_gate(session, spec).await?;
3933 let render_confirmed_submit = spec.id.as_str() == "claude"
3934 || (RuntimePlatform::current() == RuntimePlatform::Windows
3935 && spec.id.as_str() == "codex");
3936 if render_confirmed_submit {
3937 let prompt = session
3938 .pending_followup_prompt()
3939 .ok_or_else(|| "deferred initial prompt disappeared before paste".to_owned())?
3940 .to_owned();
3941 let baseline = session
3942 .terminal_state()
3943 .map_err(|error| error.to_string())?;
3944 let inserted = session
3945 .insert_pending_followup_prompt(PromptFraming::BracketedPaste, &permit)
3946 .await
3947 .map_err(|error| error.to_string())?;
3948 if !inserted {
3949 return Err("deferred initial prompt was not inserted".to_owned());
3950 }
3951 wait_for_prompt_render(
3952 session,
3953 spec,
3954 &prompt,
3955 &baseline,
3956 spec.readiness.timeout_ms,
3957 )
3958 .await?;
3959 if RuntimePlatform::current() == RuntimePlatform::Windows && spec.id.as_str() == "codex" {
3960 tokio::time::sleep(Duration::from_millis(
3961 CODEX_PASTE_ENTER_SUPPRESSION_MS + CODEX_POST_RENDER_MARGIN_MS,
3962 ))
3963 .await;
3964 }
3965 permit = wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3966 wait_for_startup_operator_gate(session, spec).await?;
3967 }
3968 ensure_no_startup_operator_gate(session, spec)?;
3969 let submitted = session
3970 .submit_pending_followup(PromptFraming::BracketedPaste, permit)
3971 .await
3972 .map_err(|error| error.to_string())?;
3973 if !submitted {
3974 return Err("deferred initial prompt disappeared before delivery".to_owned());
3975 }
3976 Ok(())
3977}
3978
3979async fn wait_for_prompt_render(
3980 session: &PtySession,
3981 spec: &AgentSpec,
3982 prompt: &str,
3983 baseline: &PtyTerminalSnapshot,
3984 timeout_ms: u64,
3985) -> Result<(), String> {
3986 let probe = prompt_render_probe(&gate4agent_types::sanitize_prompt_text(prompt));
3987 let deadline = Instant::now() + Duration::from_millis(timeout_ms.max(1));
3988 loop {
3989 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
3990 if let Some(gate) = startup_operator_gate(&snapshot.contents) {
3991 return Err(startup_operator_error(spec, &gate));
3992 }
3993 if prompt_rendered(&snapshot, baseline, &probe) {
3994 return Ok(());
3995 }
3996 if Instant::now() >= deadline {
3997 let tail = terminal_tail(&snapshot.contents);
3998 let compact_tail = compact_alphanumeric(&tail);
3999 let baseline_tail = terminal_tail(&baseline.contents).to_ascii_lowercase();
4000 let normalized_tail = tail.to_ascii_lowercase();
4001 let retained = render_ack_event_summary(session, baseline.sequence);
4002 let foreground = session.observe_foreground().await.ok();
4003 let foreground_name = foreground
4004 .as_ref()
4005 .and_then(|observation| observation.readiness.process_name.as_deref())
4006 .map(safe_process_label)
4007 .unwrap_or_else(|| "none".to_owned());
4008 let child_live = retained.exit_code.is_none() && foreground.is_some();
4009 return Err(format!(
4010 "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={})",
4011 spec.id,
4012 baseline.sequence,
4013 snapshot.sequence,
4014 snapshot.sequence.saturating_sub(baseline.sequence),
4015 snapshot.cursor != baseline.cursor,
4016 baseline.bracketed_paste,
4017 snapshot.bracketed_paste,
4018 tail.chars().count(),
4019 probe.chars().count(),
4020 !probe.is_empty() && compact_tail.contains(&probe),
4021 paste_placeholder_visible(&baseline_tail),
4022 paste_placeholder_visible(&normalized_tail),
4023 child_live,
4024 foreground_name,
4025 retained.output,
4026 retained.foreground,
4027 retained.snapshots,
4028 retained.resized,
4029 retained.gaps,
4030 retained.reader_errors,
4031 retained.operator_actions,
4032 retained
4033 .exit_code
4034 .map_or_else(|| "none".to_owned(), |code| code.to_string()),
4035 if retained.output_flags.is_empty() {
4036 "none".to_owned()
4037 } else {
4038 retained.output_flags.join(",")
4039 },
4040 ));
4041 }
4042 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
4043 }
4044}
4045
4046#[derive(Default)]
4047struct RenderAckEventSummary {
4048 output: usize,
4049 foreground: usize,
4050 snapshots: usize,
4051 resized: usize,
4052 gaps: usize,
4053 reader_errors: usize,
4054 operator_actions: usize,
4055 exit_code: Option<i32>,
4056 output_flags: Vec<&'static str>,
4057}
4058
4059fn render_ack_event_summary(session: &PtySession, baseline_sequence: u64) -> RenderAckEventSummary {
4060 let mut summary = RenderAckEventSummary::default();
4061 let Ok(attachment) = session.attach_retained_events() else {
4062 return summary;
4063 };
4064 for envelope in attachment
4065 .replay
4066 .into_iter()
4067 .filter(|envelope| envelope.sequence > baseline_sequence)
4068 {
4069 match envelope.event {
4070 PtyEvent::Output(bytes) => {
4071 summary.output = summary.output.saturating_add(1);
4072 observe_render_ack_output_flags(&mut summary.output_flags, &bytes);
4073 }
4074 PtyEvent::ForegroundProcess(_) => {
4075 summary.foreground = summary.foreground.saturating_add(1);
4076 }
4077 PtyEvent::SnapshotAvailable { .. } => {
4078 summary.snapshots = summary.snapshots.saturating_add(1);
4079 }
4080 PtyEvent::Resized(_) => {
4081 summary.resized = summary.resized.saturating_add(1);
4082 }
4083 PtyEvent::DataGap { .. } => {
4084 summary.gaps = summary.gaps.saturating_add(1);
4085 }
4086 PtyEvent::ReaderError { .. } => {
4087 summary.reader_errors = summary.reader_errors.saturating_add(1);
4088 }
4089 PtyEvent::OperatorActionRequired { .. } => {
4090 summary.operator_actions = summary.operator_actions.saturating_add(1);
4091 }
4092 PtyEvent::Exited { code } => summary.exit_code = Some(code),
4093 PtyEvent::Started => {}
4094 }
4095 }
4096 summary
4097}
4098
4099fn observe_render_ack_output_flags(flags: &mut Vec<&'static str>, bytes: &[u8]) {
4100 let normalized = String::from_utf8_lossy(bytes).to_ascii_lowercase();
4101 for (label, marker) in [
4102 ("error", "error"),
4103 ("panic", "panic"),
4104 ("fatal", "fatal"),
4105 ("login", "login"),
4106 ("auth", "auth"),
4107 ("permission", "permission"),
4108 ("rate-limit", "rate limit"),
4109 ("usage-limit", "usage limit"),
4110 ("update", "update"),
4111 ("working", "working"),
4112 ("thinking", "thinking"),
4113 ] {
4114 if normalized.contains(marker) && !flags.contains(&label) {
4115 flags.push(label);
4116 }
4117 }
4118}
4119
4120fn safe_process_label(process_name: &str) -> String {
4121 process_name
4122 .chars()
4123 .take(64)
4124 .map(|character| {
4125 if character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | '-') {
4126 character
4127 } else {
4128 '?'
4129 }
4130 })
4131 .collect()
4132}
4133
4134fn prompt_rendered(
4135 snapshot: &PtyTerminalSnapshot,
4136 baseline: &PtyTerminalSnapshot,
4137 probe: &str,
4138) -> bool {
4139 if snapshot.sequence <= baseline.sequence {
4140 return false;
4141 }
4142 let tail = terminal_tail(&snapshot.contents);
4143 let compact = compact_alphanumeric(&tail);
4144 if !probe.is_empty() && compact.contains(probe) {
4145 return true;
4146 }
4147 let normalized_tail = tail.to_ascii_lowercase();
4148 let normalized_baseline = terminal_tail(&baseline.contents).to_ascii_lowercase();
4149 paste_placeholder_visible(&normalized_tail)
4150 && !paste_placeholder_visible(&normalized_baseline)
4151}
4152
4153fn paste_placeholder_visible(normalized_tail: &str) -> bool {
4154 normalized_tail.contains("[pasted content")
4158 || normalized_tail.contains("[pasted text #")
4159}
4160
4161fn terminal_tail(contents: &str) -> String {
4162 let mut lines = contents.lines().rev().take(12).collect::<Vec<_>>();
4163 lines.reverse();
4164 lines.join("\n")
4165}
4166
4167fn prompt_render_probe(prompt: &str) -> String {
4168 let compact = compact_alphanumeric(prompt);
4169 let chars = compact.chars().collect::<Vec<_>>();
4170 chars[chars.len().saturating_sub(32)..].iter().collect()
4171}
4172
4173fn compact_alphanumeric(value: &str) -> String {
4174 value
4175 .chars()
4176 .filter(|character| character.is_alphanumeric())
4177 .flat_map(char::to_lowercase)
4178 .collect()
4179}
4180
4181async fn wait_for_startup_operator_gate(
4182 session: &PtySession,
4183 spec: &AgentSpec,
4184) -> Result<(), String> {
4185 let deadline = Instant::now() + Duration::from_millis(STARTUP_GATE_SETTLE_MS);
4186 loop {
4187 ensure_no_startup_operator_gate(session, spec)?;
4188 let now = Instant::now();
4189 if now >= deadline {
4190 return Ok(());
4191 }
4192 tokio::time::sleep(
4193 deadline
4194 .saturating_duration_since(now)
4195 .min(Duration::from_millis(STARTUP_GATE_POLL_MS)),
4196 )
4197 .await;
4198 }
4199}
4200
4201fn ensure_no_startup_operator_gate(session: &PtySession, spec: &AgentSpec) -> Result<(), String> {
4221 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
4222 match startup_operator_gate(&snapshot.contents) {
4223 Some(gate) => Err(startup_operator_error(spec, &gate)),
4224 None => Ok(()),
4225 }
4226}
4227
4228fn startup_operator_error(spec: &AgentSpec, gate: &OperatorGateState) -> String {
4229 format!(
4230 "agent '{}' requires operator action at startup ({gate}); initial prompt was not submitted",
4231 spec.id
4232 )
4233}
4234
4235fn ensure_no_readiness_operator_gate(
4236 diagnostics: &ReadinessDiagnostics,
4237 spec: &AgentSpec,
4238) -> Result<(), String> {
4239 match &diagnostics.operator_gate {
4240 Some(gate) => Err(startup_operator_error(spec, gate)),
4241 None => Ok(()),
4242 }
4243}
4244
4245fn normalize_screen_text(contents: &str) -> String {
4252 contents
4253 .split_whitespace()
4254 .collect::<Vec<_>>()
4255 .join(" ")
4256 .to_ascii_lowercase()
4257}
4258
4259const PACKAGE_MANAGER_INSTALL_MARKERS: &[&str] = &[
4265 "npm install -g",
4266 "npm i -g",
4267 "npm update -g",
4268 "pip install --upgrade",
4269 "pip install -u",
4270 "yarn global add",
4271 "pnpm add -g",
4272];
4273
4274const PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS: &[&str] = &[
4280 "update ran successfully",
4281 "please restart",
4282 "update complete",
4283 "updated successfully",
4284];
4285
4286fn operator_gate(kind: OperatorGateKind, subject: OperatorGateSubject, contents: &str) -> OperatorGateState {
4297 let (input, options) = parse_operator_gate_options(contents);
4298 OperatorGateState::new(kind)
4299 .with_subject(subject)
4300 .with_options(input, options)
4301}
4302
4303fn startup_operator_gate(contents: &str) -> Option<OperatorGateState> {
4304 let normalized = normalize_screen_text(contents);
4305 if [
4306 "trust this folder",
4307 "trust the files in this folder",
4308 "trust the contents of this directory",
4309 "do you trust this directory",
4310 ]
4311 .iter()
4312 .any(|marker| normalized.contains(marker))
4313 {
4314 return Some(operator_gate(
4315 OperatorGateKind::WorkspaceTrust,
4316 OperatorGateSubject::Directory { path: None },
4317 contents,
4318 ));
4319 }
4320 if normalized.contains("quick safety check")
4321 && (normalized.contains("yes, i trust this folder")
4322 || normalized.contains("continue without these permissions"))
4323 {
4324 return Some(operator_gate(
4325 OperatorGateKind::WorkspaceTrust,
4326 OperatorGateSubject::Directory { path: None },
4327 contents,
4328 ));
4329 }
4330 if normalized.contains("hooks need review") && normalized.contains("continue without trusting")
4345 {
4346 return Some(operator_gate(
4347 OperatorGateKind::HookTrust,
4348 OperatorGateSubject::Hooks { count: None },
4349 contents,
4350 ));
4351 }
4352 if [
4353 "select authentication method",
4354 "choose how to authenticate",
4355 "no auth type is selected",
4356 ]
4357 .iter()
4358 .any(|marker| normalized.contains(marker))
4359 {
4360 return Some(operator_gate(
4361 OperatorGateKind::Authentication,
4362 OperatorGateSubject::Account,
4363 contents,
4364 ));
4365 }
4366 if normalized.contains("sign in")
4367 && (normalized.contains("openai")
4368 || normalized.contains("chatgpt")
4369 || normalized.contains("codex"))
4370 {
4371 return Some(operator_gate(
4372 OperatorGateKind::Authentication,
4373 OperatorGateSubject::Account,
4374 contents,
4375 ));
4376 }
4377 if normalized.contains("select login method") {
4386 return Some(operator_gate(
4387 OperatorGateKind::Authentication,
4388 OperatorGateSubject::Account,
4389 contents,
4390 ));
4391 }
4392 if normalized.contains("sign in") && normalized.contains("paste code") {
4404 return Some(
4405 OperatorGateState::new(OperatorGateKind::Authentication)
4406 .with_subject(OperatorGateSubject::Account)
4407 .with_options(OperatorGateInput::TextEntry, Vec::new()),
4408 );
4409 }
4410 if normalized.contains("kimi code update available")
4411 && normalized.contains("install update now")
4412 {
4413 return Some(operator_gate(
4414 OperatorGateKind::VendorUpdate,
4415 OperatorGateSubject::Unknown,
4416 contents,
4417 ));
4418 }
4419 if PACKAGE_MANAGER_INSTALL_MARKERS
4430 .iter()
4431 .any(|marker| normalized.contains(marker))
4432 && PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS
4433 .iter()
4434 .any(|marker| normalized.contains(marker))
4435 {
4436 return Some(operator_gate(
4437 OperatorGateKind::VendorUpdate,
4438 OperatorGateSubject::Unknown,
4439 contents,
4440 ));
4441 }
4442 if normalized.contains("choose the text style that looks best with your terminal") {
4443 return Some(operator_gate(
4444 OperatorGateKind::TerminalAppearance,
4445 OperatorGateSubject::Appearance,
4446 contents,
4447 ));
4448 }
4449 if normalized.contains("welcome to claude code for")
4450 && (normalized.contains("open files") || normalized.contains("selected lines"))
4451 {
4452 return Some(operator_gate(
4453 OperatorGateKind::Onboarding,
4454 OperatorGateSubject::Unknown,
4455 contents,
4456 ));
4457 }
4458 if normalized.contains("welcome to claude code")
4459 && (normalized.contains("press enter") || normalized.contains("enter to continue"))
4460 {
4461 return Some(operator_gate(
4462 OperatorGateKind::Onboarding,
4463 OperatorGateSubject::Unknown,
4464 contents,
4465 ));
4466 }
4467 if normalized.contains("migration") && normalized.contains("enter confirm") && normalized.contains("esc")
4468 {
4469 return Some(operator_gate(
4470 OperatorGateKind::ConfigurationMigration,
4471 OperatorGateSubject::Unknown,
4472 contents,
4473 ));
4474 }
4475 None
4476}
4477
4478fn parse_operator_gate_options(contents: &str) -> (OperatorGateInput, Vec<OperatorGateOption>) {
4500 let numbered: Vec<OperatorGateOption> = contents
4501 .lines()
4502 .filter_map(parse_numbered_gate_option_line)
4503 .take(OPERATOR_GATE_OPTIONS_MAX)
4504 .collect();
4505 if !numbered.is_empty() {
4506 return (OperatorGateInput::NumberedList, numbered);
4507 }
4508 let arrow: Vec<OperatorGateOption> = contents
4509 .lines()
4510 .filter_map(parse_arrow_gate_option_line)
4511 .take(OPERATOR_GATE_OPTIONS_MAX)
4512 .collect();
4513 if !arrow.is_empty() {
4514 return (OperatorGateInput::ArrowList, arrow);
4515 }
4516 (OperatorGateInput::Unknown, Vec::new())
4517}
4518
4519const GATE_CURSOR_GLYPHS: [char; 2] = ['\u{203a}', '\u{276f}'];
4533
4534fn parse_numbered_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4535 let trimmed = line.trim_start();
4536 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4544 Some(stripped) => (true, stripped.trim_start()),
4545 None => (false, trimmed),
4546 };
4547 let digits_end = rest.find(|character: char| !character.is_ascii_digit()).unwrap_or(0);
4548 if digits_end == 0 {
4549 return None;
4550 }
4551 let text = rest[digits_end..].strip_prefix('.')?.trim();
4552 if text.is_empty() {
4553 return None;
4554 }
4555 Some(OperatorGateOption {
4556 semantics: classify_operator_gate_option_semantics(text),
4557 text: text.to_owned(),
4558 selected,
4559 })
4560}
4561
4562fn parse_arrow_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4586 let trimmed = line.trim();
4587 if trimmed.is_empty()
4588 || trimmed
4589 .chars()
4590 .any(|character| matches!(character, '.' | '?' | '!' | ':'))
4591 {
4592 return None;
4593 }
4594 let lower = trimmed.to_ascii_lowercase();
4595 if lower.contains('\u{2191}') || lower.contains('\u{2193}') || lower.contains("navigate") {
4596 return None;
4597 }
4598 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4599 Some(stripped) => (true, stripped.trim()),
4600 None => (false, trimmed),
4601 };
4602 if rest.is_empty() || !rest.chars().any(|character| character.is_alphabetic()) {
4603 return None;
4604 }
4605 let semantics = classify_operator_gate_option_semantics(rest);
4606 if !selected && semantics == OperatorGateOptionSemantics::Unknown {
4607 return None;
4608 }
4609 Some(OperatorGateOption {
4610 semantics,
4611 text: rest.to_owned(),
4612 selected,
4613 })
4614}
4615
4616fn classify_operator_gate_option_semantics(text: &str) -> OperatorGateOptionSemantics {
4624 let lower = text.to_ascii_lowercase();
4625 if lower.contains("review") {
4626 OperatorGateOptionSemantics::Inspect
4627 } else if lower.contains("don't trust")
4628 || lower.contains("do not trust")
4629 || lower.contains("without trusting")
4630 || lower.contains("decline")
4631 {
4632 OperatorGateOptionSemantics::Decline
4633 } else if lower.contains("trust") || lower.contains("continue") || lower.contains("proceed") {
4634 OperatorGateOptionSemantics::Accept
4635 } else if lower.contains("exit") || lower.contains("quit") || lower.contains("cancel") {
4636 OperatorGateOptionSemantics::Exit
4637 } else {
4638 OperatorGateOptionSemantics::Unknown
4639 }
4640}
4641
4642fn looks_like_shell_prompt_line(line: &str) -> bool {
4647 matches!(line.trim_end().chars().last(), Some('$' | '%' | '#' | '>'))
4648}
4649
4650fn screen_failure(contents: &str) -> Option<&'static str> {
4673 let normalized = normalize_screen_text(contents);
4674
4675 if ["panicked at", "unhandled exception", "traceback (most recent call last)"]
4684 .iter()
4685 .any(|marker| normalized.contains(marker))
4686 {
4687 return Some("crash");
4688 }
4689
4690 if normalized.contains("command not found")
4696 || normalized.contains("is not recognized as an internal or external command")
4697 || (normalized.contains("no such file or directory")
4698 && contents.lines().any(looks_like_shell_prompt_line))
4699 {
4700 return Some("missing command");
4701 }
4702
4703 if normalized.contains("api key required") && normalized.contains("grok_api_key") {
4714 return Some("missing api key");
4715 }
4716
4717 None
4718}
4719
4720fn screen_failure_for_generation(contents: &str, ever_reached_ready: bool) -> Option<&'static str> {
4727 if ever_reached_ready {
4728 None
4729 } else {
4730 screen_failure(contents)
4731 }
4732}
4733
4734#[derive(Clone, Debug, Eq, PartialEq)]
4737enum ForegroundVerdict {
4738 Agent,
4740 Foreign { process: String },
4742}
4743
4744fn classify_pty_screen_state(
4770 foreground: Option<&ForegroundVerdict>,
4771 gate: Option<&OperatorGateState>,
4772 failure: Option<&'static str>,
4773) -> PtyScreenState {
4774 if let Some(ForegroundVerdict::Foreign { process }) = foreground {
4775 return PtyScreenState::NotAgent {
4776 observed_process: process.clone(),
4777 };
4778 }
4779 if let Some(reason) = failure {
4780 return PtyScreenState::Failing {
4781 reason: reason.to_owned(),
4782 };
4783 }
4784 if let Some(gate) = gate {
4785 return PtyScreenState::OperatorGate { gate: gate.clone() };
4786 }
4787 if foreground.is_some() {
4788 PtyScreenState::Ready
4789 } else {
4790 PtyScreenState::Unknown
4791 }
4792}
4793
4794fn resolve_foreground_verdict(
4810 spec: &AgentSpec,
4811 observation: &PtyForegroundObservation,
4812 platform: RuntimePlatform,
4813) -> ForegroundVerdict {
4814 let process_name = observation
4815 .readiness
4816 .process_name
4817 .as_deref()
4818 .unwrap_or(observation.observed_process.as_str());
4819 if is_expected_agent_process(spec, process_name, platform)
4820 || is_agent_foreground_wrapper(process_name, platform)
4821 {
4822 ForegroundVerdict::Agent
4823 } else {
4824 ForegroundVerdict::Foreign {
4825 process: observation.observed_process.clone(),
4826 }
4827 }
4828}
4829
4830#[derive(Clone, Copy, Debug, Eq, PartialEq)]
4836enum ForegroundProbeSchedule {
4837 Disarmed,
4839 Armed,
4841}
4842
4843fn foreground_probe_schedule(state: &PtyScreenState) -> ForegroundProbeSchedule {
4844 if matches!(state, PtyScreenState::Ready) {
4845 ForegroundProbeSchedule::Disarmed
4846 } else {
4847 ForegroundProbeSchedule::Armed
4848 }
4849}
4850
4851fn foreground_probe_rearms_immediately(previous: &PtyScreenState, next: &PtyScreenState) -> bool {
4859 matches!(previous, PtyScreenState::Ready) && !matches!(next, PtyScreenState::Ready)
4860}
4861
4862fn observe_readiness_event(
4863 tracker: &mut ReadinessTracker<'_>,
4864 diagnostics: &mut ReadinessDiagnostics,
4865 event: PtyEvent,
4866 elapsed_ms: u64,
4867) -> Result<(), String> {
4868 match event {
4869 PtyEvent::Output(data) => {
4870 diagnostics.observe_output(&data);
4871 tracker.observe_output(&data, elapsed_ms);
4872 }
4873 PtyEvent::ForegroundProcess(observation) => {
4874 diagnostics.observe_foreground(&observation.readiness);
4875 tracker.observe_foreground(&observation.readiness, elapsed_ms);
4876 }
4877 PtyEvent::DataGap { .. } => {
4878 return Err("PTY replay gap prevents positive readiness proof".to_owned());
4879 }
4880 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
4881 return Err(message);
4882 }
4883 PtyEvent::Exited { code } => {
4884 return Err(format!("PTY exited with code {code} before readiness"));
4885 }
4886 PtyEvent::Started | PtyEvent::Resized(_) | PtyEvent::SnapshotAvailable { .. } => {}
4887 }
4888 Ok(())
4889}
4890
4891#[derive(Default)]
4892struct ReadinessDiagnostics {
4893 draft_signal: Option<gate4agent_types::DraftReadySignal>,
4894 output_bytes: usize,
4895 output_chunks: usize,
4896 tail: Vec<u8>,
4897 saw_bracketed_paste: bool,
4898 saw_cursor_show: bool,
4899 saw_cursor_hide: bool,
4900 saw_alternate_screen: bool,
4901 saw_clear_screen: bool,
4902 saw_claude_composer: bool,
4903 saw_codex_composer: bool,
4904 saw_named_foreground: bool,
4905 operator_gate: Option<OperatorGateState>,
4906}
4907
4908impl ReadinessDiagnostics {
4909 fn observe_output(&mut self, data: &[u8]) {
4910 const SIGNAL_TAIL_BYTES: usize = 4_096;
4911 self.output_bytes = self.output_bytes.saturating_add(data.len());
4912 self.output_chunks = self.output_chunks.saturating_add(1);
4913 let mut combined = Vec::with_capacity(self.tail.len().saturating_add(data.len()));
4914 combined.extend_from_slice(&self.tail);
4915 combined.extend_from_slice(data);
4916 self.saw_bracketed_paste |= readiness_bytes_contain(&combined, b"\x1b[?2004h");
4917 self.saw_cursor_show |= readiness_bytes_contain(&combined, b"\x1b[?25h");
4918 self.saw_cursor_hide |= readiness_bytes_contain(&combined, b"\x1b[?25l");
4919 self.saw_alternate_screen |= readiness_bytes_contain(&combined, b"\x1b[?1049h");
4920 self.saw_clear_screen |= readiness_bytes_contain(&combined, b"\x1b[2J");
4921 self.saw_claude_composer |= readiness_bytes_contain(&combined, "❯".as_bytes());
4922 self.saw_codex_composer |= readiness_bytes_contain(&combined, "›".as_bytes());
4923 let text = String::from_utf8_lossy(&combined);
4924 self.operator_gate = self
4925 .operator_gate
4926 .take()
4927 .or_else(|| startup_operator_gate(&strip_ansi_codes(&text)));
4928 self.tail = combined[combined.len().saturating_sub(SIGNAL_TAIL_BYTES)..].to_vec();
4929 }
4930
4931 fn observe_foreground(&mut self, foreground: &gate4agent::agent::ForegroundObservation) {
4932 self.saw_named_foreground |= foreground.process_name.is_some();
4933 }
4934
4935 fn summary(&self) -> String {
4936 format!(
4937 "draft_signal={:?} output_bytes={} output_chunks={} named_foreground={} bracketed_paste={} cursor_show={} cursor_hide={} alternate_screen={} clear_screen={} claude_composer={} codex_composer={} csi={}",
4938 self.draft_signal,
4939 self.output_bytes,
4940 self.output_chunks,
4941 self.saw_named_foreground,
4942 self.saw_bracketed_paste,
4943 self.saw_cursor_show,
4944 self.saw_cursor_hide,
4945 self.saw_alternate_screen,
4946 self.saw_clear_screen,
4947 self.saw_claude_composer,
4948 self.saw_codex_composer,
4949 readiness_csi_signatures(&self.tail),
4950 )
4951 }
4952}
4953
4954fn readiness_csi_signatures(bytes: &[u8]) -> String {
4955 let mut signatures = Vec::new();
4956 let mut index = 0;
4957 while index + 2 < bytes.len() && signatures.len() < 32 {
4958 if bytes[index] != 0x1b || bytes[index + 1] != b'[' {
4959 index += 1;
4960 continue;
4961 }
4962 let mut end = index + 2;
4963 while end < bytes.len() && end.saturating_sub(index) <= 24 {
4964 let byte = bytes[end];
4965 if (0x40..=0x7e).contains(&byte) {
4966 let signature = String::from_utf8_lossy(&bytes[index + 2..=end]).into_owned();
4967 if !signatures.iter().any(|existing| existing == &signature) {
4968 signatures.push(signature);
4969 }
4970 index = end;
4971 break;
4972 }
4973 if !(0x20..=0x3f).contains(&byte) {
4974 break;
4975 }
4976 end += 1;
4977 }
4978 index += 1;
4979 }
4980 if signatures.is_empty() {
4981 "none".to_owned()
4982 } else {
4983 signatures.join("|")
4984 }
4985}
4986
4987fn readiness_bytes_contain(haystack: &[u8], needle: &[u8]) -> bool {
4988 haystack
4989 .windows(needle.len())
4990 .any(|window| window == needle)
4991}
4992
4993fn readiness_complete(
4994 status: ReadinessStatus,
4995 diagnostics: &ReadinessDiagnostics,
4996) -> Result<bool, String> {
4997 match status {
4998 ReadinessStatus::Waiting => Ok(false),
4999 ReadinessStatus::Ready(_) => Ok(true),
5000 ReadinessStatus::TimedOut => Err(format!(
5001 "PTY readiness timed out ({})",
5002 diagnostics.summary()
5003 )),
5004 }
5005}
5006
5007fn elapsed_ms(started: Instant) -> u64 {
5008 u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX)
5009}
5010
5011
5012pub const ACP_BUSY_PROMPT_ENV: &str = "GATE4AGENT_ACP_BUSY_PROMPT";
5015
5016fn busy_prompt_queues(value: Option<&str>) -> bool {
5017 value.is_some_and(|v| v.trim().eq_ignore_ascii_case("queue"))
5018}
5019
5020async fn submit_acp_prompt(session: &gate4agent::acp::AcpSession, prompt: &str) -> Result<(), gate4agent::acp::AcpError> {
5023 if busy_prompt_queues(std::env::var(ACP_BUSY_PROMPT_ENV).ok().as_deref()) {
5024 return session.start_prompt(prompt).await;
5025 }
5026 let delivery = session.submit_prompt(prompt).await?;
5027 match &delivery {
5028 gate4agent::acp::PromptDelivery::Queued { reason } => tracing::info!(
5029 session = session.session_id(),
5030 %reason,
5031 "ACP prompt queued behind the running turn"
5032 ),
5033 other => tracing::debug!(session = session.session_id(), delivery = ?other, "ACP prompt delivered"),
5034 }
5035 Ok(())
5036}
5037
5038#[cfg(test)]
5039mod busy_prompt_env_tests {
5040 use super::busy_prompt_queues;
5041
5042 #[test]
5043 fn only_queue_opts_out_of_steering() {
5044 assert!(busy_prompt_queues(Some("queue")));
5045 assert!(busy_prompt_queues(Some(" QUEUE ")));
5046 assert!(!busy_prompt_queues(Some("steer")));
5047 assert!(!busy_prompt_queues(Some("")));
5048 assert!(!busy_prompt_queues(None));
5049 }
5050}
5051
5052#[cfg(test)]
5053mod tests {
5054 use super::{
5055 acp_approval_level_args,
5056 approval_level_not_offered_message,
5057 classify_operator_gate_option_semantics,
5058 classify_pty_screen_state,
5059 defers_permission_requests,
5060 foreground_probe_rearms_immediately, foreground_probe_schedule,
5061 argument_looks_like_credential, host_policy_for_approval_level,
5062 mcp_server_acp_entry,
5063 parse_operator_gate_options, prepare_fresh_pty_provider_session,
5064 prompt_render_probe, prompt_rendered, required_acp_mode,
5065 reserve_provider_gap_sequence, resolve_foreground_verdict, screen_failure,
5066 screen_failure_for_generation, with_pty_terminal_capability_defaults,
5067 should_attach_pty_provider_stream, should_probe_pty_identity, startup_operator_gate,
5068 terminal_frame, terminal_frame_byte_len, terminal_state_capture_should_skip,
5069 validate_instance_launch_arguments, validate_spawn_runtime_policy,
5070 ForegroundProbeSchedule, ForegroundVerdict, ReadinessDiagnostics, RateLimitFeed,
5071 Utf8ChunkDecoder,
5072 };
5073 use gate4agent::acp::protocol::{McpServerConfig, SessionMode};
5074 use gate4agent::HostPolicy;
5075 use gate4agent_adapters::builtin_adapter_registry;
5076 use gate4agent_catalog::{EnvMutation, McpServerSpec, ModeId};
5077 use gate4agent::agent::ForegroundObservation;
5078 use gate4agent::core::types::{
5079 AgentEvent, ContextWindowUsage as AgentContextWindowUsage, HostDecisionAuthority,
5080 HostRequestDecision, HostRequestOutcome, RateLimitType,
5081 };
5082 use gate4agent::pty::event::PtyMouseProtocolEncoding;
5083 use gate4agent::pty::{PtyForegroundObservation, PtyForegroundSource, RateLimitDetector};
5084 use gate4agent::CliTool;
5085 use gate4agent_types::{
5086 AdapterFamily, AgentId, ApprovalLevel,
5087 HostDecisionAuthority as ProviderHostDecisionAuthority,
5088 HostRequestDecision as ProviderHostRequestDecision,
5089 HostRequestOutcome as ProviderHostRequestOutcome, OperatorGateInput,
5090 OperatorGateKind, OperatorGateOptionSemantics, OperatorGateState, OperatorGateSubject,
5091 ProviderEvent, ProviderInteractionKind, ProviderInteractionOption, ProviderRuntimePolicy,
5092 PtyScreenState, RuntimePlatform, TerminalMouseProtocolEncoding, TransportKind,
5093 };
5094 use std::ffi::{OsStr, OsString};
5095
5096 fn snapshot(sequence: u64, contents: &str) -> super::PtyTerminalSnapshot {
5097 super::PtyTerminalSnapshot {
5098 pty_id: "fixture".to_owned(),
5099 provider_revision: "fixture-r1".to_owned(),
5100 generation: 1,
5101 sequence,
5102 size: gate4agent::pty::PtySize { rows: 24, cols: 80 },
5103 cursor: (0, 0),
5104 bracketed_paste: false,
5105 contents: contents.to_owned(),
5106 formatted: Vec::new(),
5107 scrollback_formatted: Vec::new(),
5108 alternate_screen: false,
5109 mouse_protocol_enabled: false,
5110 mouse_protocol_encoding: PtyMouseProtocolEncoding::Default,
5111 produced_at_unix_ms: 0,
5112 }
5113 }
5114
5115 #[test]
5116 fn terminal_frame_preserves_scrollback_and_terminal_input_metadata() {
5117 let mut snapshot = snapshot(7, "visible");
5118 snapshot.scrollback_formatted = vec![b"older".to_vec()];
5119 snapshot.alternate_screen = true;
5120 snapshot.mouse_protocol_enabled = true;
5121 snapshot.mouse_protocol_encoding = PtyMouseProtocolEncoding::Sgr;
5122 snapshot.produced_at_unix_ms = 1_700_000_000_000;
5123
5124 let frame = terminal_frame(snapshot, PtyScreenState::default());
5125 assert_eq!(frame.scrollback_formatted, vec![b"older".to_vec()]);
5126 assert!(frame.alternate_screen);
5127 assert!(frame.mouse_protocol_enabled);
5128 assert_eq!(frame.mouse_protocol_encoding, TerminalMouseProtocolEncoding::Sgr);
5129 assert_eq!(frame.produced_at_unix_ms, 1_700_000_000_000);
5131 }
5132
5133 #[test]
5134 fn terminal_frame_byte_len_sums_formatted_and_every_scrollback_row() {
5135 let mut snapshot = snapshot(9, "visible");
5136 snapshot.formatted = b"\x1b[2Jvisible".to_vec();
5137 snapshot.scrollback_formatted =
5138 vec![b"row one".to_vec(), b"row two, longer".to_vec()];
5139 let expected = snapshot.formatted.len()
5140 + snapshot.scrollback_formatted[0].len()
5141 + snapshot.scrollback_formatted[1].len();
5142
5143 let frame = terminal_frame(snapshot, PtyScreenState::default());
5144 assert_eq!(terminal_frame_byte_len(&frame), expected as u64);
5145 }
5146
5147 #[test]
5148 fn the_sequence_gate_skips_only_when_the_sequence_did_not_advance() {
5149 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(5), 5));
5150 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(4), 5));
5151 assert!(!terminal_state_capture_should_skip(Ok::<u64, ()>(6), 5));
5152 assert!(!terminal_state_capture_should_skip(Err::<u64, ()>(()), 5));
5155 }
5156
5157 #[test]
5158 fn structured_context_usage_maps_without_pty_inference() {
5159 let mapped = super::provider_event(
5160 AgentEvent::ContextWindowUsage {
5161 usage: AgentContextWindowUsage {
5162 uncached_input_tokens: 70,
5163 cache_read_tokens: 20,
5164 cache_write_tokens: 0,
5165 output_tokens: 10,
5166 unattributed_tokens: 5,
5167 used_tokens: 105,
5168 capacity_tokens: 100,
5169 },
5170 },
5171 &[],
5172 );
5173 assert_eq!(
5174 mapped,
5175 Some(ProviderEvent::ContextWindowUsage {
5176 usage: gate4agent_types::ContextWindowUsage {
5177 uncached_input_tokens: 70,
5178 cache_read_tokens: 20,
5179 cache_write_tokens: 0,
5180 output_tokens: 10,
5181 unattributed_tokens: 5,
5182 used_tokens: 105,
5183 capacity_tokens: 100,
5184 }
5185 })
5186 );
5187 assert_eq!(
5188 ProviderEvent::ContextWindowUsage {
5189 usage: gate4agent_types::ContextWindowUsage {
5190 uncached_input_tokens: 70,
5191 cache_read_tokens: 20,
5192 cache_write_tokens: 0,
5193 output_tokens: 10,
5194 unattributed_tokens: 5,
5195 used_tokens: 104,
5196 capacity_tokens: 100,
5197 },
5198 }
5199 .validate_ingress(),
5200 Err(gate4agent_types::ProviderEventValidationError::ContextWindowSegmentsMismatch {
5201 segment_sum: 105,
5202 used_tokens: 104,
5203 })
5204 );
5205 assert!(
5206 super::provider_event(AgentEvent::PtyRaw { data: b"105/100".to_vec() }, &[]).is_none()
5207 );
5208 }
5209
5210 #[test]
5219 fn turn_interrupted_maps_to_the_provider_event_that_unblocks_the_next_prompt() {
5220 let mapped = super::provider_event(
5221 AgentEvent::TurnInterrupted {
5222 reason: "session/prompt timed out after 120s".to_owned(),
5223 },
5224 &[],
5225 );
5226 assert_eq!(mapped, Some(ProviderEvent::TurnInterrupted));
5227 }
5228
5229 #[test]
5230 fn tool_result_non_execution_kind_carries_through_to_tool_completed() {
5231 let mapped = super::provider_event(
5232 AgentEvent::ToolResult {
5233 id: "t1".to_owned(),
5234 output: "denied".to_owned(),
5235 is_error: true,
5236 duration_ms: None,
5237 non_execution_kind: Some("permission-rule".to_owned()),
5238 },
5239 &[],
5240 );
5241 assert_eq!(
5242 mapped,
5243 Some(ProviderEvent::ToolCompleted {
5244 id: "t1".to_owned(),
5245 output: "denied".to_owned(),
5246 is_error: true,
5247 duration_ms: None,
5248 agent_id: None,
5249 non_execution_kind: Some("permission-rule".to_owned()),
5250 })
5251 );
5252 }
5253
5254 #[test]
5255 fn session_end_stop_reason_carries_through_to_session_ended() {
5256 use gate4agent::StopReason;
5257
5258 let refusal = super::provider_event(
5259 AgentEvent::SessionEnd {
5260 result: "refusal".to_owned(),
5261 cost_usd: None,
5262 is_error: true,
5263 stop_reason: Some(StopReason::Refusal),
5264 },
5265 &[],
5266 );
5267 assert_eq!(
5268 refusal,
5269 Some(ProviderEvent::SessionEnded {
5270 result: "refusal".to_owned(),
5271 cost_usd: None,
5272 is_error: true,
5273 stop_reason: Some(gate4agent_types::ProviderStopReason::Refusal),
5274 })
5275 );
5276
5277 let quota = super::provider_event(
5278 AgentEvent::SessionEnd {
5279 result: "JSON-RPC error -32603: Internal error".to_owned(),
5280 cost_usd: None,
5281 is_error: true,
5282 stop_reason: Some(StopReason::ProviderError {
5283 code: -32603,
5284 message: "You've hit your usage limit.".to_owned(),
5285 vendor_code: Some("usageLimitExceeded".to_owned()),
5286 }),
5287 },
5288 &[],
5289 );
5290 assert_eq!(
5291 quota,
5292 Some(ProviderEvent::SessionEnded {
5293 result: "JSON-RPC error -32603: Internal error".to_owned(),
5294 cost_usd: None,
5295 is_error: true,
5296 stop_reason: Some(gate4agent_types::ProviderStopReason::ProviderError {
5297 code: -32603,
5298 message: "You've hit your usage limit.".to_owned(),
5299 vendor_code: Some("usageLimitExceeded".to_owned()),
5300 }),
5301 })
5302 );
5303 }
5304
5305 #[test]
5306 fn host_request_reaches_the_operator_with_method_and_host_decision() {
5307 let denied = super::provider_event(
5308 AgentEvent::RpcIncomingRequest {
5309 id: gate4agent::rpc::message::RpcId::Number(1),
5310 method: "fs/read_text_file".to_owned(),
5311 params: None,
5312 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Policy },
5313 outcome: HostRequestOutcome::Executed,
5314 reason: None,
5315 },
5316 &[],
5317 );
5318 assert_eq!(
5319 denied,
5320 Some(ProviderEvent::HostRequestObserved {
5321 method: "fs/read_text_file".to_owned(),
5322 params_json: String::new(),
5323 decision: ProviderHostRequestDecision::Denied {
5324 by: ProviderHostDecisionAuthority::Policy
5325 },
5326 outcome: ProviderHostRequestOutcome::Executed,
5327 reason: None,
5328 })
5329 );
5330
5331 let granted = super::provider_event(
5332 AgentEvent::RpcIncomingRequest {
5333 id: gate4agent::rpc::message::RpcId::Number(2),
5334 method: "terminal/create".to_owned(),
5335 params: None,
5336 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5337 outcome: HostRequestOutcome::Executed,
5338 reason: None,
5339 },
5340 &[],
5341 );
5342 assert_eq!(
5343 granted,
5344 Some(ProviderEvent::HostRequestObserved {
5345 method: "terminal/create".to_owned(),
5346 params_json: String::new(),
5347 decision: ProviderHostRequestDecision::Granted {
5348 by: ProviderHostDecisionAuthority::Policy
5349 },
5350 outcome: ProviderHostRequestOutcome::Executed,
5351 reason: None,
5352 })
5353 );
5354
5355 let gate_denied = super::provider_event(
5359 AgentEvent::RpcIncomingRequest {
5360 id: gate4agent::rpc::message::RpcId::Number(3),
5361 method: "terminal/create".to_owned(),
5362 params: None,
5363 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5364 outcome: HostRequestOutcome::Executed,
5365 reason: None,
5366 },
5367 &[],
5368 );
5369 assert_eq!(
5370 gate_denied,
5371 Some(ProviderEvent::HostRequestObserved {
5372 method: "terminal/create".to_owned(),
5373 params_json: String::new(),
5374 decision: ProviderHostRequestDecision::Denied {
5375 by: ProviderHostDecisionAuthority::Gate
5376 },
5377 outcome: ProviderHostRequestOutcome::Executed,
5378 reason: None,
5379 })
5380 );
5381
5382 let operator_granted = super::provider_event(
5383 AgentEvent::RpcIncomingRequest {
5384 id: gate4agent::rpc::message::RpcId::Number(4),
5385 method: "session/request_permission".to_owned(),
5386 params: None,
5387 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Operator },
5388 outcome: HostRequestOutcome::Executed,
5389 reason: None,
5390 },
5391 &[],
5392 );
5393 assert_eq!(
5394 operator_granted,
5395 Some(ProviderEvent::HostRequestObserved {
5396 method: "session/request_permission".to_owned(),
5397 params_json: String::new(),
5398 decision: ProviderHostRequestDecision::Granted {
5399 by: ProviderHostDecisionAuthority::Operator
5400 },
5401 outcome: ProviderHostRequestOutcome::Executed,
5402 reason: None,
5403 })
5404 );
5405
5406 let deadline_denied = super::provider_event(
5407 AgentEvent::RpcIncomingRequest {
5408 id: gate4agent::rpc::message::RpcId::Number(5),
5409 method: "session/request_permission".to_owned(),
5410 params: None,
5411 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::DeadlinePolicy },
5412 outcome: HostRequestOutcome::Executed,
5413 reason: None,
5414 },
5415 &[],
5416 );
5417 assert_eq!(
5418 deadline_denied,
5419 Some(ProviderEvent::HostRequestObserved {
5420 method: "session/request_permission".to_owned(),
5421 params_json: String::new(),
5422 decision: ProviderHostRequestDecision::Denied {
5423 by: ProviderHostDecisionAuthority::DeadlinePolicy
5424 },
5425 outcome: ProviderHostRequestOutcome::Executed,
5426 reason: None,
5427 })
5428 );
5429
5430 }
5436
5437 #[test]
5444 fn granted_host_request_execution_failure_carries_through_as_a_failed_outcome() {
5445 let spawn_error = "terminal/create spawn failed: os error 3";
5446 let mapped = super::provider_event(
5447 AgentEvent::RpcIncomingRequest {
5448 id: gate4agent::rpc::message::RpcId::Number(10),
5449 method: "terminal/create".to_owned(),
5450 params: None,
5451 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5452 outcome: HostRequestOutcome::Failed { error: spawn_error.to_owned() },
5453 reason: None,
5454 },
5455 &[],
5456 );
5457 assert_eq!(
5458 mapped,
5459 Some(ProviderEvent::HostRequestObserved {
5460 method: "terminal/create".to_owned(),
5461 params_json: String::new(),
5462 decision: ProviderHostRequestDecision::Granted {
5463 by: ProviderHostDecisionAuthority::Policy
5464 },
5465 outcome: ProviderHostRequestOutcome::Failed { error: spawn_error.to_owned() },
5466 reason: None,
5467 })
5468 );
5469 mapped.expect("mapped").validate_ingress().expect("bounded free-text error validates");
5470 }
5471
5472 #[test]
5479 fn host_request_reason_carries_through_to_the_operator() {
5480 let gate_text =
5481 "blocked by dangerous-command gate: rule=filesystem-wipe, argument=rm -rf /";
5482 let denied = super::provider_event(
5483 AgentEvent::RpcIncomingRequest {
5484 id: gate4agent::rpc::message::RpcId::Number(9),
5485 method: "terminal/create".to_owned(),
5486 params: None,
5487 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5488 outcome: HostRequestOutcome::Executed,
5489 reason: Some(gate_text.to_owned()),
5490 },
5491 &[],
5492 );
5493 assert_eq!(
5494 denied,
5495 Some(ProviderEvent::HostRequestObserved {
5496 method: "terminal/create".to_owned(),
5497 params_json: String::new(),
5498 decision: ProviderHostRequestDecision::Denied {
5499 by: ProviderHostDecisionAuthority::Gate
5500 },
5501 outcome: ProviderHostRequestOutcome::Executed,
5502 reason: Some(gate_text.to_owned()),
5503 })
5504 );
5505
5506 denied.expect("mapped").validate_ingress().expect("bounded free-text reason validates");
5511 }
5512
5513 #[test]
5514 fn deferred_acp_permission_request_becomes_an_interaction_with_its_id() {
5515 let with_title = super::provider_event(
5516 AgentEvent::RpcIncomingRequest {
5517 id: gate4agent::rpc::message::RpcId::Number(6),
5518 method: "session/request_permission".to_owned(),
5519 params: Some(serde_json::json!({
5520 "sessionId": "s1",
5521 "toolCall": {"toolCallId": "t1", "kind": "edit", "title": "Edit src/main.rs"},
5522 "options": [
5523 {"optionId": "allow", "name": "Allow", "kind": "allow_once"},
5524 {"optionId": "reject", "name": "Reject", "kind": "reject_once"},
5525 ],
5526 })),
5527 decision: HostRequestDecision::Deferred,
5528 outcome: HostRequestOutcome::Executed,
5529 reason: None,
5530 },
5531 &[],
5532 );
5533 assert_eq!(
5542 with_title,
5543 Some(ProviderEvent::InteractionRequested {
5544 request_id: Some("number:6".to_owned()),
5545 interaction_kind: ProviderInteractionKind::Approval,
5546 tool_name: "edit".to_owned(),
5547 title: Some("Edit src/main.rs".to_owned()),
5548 prompt: "Edit src/main.rs".to_owned(),
5549 options: vec![
5550 ProviderInteractionOption {
5551 option_id: "allow".to_owned(),
5552 name: "Allow".to_owned(),
5553 kind: "allow_once".to_owned(),
5554 },
5555 ProviderInteractionOption {
5556 option_id: "reject".to_owned(),
5557 name: "Reject".to_owned(),
5558 kind: "reject_once".to_owned(),
5559 },
5560 ],
5561 agent_id: None,
5562 })
5563 );
5564
5565 let without_title = super::provider_event(
5571 AgentEvent::RpcIncomingRequest {
5572 id: gate4agent::rpc::message::RpcId::String("agent-7".to_owned()),
5573 method: "session/request_permission".to_owned(),
5574 params: None,
5575 decision: HostRequestDecision::Deferred,
5576 outcome: HostRequestOutcome::Executed,
5577 reason: None,
5578 },
5579 &[],
5580 );
5581 assert_eq!(
5582 without_title,
5583 Some(ProviderEvent::InteractionRequested {
5584 request_id: Some("string:agent-7".to_owned()),
5585 interaction_kind: ProviderInteractionKind::Approval,
5586 tool_name: "session/request_permission".to_owned(),
5587 title: None,
5588 prompt: String::new(),
5589 options: Vec::new(),
5590 agent_id: None,
5591 })
5592 );
5593
5594 let resolved = super::provider_event(
5598 AgentEvent::RpcIncomingRequest {
5599 id: gate4agent::rpc::message::RpcId::Number(6),
5600 method: "session/request_permission".to_owned(),
5601 params: None,
5602 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Operator },
5603 outcome: HostRequestOutcome::Executed,
5604 reason: None,
5605 },
5606 &[],
5607 );
5608 assert_eq!(
5609 resolved,
5610 Some(ProviderEvent::HostRequestObserved {
5611 method: "session/request_permission".to_owned(),
5612 params_json: String::new(),
5613 decision: ProviderHostRequestDecision::Denied {
5614 by: ProviderHostDecisionAuthority::Operator
5615 },
5616 outcome: ProviderHostRequestOutcome::Executed,
5617 reason: None,
5618 })
5619 );
5620 }
5621
5622 #[test]
5623 fn unrecognized_notification_reaches_the_operator_as_a_raw_event_instead_of_vanishing() {
5624 let mapped = super::provider_event(
5625 AgentEvent::RpcNotification {
5626 method: "session/update".to_owned(),
5627 params: Default::default(),
5628 },
5629 &[],
5630 );
5631 assert_eq!(
5632 mapped,
5633 Some(ProviderEvent::UnrecognizedNotification {
5634 method: "session/update".to_owned(),
5635 payload_json: "null".to_owned(),
5636 })
5637 );
5638 }
5639
5640 #[test]
5641 fn pty_terminal_capability_defaults_never_override_a_caller_supplied_term() {
5642 let caller_supplied = vec![EnvMutation {
5643 key: OsString::from("TERM"),
5644 value: Some(OsString::from("dumb")),
5645 }];
5646 let filled = with_pty_terminal_capability_defaults(caller_supplied);
5647
5648 let term_values: Vec<_> = filled
5649 .iter()
5650 .filter(|mutation| mutation.key.as_os_str() == OsStr::new("TERM"))
5651 .collect();
5652 assert_eq!(term_values.len(), 1, "TERM must not be duplicated");
5653 assert_eq!(term_values[0].value.as_deref(), Some(OsStr::new("dumb")));
5654
5655 let colorterm = filled
5656 .iter()
5657 .find(|mutation| mutation.key.as_os_str() == OsStr::new("COLORTERM"))
5658 .expect("COLORTERM default is filled in when the caller left it unset");
5659 assert_eq!(colorterm.value.as_deref(), Some(OsStr::new("truecolor")));
5660 }
5661
5662 #[test]
5668 fn mcp_server_acp_entry_translates_a_spec_into_one_stdio_entry() {
5669 let spec = McpServerSpec::new(
5670 "test-mcp-server",
5671 OsString::from("C:\\example\\example-mcp-server.exe"),
5672 vec![OsString::from("--session-proxy")],
5673 vec![
5674 (
5675 OsString::from("TEST_MCP_SESSION_ENDPOINT"),
5676 OsString::from("\\\\.\\pipe\\example-mcp-server-s1"),
5677 ),
5678 (
5679 OsString::from("TEST_MCP_SESSION_TOKEN"),
5680 OsString::from("tok-abc"),
5681 ),
5682 ],
5683 )
5684 .unwrap();
5685
5686 let server = mcp_server_acp_entry(&spec);
5687 match server {
5688 McpServerConfig::Stdio { name, command, args, env } => {
5689 assert_eq!(name, "test-mcp-server", "ACP v1 requires a name; the adapter registers by it");
5690 assert_eq!(command, "C:\\example\\example-mcp-server.exe");
5691 assert_eq!(args, vec!["--session-proxy".to_string()]);
5692 assert_eq!(env.len(), 2, "exactly the entries the spec was given, nothing else");
5693 assert_eq!(
5694 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_ENDPOINT").map(|pair| pair.value.as_str()),
5695 Some("\\\\.\\pipe\\example-mcp-server-s1")
5696 );
5697 assert_eq!(
5698 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_TOKEN").map(|pair| pair.value.as_str()),
5699 Some("tok-abc")
5700 );
5701 }
5702 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5703 }
5704 }
5705
5706 #[test]
5707 fn mcp_server_acp_entry_carries_zero_env_pairs_when_the_spec_carries_none() {
5708 let spec = McpServerSpec::new(
5709 "test-mcp-server",
5710 OsString::from("C:\\example\\example-mcp-server.exe"),
5711 vec![OsString::from("--session-proxy")],
5712 Vec::new(),
5713 )
5714 .unwrap();
5715
5716 let server = mcp_server_acp_entry(&spec);
5717 match server {
5718 McpServerConfig::Stdio { env, .. } => assert!(env.is_empty()),
5719 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5720 }
5721 }
5722
5723 #[test]
5724 fn credential_shape_rule_matches_prefixed_hex64_not_bare_digest_or_uuid() {
5725 let hex64 = "a1b2c3d4e5f6".repeat(5) + "a1b2";
5726 assert_eq!(hex64.len(), 64);
5727
5728 let prefixed_token = format!("g4aho_{hex64}");
5729 assert!(
5730 argument_looks_like_credential(&prefixed_token),
5731 "a short lowercase prefix plus '_' plus 64 lowercase hex chars is a credential"
5732 );
5733
5734 assert!(
5735 !argument_looks_like_credential(&hex64),
5736 "a bare 64-hex digest with no prefix is a legitimate diagnostic, not a credential"
5737 );
5738
5739 assert!(
5740 !argument_looks_like_credential("550e8400-e29b-41d4-a716-446655440000"),
5741 "a UUID must not be mistaken for a prefixed-hex64 credential"
5742 );
5743 }
5744
5745 #[test]
5746 fn native_instance_launch_arguments_fail_closed_before_shell_spawn() {
5747 let claude = AgentId::new("claude").unwrap();
5748 assert_eq!(
5749 validate_instance_launch_arguments(
5750 &claude,
5751 TransportKind::Pipe,
5752 &[OsString::from("--bundle-mode")],
5753 )
5754 .unwrap_err(),
5755 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
5756 );
5757 assert_eq!(
5758 validate_instance_launch_arguments(
5759 &claude,
5760 TransportKind::Pty,
5761 &[OsString::from("--resume=session-secret")],
5762 )
5763 .unwrap_err(),
5764 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
5765 );
5766 assert!(validate_instance_launch_arguments(
5767 &claude,
5768 TransportKind::Pty,
5769 &[
5770 OsString::from("--permission-mode"),
5771 OsString::from("default"),
5772 ],
5773 )
5774 .is_ok());
5775 }
5776
5777 fn kind_of(contents: &str) -> Option<OperatorGateKind> {
5781 startup_operator_gate(contents).map(|gate| gate.kind)
5782 }
5783
5784 #[test]
5785 fn startup_operator_gates_are_classified_without_returning_terminal_text() {
5786 assert_eq!(kind_of(" Trust this\nfolder? "), Some(OperatorGateKind::WorkspaceTrust));
5787 assert_eq!(
5788 kind_of("No auth type is selected"),
5789 Some(OperatorGateKind::Authentication)
5790 );
5791 assert_eq!(
5792 kind_of("Sign in with OpenAI to use Codex"),
5793 Some(OperatorGateKind::Authentication)
5794 );
5795 assert_eq!(
5801 kind_of(
5802 "Claude Code can be used with your Claude subscription or billed based on \
5803 API usage through your Console account.\n\
5804 Select login method:\n\
5805 \u{276f} 1. Claude ...\n\
5806 2. API usage billing\n\
5807 3. 3rd-party platform \u{b7} Amazon Bedrock ..."
5808 ),
5809 Some(OperatorGateKind::Authentication)
5810 );
5811 assert_eq!(
5812 kind_of(
5813 "Browser didn't open? Use the url below to sign in (c to copy)\n\
5814 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
5815 Paste code here"
5816 ),
5817 Some(OperatorGateKind::Authentication)
5818 );
5819 assert_eq!(
5824 kind_of(
5825 "Once you sign in, copy the generated token and paste it into your .env file; \
5826 no code entry happens on this screen."
5827 ),
5828 None
5829 );
5830 assert_eq!(
5831 kind_of("Kimi Code Update Available\nInstall update now (0.32.0)\nEnter confirm"),
5832 Some(OperatorGateKind::VendorUpdate)
5833 );
5834 assert_eq!(
5835 kind_of(
5836 "Welcome to Claude Code\nChoose the text style that looks best with your terminal"
5837 ),
5838 Some(OperatorGateKind::TerminalAppearance)
5839 );
5840 assert_eq!(
5841 kind_of(
5842 "Welcome to Claude Code for VS Code\nClaude has context of open files and selected lines"
5843 ),
5844 Some(OperatorGateKind::Onboarding)
5845 );
5846 assert_eq!(
5847 kind_of("Welcome to Claude Code\n❯ Press Enter to continue"),
5848 Some(OperatorGateKind::Onboarding)
5849 );
5850 assert_eq!(kind_of("Welcome to Claude Code\n❯ ready\nEnter to send"), None);
5851 assert_eq!(
5852 kind_of(
5853 "Quick safety check: Is this a project you trust?\nYes, I trust this folder\nNo, continue without these permissions"
5854 ),
5855 Some(OperatorGateKind::WorkspaceTrust)
5856 );
5857 assert_eq!(kind_of("ready for a prompt"), None);
5858 assert_eq!(
5863 kind_of(
5864 "Updating Codex via `npm install -g @openai/codex`...\n\
5865 npm warn cleanup Failed to remove some directories\n\
5866 Update ran successfully! Please restart Codex."
5867 ),
5868 Some(OperatorGateKind::VendorUpdate)
5869 );
5870 assert_eq!(
5880 kind_of(
5881 " Hooks need review\n\
5882 6 hooks are new or changed.\n\
5883 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5884 2. Trust all and continue\n\
5885 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5886 ),
5887 Some(OperatorGateKind::HookTrust)
5888 );
5889 assert_eq!(
5892 kind_of(
5893 " Hooks need review\n\
5894 42 hooks are new or changed.\n\
5895 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5896 2. Trust all and continue\n\
5897 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5898 ),
5899 Some(OperatorGateKind::HookTrust)
5900 );
5901 assert_eq!(
5905 kind_of(
5906 "I reviewed the pre-commit hooks in this repo and they look safe to trust; \
5907 I'll leave the hooks config as-is and continue with the refactor."
5908 ),
5909 None
5910 );
5911 }
5912
5913 #[test]
5920 fn startup_operator_gate_parses_a_numbered_hook_trust_option_list() {
5921 let contents = "Hooks need review\n\
5922 \u{203a} 1. Review hooks\n \
5923 2. Trust all and continue\n \
5924 3. Continue without trusting (hooks won't run)\n\
5925 Press enter to confirm or esc to go back";
5926 let gate = startup_operator_gate(contents).expect("hook trust must classify");
5927 assert_eq!(gate.kind, OperatorGateKind::HookTrust);
5928 assert_eq!(gate.input, OperatorGateInput::NumberedList);
5929 assert_eq!(
5930 gate.options,
5931 vec![
5932 gate4agent_types::OperatorGateOption {
5933 text: "Review hooks".to_owned(),
5934 semantics: OperatorGateOptionSemantics::Inspect,
5935 selected: true,
5936 },
5937 gate4agent_types::OperatorGateOption {
5938 text: "Trust all and continue".to_owned(),
5939 semantics: OperatorGateOptionSemantics::Accept,
5940 selected: false,
5941 },
5942 gate4agent_types::OperatorGateOption {
5943 text: "Continue without trusting (hooks won't run)".to_owned(),
5944 semantics: OperatorGateOptionSemantics::Decline,
5945 selected: false,
5946 },
5947 ],
5948 );
5949 }
5950
5951 #[test]
5958 fn startup_operator_gate_parses_an_arrow_workspace_trust_option_list() {
5959 let contents = "Do you trust the files in this folder?\n \
5960 Trust this folder\n \
5961 Enable project MCP servers. Remembered for this folder.\n\u{276f} \
5962 Don't trust\n \
5963 Exit Kimi Code. Asked again next launch.\n \
5964 \u{2191}\u{2193} navigate \u{b7} Enter select \u{b7} Esc exit";
5965 let gate = startup_operator_gate(contents).expect("workspace trust must classify");
5966 assert_eq!(gate.kind, OperatorGateKind::WorkspaceTrust);
5967 assert_eq!(gate.input, OperatorGateInput::ArrowList);
5968 assert_eq!(
5969 gate.options,
5970 vec![
5971 gate4agent_types::OperatorGateOption {
5972 text: "Trust this folder".to_owned(),
5973 semantics: OperatorGateOptionSemantics::Accept,
5974 selected: false,
5975 },
5976 gate4agent_types::OperatorGateOption {
5977 text: "Don't trust".to_owned(),
5978 semantics: OperatorGateOptionSemantics::Decline,
5979 selected: true,
5980 },
5981 ],
5982 );
5983 }
5984
5985 #[test]
5989 fn startup_operator_gate_without_a_recognized_option_list_reports_unknown_input() {
5990 let gate = startup_operator_gate("No auth type is selected")
5991 .expect("authentication must classify");
5992 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5993 assert_eq!(gate.input, OperatorGateInput::Unknown);
5994 assert!(gate.options.is_empty());
5995 }
5996
5997 #[test]
6006 fn startup_operator_gate_parses_claudes_login_method_chooser_including_its_cursor_row() {
6007 let contents = "Select login method:\n\
6008 \u{276f} 1. Claude ...\n\
6009 2. API usage billing\n\
6010 3. 3rd-party platform \u{b7} Amazon Bedrock ...";
6011 let gate = startup_operator_gate(contents).expect("authentication must classify");
6012 assert_eq!(gate.kind, OperatorGateKind::Authentication);
6013 assert_eq!(gate.subject, OperatorGateSubject::Account);
6014 assert_eq!(gate.input, OperatorGateInput::NumberedList);
6015 assert_eq!(
6016 gate.options,
6017 vec![
6018 gate4agent_types::OperatorGateOption {
6019 text: "Claude ...".to_owned(),
6020 semantics: OperatorGateOptionSemantics::Unknown,
6021 selected: true,
6022 },
6023 gate4agent_types::OperatorGateOption {
6024 text: "API usage billing".to_owned(),
6025 semantics: OperatorGateOptionSemantics::Unknown,
6026 selected: false,
6027 },
6028 gate4agent_types::OperatorGateOption {
6029 text: "3rd-party platform \u{b7} Amazon Bedrock ...".to_owned(),
6030 semantics: OperatorGateOptionSemantics::Unknown,
6031 selected: false,
6032 },
6033 ],
6034 );
6035 }
6036
6037 #[test]
6042 fn startup_operator_gate_oauth_wait_screen_reports_text_entry_input() {
6043 let contents = "Browser didn't open? Use the url below to sign in (c to copy)\n\
6044 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
6045 Paste code here";
6046 let gate = startup_operator_gate(contents).expect("oauth wait screen must classify");
6047 assert_eq!(gate.kind, OperatorGateKind::Authentication);
6048 assert_eq!(gate.subject, OperatorGateSubject::Account);
6049 assert_eq!(gate.input, OperatorGateInput::TextEntry);
6050 assert!(gate.options.is_empty());
6051 }
6052
6053 #[test]
6059 fn parse_operator_gate_options_recognizes_numbered_and_arrow_shapes_and_nothing_else() {
6060 assert_eq!(
6061 parse_operator_gate_options("Press enter to confirm or esc to go back"),
6062 (OperatorGateInput::Unknown, Vec::new()),
6063 );
6064 let (input, options) = parse_operator_gate_options(
6065 "\u{203a} 1. Review hooks\n 2. Trust all and continue",
6066 );
6067 assert_eq!(input, OperatorGateInput::NumberedList);
6068 assert_eq!(options.len(), 2);
6069 let (input, options) = parse_operator_gate_options(
6070 " Trust this folder\n Enable project MCP servers. Remembered for this folder.\n\u{276f} Don't trust",
6071 );
6072 assert_eq!(input, OperatorGateInput::ArrowList);
6073 assert_eq!(options.len(), 2);
6074 }
6075
6076 #[test]
6077 fn classify_operator_gate_option_semantics_reads_the_verb_not_the_position() {
6078 assert_eq!(
6079 classify_operator_gate_option_semantics("Review hooks"),
6080 OperatorGateOptionSemantics::Inspect,
6081 );
6082 assert_eq!(
6083 classify_operator_gate_option_semantics("Trust all and continue"),
6084 OperatorGateOptionSemantics::Accept,
6085 );
6086 assert_eq!(
6087 classify_operator_gate_option_semantics("Continue without trusting (hooks won't run)"),
6088 OperatorGateOptionSemantics::Decline,
6089 );
6090 assert_eq!(
6091 classify_operator_gate_option_semantics("Don't trust"),
6092 OperatorGateOptionSemantics::Decline,
6093 );
6094 assert_eq!(
6095 classify_operator_gate_option_semantics("Exit Kimi Code"),
6096 OperatorGateOptionSemantics::Exit,
6097 );
6098 assert_eq!(
6099 classify_operator_gate_option_semantics("Something unrecognized"),
6100 OperatorGateOptionSemantics::Unknown,
6101 );
6102 }
6103
6104 #[test]
6105 fn screen_failure_recognizes_crash_and_missing_command_banners() {
6106 assert_eq!(
6107 screen_failure("thread 'main' panicked at 'index out of bounds', src/main.rs:12:5"),
6108 Some("crash")
6109 );
6110 assert_eq!(
6111 screen_failure("Traceback (most recent call last):\n File \"a.py\", line 1"),
6112 Some("crash")
6113 );
6114 assert_eq!(
6115 screen_failure("bash: fooagent: command not found"),
6116 Some("missing command")
6117 );
6118 assert_eq!(
6119 screen_failure("C:\\workspace> fooagent\n'fooagent' is not recognized as an internal or external command"),
6120 Some("missing command")
6121 );
6122 assert_eq!(
6123 screen_failure(
6124 "workspace/project $ fooagent: no such file or directory\nworkspace/project $"
6125 ),
6126 Some("missing command")
6127 );
6128 assert_eq!(
6131 screen_failure("The build log mentions no such file or directory near line 40."),
6132 None
6133 );
6134 assert_eq!(
6138 screen_failure("fooagent-installer: fatal error: missing header <stdio.h>"),
6139 None
6140 );
6141 }
6142
6143 #[test]
6144 fn screen_failure_recognizes_grok_missing_api_key_banner() {
6145 assert_eq!(
6150 screen_failure(
6151 "\u{274c} Error: API key required. Set GROK_API_KEY environment variable, \
6152 use --api-key flag, or set \"apiKey\" field in ~/.grok/user-settings.json"
6153 ),
6154 Some("missing api key")
6155 );
6156 assert_eq!(
6160 screen_failure(
6161 "You'll need an API key for this provider before it works; check the docs \
6162 for how to configure one."
6163 ),
6164 None
6165 );
6166 }
6167
6168 #[test]
6169 fn screen_failure_no_longer_has_an_authentication_expired_bucket() {
6170 assert_eq!(
6175 screen_failure("Your session token has expired. Please re-authenticate."),
6176 None
6177 );
6178 assert_eq!(
6179 screen_failure("The stored credential was revoked by the workspace admin."),
6180 None
6181 );
6182 }
6183
6184 #[test]
6185 fn screen_failure_does_not_false_positive_on_an_agent_narrating_an_error() {
6186 let narration = "I looked at the traceback you pasted -- it's a Python \
6191 exception, a plain ValueError from a retry loop, not a real crash. \
6192 Our harness logs the word fatal in its own banner for visibility, \
6193 but nothing actually panicked. The command definitely exists; it \
6194 just needed different flags, and your token is still valid.";
6195 assert_eq!(screen_failure(narration), None);
6196 }
6197
6198 #[test]
6199 fn screen_failure_for_generation_ignores_every_marker_once_the_session_was_ever_ready() {
6200 let shell_command_not_found = "$ frobnicate --help\nbash: frobnicate: command not found\n$";
6205 assert_eq!(
6206 screen_failure_for_generation(shell_command_not_found, true),
6207 None
6208 );
6209
6210 let python_traceback_from_a_ran_script = "$ python broken.py\n\
6211 Traceback (most recent call last):\n File \"broken.py\", line 3, in <module>\n\
6212 ValueError: bad input\n$";
6213 assert_eq!(
6214 screen_failure_for_generation(python_traceback_from_a_ran_script, true),
6215 None
6216 );
6217
6218 let cargo_test_panic = "running 1 test\n\
6219 error[E0308]: mismatched types\n\
6220 thread 'tests::it_fails' panicked at 'assertion failed', src/lib.rs:9:5\n\
6221 test result: FAILED. 0 passed; 1 failed";
6222 assert_eq!(screen_failure_for_generation(cargo_test_panic, true), None);
6223
6224 let agent_narrating_an_expired_token = "The API token has expired; \
6225 I revoked the old credential and issued a new one for you.";
6226 assert_eq!(
6227 screen_failure_for_generation(agent_narrating_an_expired_token, true),
6228 None
6229 );
6230
6231 assert_eq!(
6236 screen_failure_for_generation(shell_command_not_found, false),
6237 Some("missing command")
6238 );
6239 assert_eq!(
6240 screen_failure_for_generation(python_traceback_from_a_ran_script, false),
6241 Some("crash")
6242 );
6243 assert_eq!(screen_failure_for_generation(cargo_test_panic, false), Some("crash"));
6244 }
6245
6246 #[test]
6247 fn classify_pty_screen_state_lets_a_foreign_process_win_over_a_matching_gate_text() {
6248 let foreign = ForegroundVerdict::Foreign {
6253 process: "npm".to_owned(),
6254 };
6255 assert_eq!(
6256 classify_pty_screen_state(Some(&foreign), None, None),
6257 PtyScreenState::NotAgent {
6258 observed_process: "npm".to_owned()
6259 }
6260 );
6261 let vendor_update_gate = OperatorGateState::new(OperatorGateKind::VendorUpdate);
6262 assert_eq!(
6263 classify_pty_screen_state(Some(&foreign), Some(&vendor_update_gate), None),
6264 PtyScreenState::NotAgent {
6265 observed_process: "npm".to_owned()
6266 }
6267 );
6268 }
6269
6270 #[test]
6271 fn classify_pty_screen_state_reports_a_gate_only_when_foreground_matches() {
6272 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6273 assert_eq!(
6274 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), Some(&authentication_gate), None),
6275 PtyScreenState::OperatorGate {
6276 gate: authentication_gate.clone()
6277 }
6278 );
6279 }
6280
6281 #[test]
6282 fn classify_pty_screen_state_reports_failing_for_a_matched_foreground() {
6283 assert_eq!(
6284 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, Some("crash")),
6285 PtyScreenState::Failing {
6286 reason: "crash".to_owned()
6287 }
6288 );
6289 }
6290
6291 #[test]
6292 fn classify_pty_screen_state_prefers_failing_over_a_co_occurring_gate() {
6293 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6297 assert_eq!(
6298 classify_pty_screen_state(
6299 Some(&ForegroundVerdict::Agent),
6300 Some(&authentication_gate),
6301 Some("crash")
6302 ),
6303 PtyScreenState::Failing {
6304 reason: "crash".to_owned()
6305 }
6306 );
6307 }
6308
6309 #[test]
6310 fn classify_pty_screen_state_reaches_ready_only_with_matched_foreground_and_clean_text() {
6311 assert_eq!(
6312 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, None),
6313 PtyScreenState::Ready
6314 );
6315 }
6316
6317 #[test]
6318 fn classify_pty_screen_state_never_reaches_ready_without_a_foreground_observation() {
6319 assert_eq!(classify_pty_screen_state(None, None, None), PtyScreenState::Unknown);
6322 }
6323
6324 #[test]
6325 fn resolve_foreground_verdict_tolerates_a_spawning_wrapper_like_readiness_does() {
6326 let spec = gate4agent_testkit::interactive_agent_spec();
6334 let observation = PtyForegroundObservation {
6335 root_pid: 1,
6336 observed_pid: 2,
6337 observed_process: "node".to_owned(),
6338 readiness: ForegroundObservation {
6339 process_name: Some("node".to_owned()),
6340 has_child_processes: true,
6341 is_shell: false,
6342 },
6343 source: PtyForegroundSource::ProcessTree,
6344 };
6345 let verdict = resolve_foreground_verdict(&spec, &observation, RuntimePlatform::current());
6346 assert_eq!(verdict, ForegroundVerdict::Agent);
6347 assert_eq!(
6348 classify_pty_screen_state(Some(&verdict), None, None),
6349 PtyScreenState::Ready
6350 );
6351 }
6352
6353 #[test]
6354 fn foreground_probe_disarms_only_once_ready_and_rearms_on_a_fresh_gate() {
6355 assert_eq!(
6356 foreground_probe_schedule(&PtyScreenState::Ready),
6357 ForegroundProbeSchedule::Disarmed
6358 );
6359 assert_eq!(
6360 foreground_probe_schedule(&PtyScreenState::Unknown),
6361 ForegroundProbeSchedule::Armed
6362 );
6363 assert_eq!(
6364 foreground_probe_schedule(&PtyScreenState::OperatorGate {
6365 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate)
6366 }),
6367 ForegroundProbeSchedule::Armed
6368 );
6369 }
6370
6371 #[test]
6372 fn text_only_gate_transition_rearms_the_probe_only_when_leaving_ready() {
6373 let gate = PtyScreenState::OperatorGate {
6374 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate),
6375 };
6376 assert!(foreground_probe_rearms_immediately(
6377 &PtyScreenState::Ready,
6378 &gate
6379 ));
6380 assert!(!foreground_probe_rearms_immediately(
6383 &PtyScreenState::Unknown,
6384 &gate
6385 ));
6386 }
6387
6388 #[test]
6389 fn readiness_diagnostics_detects_an_ansi_split_gate_without_exposing_text() {
6390 let mut diagnostics = ReadinessDiagnostics::default();
6391 diagnostics.observe_output(b"\x1b[31mNo auth ");
6392 diagnostics.observe_output(b"\x1b[0mtype is selected");
6393 assert_eq!(
6394 diagnostics.operator_gate.as_ref().map(|gate| gate.kind),
6395 Some(OperatorGateKind::Authentication)
6396 );
6397 assert!(!diagnostics.summary().contains("No auth"));
6398 }
6399
6400 #[test]
6401 fn semantic_utf8_decoder_preserves_codepoints_split_across_pty_reads() {
6402 let mut decoder = Utf8ChunkDecoder::default();
6403 let bytes = "ready Привет".as_bytes();
6404 let split = bytes
6405 .windows(2)
6406 .position(|window| window[0] >= 0x80 && window[1] >= 0x80)
6407 .expect("Cyrillic text contains adjacent UTF-8 bytes")
6408 + 1;
6409 let first = decoder.push(&bytes[..split]);
6410 let second = decoder.push(&bytes[split..]);
6411 assert_eq!(format!("{first}{second}"), "ready Привет");
6412 assert!(!first.contains('\u{fffd}'));
6413 assert!(!second.contains('\u{fffd}'));
6414 }
6415
6416 #[test]
6417 fn semantic_utf8_decoder_replaces_invalid_bytes_without_stalling() {
6418 let mut decoder = Utf8ChunkDecoder::default();
6419 assert_eq!(decoder.push(b"ok\xfftail"), "ok\u{fffd}tail");
6420 assert_eq!(decoder.push(" Привет".as_bytes()), " Привет");
6421 }
6422
6423 #[test]
6424 fn fresh_claude_pty_preassigns_the_exact_vendor_session_id_argv() {
6425 let claude = builtin_adapter_registry()
6426 .binding(AdapterFamily::PtySemantic, "claude-code")
6427 .expect("Claude PTY binding");
6428 let mut args = Vec::new();
6429 let identity = prepare_fresh_pty_provider_session(Some(claude), false, true, &mut args)
6430 .expect("fresh Claude provider identity");
6431 let parsed = uuid::Uuid::parse_str(&identity.id).expect("valid Claude UUID");
6432 assert_eq!(parsed.get_version_num(), 4);
6433 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
6434 assert!(identity.transcript_path.is_none());
6435 assert_eq!(args, [OsString::from("--session-id"), OsString::from(identity.id)]);
6436 }
6437
6438 #[test]
6439 fn fresh_codex_and_resumed_claude_do_not_preassign_a_second_identity() {
6440 let adapters = builtin_adapter_registry();
6441 let codex = adapters
6442 .binding(AdapterFamily::PtySemantic, "codex")
6443 .expect("Codex PTY binding");
6444 let claude = adapters
6445 .binding(AdapterFamily::PtySemantic, "claude-code")
6446 .expect("Claude PTY binding");
6447 let mut codex_args = Vec::new();
6448 assert!(prepare_fresh_pty_provider_session(Some(codex), false, true, &mut codex_args)
6449 .is_none());
6450 assert!(codex_args.is_empty());
6451
6452 let mut resume_args = vec![OsString::from("--resume"), OsString::from("vendor-id")];
6453 assert!(prepare_fresh_pty_provider_session(Some(claude), true, true, &mut resume_args)
6454 .is_none());
6455 assert_eq!(
6456 resume_args,
6457 [OsString::from("--resume"), OsString::from("vendor-id")]
6458 );
6459 }
6460
6461 #[test]
6462 fn raw_pty_policy_omits_all_identity_and_semantic_startup_paths() {
6463 let adapters = builtin_adapter_registry();
6464 let claude = adapters
6465 .binding(AdapterFamily::PtySemantic, "claude-code")
6466 .expect("Claude PTY binding");
6467 let codex = adapters
6468 .binding(AdapterFamily::PtySemantic, "codex")
6469 .expect("Codex PTY binding");
6470 let kimi = adapters
6471 .binding(AdapterFamily::PtySemantic, "kimi")
6472 .expect("Kimi PTY binding");
6473 let policy = ProviderRuntimePolicy::raw_pty();
6474 let mut args = Vec::new();
6475
6476 assert!(prepare_fresh_pty_provider_session(Some(claude), false, false, &mut args)
6477 .is_none());
6478 assert!(args.is_empty());
6479 assert!(!should_probe_pty_identity(policy, Some(codex), false, "codex"));
6480 assert!(!should_probe_pty_identity(policy, Some(kimi), false, "kimi"));
6481 assert!(!should_attach_pty_provider_stream(policy));
6482 }
6483
6484 #[test]
6485 fn identity_probe_requires_structured_prompt_for_codex_and_kimi() {
6486 let adapters = builtin_adapter_registry();
6487 let codex = adapters
6488 .binding(AdapterFamily::PtySemantic, "codex")
6489 .expect("Codex PTY binding");
6490 let kimi = adapters
6491 .binding(AdapterFamily::PtySemantic, "kimi")
6492 .expect("Kimi PTY binding");
6493 let without_structured_prompt =
6494 ProviderRuntimePolicy::new(true, true, false, true, false, false)
6495 .expect("identity observation policy without structured prompt");
6496
6497 assert!(!should_probe_pty_identity(
6498 without_structured_prompt,
6499 Some(codex),
6500 false,
6501 "codex",
6502 ));
6503 assert!(!should_probe_pty_identity(
6504 without_structured_prompt,
6505 Some(kimi),
6506 false,
6507 "kimi",
6508 ));
6509
6510 let with_structured_prompt =
6511 ProviderRuntimePolicy::new(true, true, true, true, false, false)
6512 .expect("identity probe policy");
6513 assert!(should_probe_pty_identity(
6514 with_structured_prompt,
6515 Some(codex),
6516 false,
6517 "codex",
6518 ));
6519 assert!(should_probe_pty_identity(
6520 with_structured_prompt,
6521 Some(kimi),
6522 false,
6523 "kimi",
6524 ));
6525 }
6526
6527 #[test]
6528 fn runtime_policy_admits_raw_native_resume_but_denies_unverified_prompt_injection() {
6529 let raw = ProviderRuntimePolicy::raw_pty();
6530 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, false).is_ok());
6531 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, false)
6532 .unwrap_err()
6533 .contains("SemanticReadiness"));
6534 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, true).is_ok());
6535 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, true)
6536 .unwrap_err()
6537 .contains("SemanticReadiness"));
6538
6539 let resume_without_prompt =
6540 ProviderRuntimePolicy::new(true, false, false, true, true, false)
6541 .expect("identity and resume policy");
6542 assert!(validate_spawn_runtime_policy(
6543 resume_without_prompt,
6544 TransportKind::Pty,
6545 false,
6546 true,
6547 )
6548 .is_ok());
6549 assert!(validate_spawn_runtime_policy(
6550 resume_without_prompt,
6551 TransportKind::Pty,
6552 true,
6553 true,
6554 )
6555 .unwrap_err()
6556 .contains("SemanticReadiness"));
6557 }
6558
6559 #[test]
6560 fn acp_transport_bypasses_the_pty_semantic_policy_gate_pty_and_pipe_still_enforce_it() {
6561 let no_pty_capabilities_at_all = ProviderRuntimePolicy::new(
6567 false, false, false, false, false, false,
6568 )
6569 .expect("an all-false policy is internally valid");
6570 assert!(validate_spawn_runtime_policy(
6571 no_pty_capabilities_at_all,
6572 TransportKind::Acp,
6573 false,
6574 false,
6575 )
6576 .is_ok());
6577 assert!(validate_spawn_runtime_policy(
6581 no_pty_capabilities_at_all,
6582 TransportKind::Pty,
6583 false,
6584 false,
6585 )
6586 .unwrap_err()
6587 .contains("RawPtyLifecycle"));
6588 assert!(validate_spawn_runtime_policy(
6589 no_pty_capabilities_at_all,
6590 TransportKind::Pipe,
6591 false,
6592 false,
6593 )
6594 .unwrap_err()
6595 .contains("RawPtyLifecycle"));
6596 }
6597
6598 #[test]
6599 fn prompt_render_probe_ignores_terminal_wrapping_and_uses_the_tail() {
6600 let prompt = "prefix with spaces\nand punctuation: final-render-token-1234567890";
6601 let probe = prompt_render_probe(prompt);
6602 assert!("screen prefix with spaces and punctuation final render token 1234567890"
6603 .chars()
6604 .filter(|character| character.is_alphanumeric())
6605 .flat_map(char::to_lowercase)
6606 .collect::<String>()
6607 .contains(&probe));
6608 assert!(probe.chars().count() <= 32);
6609 }
6610
6611 #[test]
6612 fn prompt_render_requires_new_sequence_and_visible_tail_evidence() {
6613 let probe = prompt_render_probe("final render token");
6614 let baseline = snapshot(7, "old composer");
6615 assert!(!prompt_rendered(
6616 &snapshot(7, "final\nrender\ntoken"),
6617 &baseline,
6618 &probe
6619 ));
6620 assert!(!prompt_rendered(
6621 &snapshot(8, "unrelated redraw"),
6622 &baseline,
6623 &probe
6624 ));
6625 assert!(prompt_rendered(
6626 &snapshot(8, "composer\nfinal\nrender\ntoken"),
6627 &baseline,
6628 &probe
6629 ));
6630 assert!(prompt_rendered(
6631 &snapshot(8, "composer [Pasted Content 4096 chars]"),
6632 &baseline,
6633 &probe
6634 ));
6635 assert!(prompt_rendered(
6636 &snapshot(8, "composer [Pasted text #1 +6 lines]"),
6637 &baseline,
6638 &probe
6639 ));
6640 }
6641
6642 #[test]
6643 fn an_existing_paste_placeholder_cannot_pass_on_an_unrelated_redraw() {
6644 let probe = prompt_render_probe("a new long prompt");
6645 assert!(!prompt_rendered(
6646 &snapshot(8, "composer [Pasted Content 4096 chars]\nunrelated redraw"),
6647 &snapshot(7, "composer [Pasted Content 4096 chars]"),
6648 &probe
6649 ));
6650 assert!(!prompt_rendered(
6651 &snapshot(8, "composer [Pasted text #1 +6 lines]\nunrelated redraw"),
6652 &snapshot(7, "composer [Pasted text #1 +6 lines]"),
6653 &probe
6654 ));
6655 }
6656
6657 #[test]
6658 fn punctuation_only_prompt_cannot_pass_on_an_unrelated_redraw() {
6659 let probe = prompt_render_probe("!?---");
6660 assert!(probe.is_empty());
6661 assert!(!prompt_rendered(
6662 &snapshot(2, "unrelated redraw"),
6663 &snapshot(1, "old composer"),
6664 &probe
6665 ));
6666 }
6667
6668 #[test]
6669 fn prompt_probe_matches_the_sanitized_terminal_payload() {
6670 let prompt = "payload\u{1b}tail";
6671 let sanitized = gate4agent_types::sanitize_prompt_text(prompt);
6672 let probe = prompt_render_probe(&sanitized);
6673 assert!(prompt_rendered(
6674 &snapshot(2, "composer payload<ESC>tail"),
6675 &snapshot(1, "old composer"),
6676 &probe
6677 ));
6678 }
6679
6680 #[test]
6681 fn lag_and_data_gap_reserve_missed_provider_source_positions() {
6682 let mut next = 7;
6683 assert_eq!(reserve_provider_gap_sequence(&mut next, 3), Some(9));
6684 assert_eq!(next, 10);
6685 assert_eq!(reserve_provider_gap_sequence(&mut next, 0), None);
6686 assert_eq!(next, 10);
6687
6688 next = u64::MAX;
6689 assert_eq!(reserve_provider_gap_sequence(&mut next, 1), None);
6690 assert_eq!(next, u64::MAX);
6691 }
6692
6693 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) │";
6706
6707 #[test]
6708 fn bare_detector_misses_the_live_ansi_sample_that_rate_limit_feed_catches() {
6709 let bare = RateLimitDetector::new_for_tool(CliTool::Codex);
6712 assert!(bare.detect(CODEX_STATUS_RAW_ANSI).is_none());
6713
6714 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6717 let info = feed
6718 .detect(CODEX_STATUS_RAW_ANSI)
6719 .expect("quota-state line must be recognized once ANSI is stripped");
6720 assert_eq!(info.limit_type, RateLimitType::Session);
6721 assert_eq!(info.usage_percent, Some(0.0));
6722 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6723 }
6724
6725 #[test]
6726 fn rate_limit_feed_reassembles_a_quota_state_line_split_mid_escape_and_mid_row() {
6727 let first =
6731 "│ 5h limit: \x1b[m[████████████████████] 100% left\x1b";
6732 let second = "[2m (resets 00:08 on 31 Aug) │\r\n";
6733
6734 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6735 assert!(
6736 feed.detect(first).is_none(),
6737 "the row is not complete yet, so nothing should match on the first chunk"
6738 );
6739 let info = feed
6740 .detect(second)
6741 .expect("the row completes once the second chunk arrives");
6742 assert_eq!(info.limit_type, RateLimitType::Session);
6743 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6744 }
6745
6746 #[test]
6747 fn rate_limit_feed_strips_ansi_before_matching_a_colored_failure_message() {
6748 let raw = "\x1b[31mError: rate limit exceeded\x1b[0m. Please wait.";
6752 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6753 let info = feed
6754 .detect(raw)
6755 .expect("a colored refusal message must still be recognized");
6756 assert_eq!(info.limit_type, RateLimitType::Unknown);
6757 }
6758
6759 #[test]
6760 fn rate_limit_feed_bounds_its_buffer_across_a_newline_free_redraw() {
6761 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6766 let noise = "x".repeat(super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES * 3);
6767 assert!(feed.detect(&noise).is_none());
6768 assert!(feed.buffer.len() <= super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES);
6769
6770 let info = feed
6771 .detect(CODEX_STATUS_RAW_ANSI)
6772 .expect("a real quota-state line must still be recognized after the noise");
6773 assert_eq!(info.limit_type, RateLimitType::Session);
6774 }
6775
6776 #[test]
6781 fn full_auto_maps_to_the_permissive_host_policy() {
6782 assert_eq!(host_policy_for_approval_level(ApprovalLevel::FullAuto), HostPolicy::Yolo);
6786 }
6787
6788 #[test]
6789 fn read_only_maps_to_the_read_only_host_policy() {
6790 assert_eq!(
6791 host_policy_for_approval_level(ApprovalLevel::ReadOnly),
6792 HostPolicy::ReadOnly
6793 );
6794 }
6795
6796 #[test]
6797 fn moderate_and_unmanaged_both_fall_back_to_the_default_host_policy() {
6798 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Moderate), HostPolicy::Auto);
6799 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Unmanaged), HostPolicy::Auto);
6800 assert_eq!(HostPolicy::default(), HostPolicy::Auto);
6801 }
6802
6803 #[test]
6804 fn no_approval_level_ever_maps_to_a_refusing_policy_except_read_only_itself() {
6805 for level in [
6810 ApprovalLevel::FullAuto,
6811 ApprovalLevel::Moderate,
6812 ApprovalLevel::ReadOnly,
6813 ApprovalLevel::Unmanaged,
6814 ] {
6815 assert_ne!(
6816 host_policy_for_approval_level(level),
6817 HostPolicy::Deny,
6818 "{level:?} must never map to HostPolicy::Deny"
6819 );
6820 }
6821 }
6822
6823 #[test]
6831 fn defers_permission_requests_matches_the_verified_provider_table() {
6832 let claude = AgentId::new("claude").unwrap();
6837 assert!(!defers_permission_requests(&claude, ApprovalLevel::FullAuto));
6838 assert!(defers_permission_requests(&claude, ApprovalLevel::Moderate));
6839 assert!(defers_permission_requests(&claude, ApprovalLevel::ReadOnly));
6843 assert!(!defers_permission_requests(&claude, ApprovalLevel::Unmanaged));
6847
6848 let codex = AgentId::new("codex").unwrap();
6849 assert!(!defers_permission_requests(&codex, ApprovalLevel::FullAuto));
6850 assert!(!defers_permission_requests(&codex, ApprovalLevel::Moderate));
6855 assert!(defers_permission_requests(&codex, ApprovalLevel::ReadOnly));
6856 assert!(!defers_permission_requests(&codex, ApprovalLevel::Unmanaged));
6858
6859 let grok = AgentId::new("grok").unwrap();
6860 assert!(!defers_permission_requests(&grok, ApprovalLevel::FullAuto));
6861 assert!(defers_permission_requests(&grok, ApprovalLevel::Moderate));
6862 assert!(defers_permission_requests(&grok, ApprovalLevel::ReadOnly));
6866 assert!(!defers_permission_requests(&grok, ApprovalLevel::Unmanaged));
6868
6869 let kimi = AgentId::new("kimi").unwrap();
6870 assert!(!defers_permission_requests(&kimi, ApprovalLevel::FullAuto));
6871 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Moderate));
6874 assert!(!defers_permission_requests(&kimi, ApprovalLevel::ReadOnly));
6878 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Unmanaged));
6880 }
6881
6882 fn session_mode(id: &str) -> SessionMode {
6889 SessionMode { id: id.to_owned(), name: id.to_owned(), description: None }
6890 }
6891
6892 #[test]
6893 fn required_acp_mode_matches_the_sourced_table() {
6894 let claude = AgentId::new("claude").unwrap();
6899 assert_eq!(
6900 required_acp_mode(&claude, ApprovalLevel::FullAuto),
6901 Ok(Some(ModeId::new("bypassPermissions")))
6902 );
6903 assert_eq!(
6904 required_acp_mode(&claude, ApprovalLevel::Moderate),
6905 Ok(Some(ModeId::new("acceptEdits")))
6906 );
6907 assert_eq!(
6911 required_acp_mode(&claude, ApprovalLevel::ReadOnly),
6912 Ok(Some(ModeId::new("default")))
6913 );
6914 assert_eq!(required_acp_mode(&claude, ApprovalLevel::Unmanaged), Ok(None));
6915
6916 let codex = AgentId::new("codex").unwrap();
6917 assert_eq!(
6918 required_acp_mode(&codex, ApprovalLevel::FullAuto),
6919 Ok(Some(ModeId::new("agent-full-access")))
6920 );
6921 assert_eq!(
6922 required_acp_mode(&codex, ApprovalLevel::Moderate),
6923 Ok(Some(ModeId::new("agent")))
6924 );
6925 assert_eq!(
6926 required_acp_mode(&codex, ApprovalLevel::ReadOnly),
6927 Ok(Some(ModeId::new("read-only")))
6928 );
6929 assert_eq!(required_acp_mode(&codex, ApprovalLevel::Unmanaged), Ok(None));
6930
6931 let kimi = AgentId::new("kimi").unwrap();
6943 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::FullAuto), Ok(None));
6944 assert_eq!(
6945 acp_approval_level_args(&kimi, ApprovalLevel::FullAuto),
6946 vec!["--auto".to_owned()],
6947 "kimi's FullAuto must reach the process through argv, since it has no ACP mode"
6948 );
6949 for level in [ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
6950 assert!(
6951 required_acp_mode(&kimi, level).is_err(),
6952 "kimi at {level:?} has neither a sourced ACP mode id nor vendor flags, so it must refuse"
6953 );
6954 }
6955 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::Unmanaged), Ok(None));
6956
6957 let gemini = AgentId::new("gemini").unwrap();
6960 for (level, mode) in [
6961 (ApprovalLevel::FullAuto, "yolo"),
6962 (ApprovalLevel::Moderate, "autoEdit"),
6963 (ApprovalLevel::ReadOnly, "plan"),
6964 ] {
6965 assert_eq!(required_acp_mode(&gemini, level), Ok(Some(ModeId::new(mode))));
6966 assert!(acp_approval_level_args(&gemini, level).is_empty());
6967 }
6968 let cursor = AgentId::new("cursor-agent").unwrap();
6972 assert_eq!(required_acp_mode(&cursor, ApprovalLevel::FullAuto), Ok(None));
6973 assert_eq!(acp_approval_level_args(&cursor, ApprovalLevel::FullAuto), vec!["--force".to_owned()]);
6974 assert_eq!(
6975 required_acp_mode(&cursor, ApprovalLevel::Moderate),
6976 Ok(Some(ModeId::new("agent")))
6977 );
6978 assert_eq!(
6979 required_acp_mode(&cursor, ApprovalLevel::ReadOnly),
6980 Ok(Some(ModeId::new("plan")))
6981 );
6982 assert!(!defers_permission_requests(&cursor, ApprovalLevel::FullAuto));
6983 assert!(defers_permission_requests(&gemini, ApprovalLevel::Moderate));
6984 assert!(
6985 acp_approval_level_args(&kimi, ApprovalLevel::Unmanaged).is_empty(),
6986 "Unmanaged imposes nothing, so it must add no argv flags either"
6987 );
6988
6989 let grok = AgentId::new("grok").unwrap();
6996 assert_eq!(required_acp_mode(&grok, ApprovalLevel::FullAuto), Ok(None));
6997 assert_eq!(
6998 acp_approval_level_args(&grok, ApprovalLevel::FullAuto),
6999 vec!["--always-approve".to_owned()],
7000 );
7001 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Moderate), Ok(None));
7002 assert_eq!(
7003 acp_approval_level_args(&grok, ApprovalLevel::Moderate),
7004 vec!["--permission-mode".to_owned(), "auto".to_owned()],
7005 );
7006 assert!(
7007 required_acp_mode(&grok, ApprovalLevel::ReadOnly).is_err(),
7008 "grok at ReadOnly is Unsupported outright, so it must refuse"
7009 );
7010 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Unmanaged), Ok(None));
7011 }
7012
7013 #[test]
7024 fn required_acp_mode_never_silently_permits_auto_except_for_unmanaged() {
7025 for id in ["claude", "codex", "grok", "kimi"] {
7026 let agent = AgentId::new(id).unwrap();
7027 for level in [ApprovalLevel::FullAuto, ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
7028 match required_acp_mode(&agent, level) {
7029 Ok(Some(mode_id)) => assert_ne!(
7030 mode_id.as_str(),
7031 "auto",
7032 "{id} at {level:?} must never silently resolve the vendor's own default 'auto'"
7033 ),
7034 Ok(None) => assert!(
7035 !acp_approval_level_args(&agent, level).is_empty(),
7036 "{id} at {level:?} resolved Ok(None) while carrying no vendor flags -- \
7037 that leaves the session at the agent's own default. Only Unmanaged, or a \
7038 level argv actually applies, may resolve to no mode"
7039 ),
7040 Err(_) => {} }
7042 }
7043 assert_eq!(
7044 required_acp_mode(&agent, ApprovalLevel::Unmanaged),
7045 Ok(None),
7046 "{id}: Unmanaged is the one level allowed to apply nothing"
7047 );
7048 }
7049 }
7050
7051 #[test]
7055 fn opencode_and_mcode_acp_approval_is_host_policy_full_auto_only() {
7056 for id in ["opencode", "mcode"] {
7057 let agent = AgentId::new(id).unwrap();
7058 assert_eq!(required_acp_mode(&agent, ApprovalLevel::FullAuto), Ok(None), "{id}");
7059 assert!(acp_approval_level_args(&agent, ApprovalLevel::FullAuto).is_empty());
7060 assert_eq!(required_acp_mode(&agent, ApprovalLevel::Unmanaged), Ok(None), "{id}");
7061 assert!(required_acp_mode(&agent, ApprovalLevel::Moderate).is_err(), "{id}");
7062 assert!(required_acp_mode(&agent, ApprovalLevel::ReadOnly).is_err(), "{id}");
7063 }
7064 }
7065
7066 #[test]
7067 fn approval_level_not_offered_message_refuses_by_name_and_lists_what_was_offered() {
7068 let offered = vec![session_mode("bypassPermissions"), session_mode("default")];
7069 let mode_id = ModeId::new("plan");
7070 let message = approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered)
7071 .expect("'plan' was not among the offered modes");
7072 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
7073 assert!(message.contains("bypassPermissions"));
7074 assert!(message.contains("default"));
7075 assert!(message.contains("ReadOnly"));
7076 }
7077
7078 #[test]
7079 fn approval_level_not_offered_message_is_none_when_the_agent_announced_it() {
7080 let offered = vec![session_mode("plan")];
7081 let mode_id = ModeId::new("plan");
7082 assert_eq!(
7083 approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered),
7084 None
7085 );
7086 }
7087
7088 #[test]
7089 fn approval_level_not_offered_message_handles_an_agent_that_announces_no_modes_at_all() {
7090 let mode_id = ModeId::new("bypassPermissions");
7091 let message = approval_level_not_offered_message(ApprovalLevel::FullAuto, &mode_id, &[])
7092 .expect("an empty mode catalog never offers anything");
7093 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
7094 assert!(message.contains("offered: []"));
7095 }
7096
7097 use super::{NativeEffectShell, NativeSessionKey, OwnedProviderSession};
7114 use gate4agent_catalog::{AgentRegistry as FixtureAgentRegistry, AgentSpec as FixtureAgentSpec};
7115 use gate4agent_types::ControlObservation;
7116 use std::collections::VecDeque;
7117
7118 fn fixture_pipe_key() -> NativeSessionKey {
7119 NativeSessionKey {
7120 instance_id: gate4agent_types::AgentInstanceId(9_001),
7121 generation: gate4agent_types::SessionGeneration(1),
7122 }
7123 }
7124
7125 fn fixture_pipe_source() -> gate4agent_types::ProviderSource {
7126 gate4agent_types::ProviderSource {
7127 family: AdapterFamily::Pipe,
7128 binding: gate4agent_types::AdapterBinding::new(
7129 gate4agent_types::AdapterId::new("fixture").unwrap(),
7130 "1",
7131 gate4agent_types::AdapterVerification::SyntheticFixture,
7132 )
7133 .unwrap(),
7134 }
7135 }
7136
7137 #[cfg(windows)]
7138 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7139 gate4agent_types::LaunchSpec {
7140 program: "powershell.exe".to_owned(),
7141 fixed_args: vec![
7142 "-NoProfile".to_owned(),
7143 "-NonInteractive".to_owned(),
7144 "-Command".to_owned(),
7145 "[Console]::In.ReadToEnd() | Out-Null; exit 0".to_owned(),
7146 ],
7147 }
7148 }
7149
7150 #[cfg(not(windows))]
7151 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7152 gate4agent_types::LaunchSpec {
7153 program: "sh".to_owned(),
7154 fixed_args: vec!["-c".to_owned(), "cat >/dev/null; exit 0".to_owned()],
7155 }
7156 }
7157
7158 #[cfg(windows)]
7159 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7160 gate4agent_types::LaunchSpec {
7161 program: "powershell.exe".to_owned(),
7162 fixed_args: vec![
7163 "-NoProfile".to_owned(),
7164 "-NonInteractive".to_owned(),
7165 "-Command".to_owned(),
7166 "Start-Sleep -Seconds 30".to_owned(),
7167 ],
7168 }
7169 }
7170
7171 #[cfg(not(windows))]
7172 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7173 gate4agent_types::LaunchSpec {
7174 program: "sh".to_owned(),
7175 fixed_args: vec!["-c".to_owned(), "sleep 30".to_owned()],
7176 }
7177 }
7178
7179 async fn spawn_fixture_pipe_shell(
7180 launch: gate4agent_types::LaunchSpec,
7181 ) -> (NativeEffectShell, NativeSessionKey) {
7182 let session = gate4agent::PipeSession::spawn_with_launch(
7183 gate4agent::core::types::SessionConfig::default(),
7184 "prompt",
7185 &launch,
7186 gate4agent_types::PipePromptDelivery::StdinClose,
7187 )
7188 .await
7189 .expect("fixture pipe process must spawn");
7190 let events = session.subscribe();
7191 let key = fixture_pipe_key();
7192 let mut shell = NativeEffectShell::new(
7193 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7194 .expect("empty fixture catalog"),
7195 );
7196 shell.pipe_sessions.insert(
7197 key,
7198 OwnedProviderSession {
7199 source: fixture_pipe_source(),
7200 session,
7201 events,
7202 pending_events: VecDeque::new(),
7203 pending_provider_events: VecDeque::new(),
7204 next_provider_sequence: 1,
7205 observed_exit_code: None,
7206 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7207 },
7208 );
7209 (shell, key)
7210 }
7211
7212 #[tokio::test]
7213 async fn stop_native_pipe_session_reports_the_real_exit_code_when_not_forced() {
7214 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_graceful_exit_launch()).await;
7215
7216 match shell.stop_native(key, false).await {
7217 ControlObservation::StopCompleted {
7218 forced, exit_code, ..
7219 } => {
7220 assert!(!forced, "a process that exits on its own must not be forced");
7221 assert_eq!(exit_code, Some(0));
7222 }
7223 other => panic!("expected StopCompleted, got {other:?}"),
7224 }
7225 }
7226
7227 #[tokio::test]
7228 async fn stop_native_pipe_session_force_true_kills_immediately_without_waiting() {
7229 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_ignore_stdin_launch()).await;
7230
7231 let start = std::time::Instant::now();
7232 match shell.stop_native(key, true).await {
7233 ControlObservation::StopCompleted { forced, .. } => {
7234 assert!(forced, "force=true must always report forced");
7235 }
7236 other => panic!("expected StopCompleted, got {other:?}"),
7237 }
7238 assert!(
7239 start.elapsed()
7240 < std::time::Duration::from_secs(gate4agent::pipe::PIPE_GRACEFUL_STOP_BOUND_SECS),
7241 "force=true must not wait out the graceful bound"
7242 );
7243 }
7244
7245 #[cfg(windows)]
7261 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7262 gate4agent_types::LaunchSpec {
7263 program: "powershell.exe".to_owned(),
7264 fixed_args: vec![
7265 "-NoLogo".to_owned(),
7266 "-NoProfile".to_owned(),
7267 "-NonInteractive".to_owned(),
7268 "-ExecutionPolicy".to_owned(),
7269 "Bypass".to_owned(),
7270 "-Command".to_owned(),
7271 ACP_HANDSHAKE_SCRIPT.to_owned(),
7272 ],
7273 }
7274 }
7275
7276 #[cfg(not(windows))]
7277 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7278 gate4agent_types::LaunchSpec {
7279 program: "python3".to_owned(),
7280 fixed_args: vec!["-u".to_owned(), "-c".to_owned(), ACP_HANDSHAKE_SCRIPT.to_owned()],
7281 }
7282 }
7283
7284 #[cfg(windows)]
7285 const ACP_HANDSHAKE_SCRIPT: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7286function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7287$initialize = [Console]::ReadLine() | ConvertFrom-Json
7288Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7289$newSession = [Console]::ReadLine() | ConvertFrom-Json
7290Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{sessionId='fixture-acp-session'}}
7291while ($true) {
7292 $line = [Console]::ReadLine()
7293 if ($null -eq $line) { exit 0 }
7294}"#;
7295 #[cfg(not(windows))]
7296 const ACP_HANDSHAKE_SCRIPT: &str = r#"import json,sys
7297def read_message():
7298 line=sys.stdin.readline()
7299 if not line: return None
7300 return json.loads(line)
7301def write_message(message):
7302 print(json.dumps(message),flush=True)
7303
7304initialize=read_message()
7305write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7306new_session=read_message()
7307write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{'sessionId':'fixture-acp-session'}})
7308while True:
7309 msg=read_message()
7310 if msg is None:
7311 sys.exit(0)"#;
7312
7313 fn fixture_acp_key() -> NativeSessionKey {
7314 NativeSessionKey {
7315 instance_id: gate4agent_types::AgentInstanceId(9_002),
7316 generation: gate4agent_types::SessionGeneration(1),
7317 }
7318 }
7319
7320 fn fixture_acp_source() -> gate4agent_types::ProviderSource {
7321 gate4agent_types::ProviderSource {
7322 family: AdapterFamily::Acp,
7323 binding: gate4agent_types::AdapterBinding::new(
7324 gate4agent_types::AdapterId::new("fixture").unwrap(),
7325 "1",
7326 gate4agent_types::AdapterVerification::SyntheticFixture,
7327 )
7328 .unwrap(),
7329 }
7330 }
7331
7332 async fn spawn_fixture_acp_shell() -> (NativeEffectShell, NativeSessionKey) {
7333 let session = gate4agent::acp::AcpSession::spawn_with_launch(
7334 gate4agent::CliTool::ClaudeCode,
7335 &std::env::current_dir().expect("cwd"),
7336 gate4agent::acp::AcpSessionOptions::default(),
7337 &acp_fixture_launch(),
7338 )
7339 .await
7340 .expect("fixture ACP handshake must succeed");
7341 let events = session.subscribe();
7342 let key = fixture_acp_key();
7343 let mut shell = NativeEffectShell::new(
7344 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7345 .expect("empty fixture catalog"),
7346 );
7347 shell.acp_sessions.insert(
7348 key,
7349 OwnedProviderSession {
7350 source: fixture_acp_source(),
7351 session,
7352 events,
7353 pending_events: VecDeque::new(),
7354 pending_provider_events: VecDeque::new(),
7355 next_provider_sequence: 1,
7356 observed_exit_code: None,
7357 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7358 },
7359 );
7360 (shell, key)
7361 }
7362
7363 #[tokio::test]
7364 async fn stop_native_acp_session_reports_the_real_exit_code_when_not_forced() {
7365 let (mut shell, key) = spawn_fixture_acp_shell().await;
7366
7367 match shell.stop_native(key, false).await {
7368 ControlObservation::StopCompleted {
7369 forced, exit_code, ..
7370 } => {
7371 assert!(!forced, "a process that exits on its own must not be forced");
7372 assert_eq!(exit_code, Some(0));
7373 }
7374 other => panic!("expected StopCompleted, got {other:?}"),
7375 }
7376 }
7377
7378 #[cfg(windows)]
7396 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7397 gate4agent_types::LaunchSpec {
7398 program: "powershell.exe".to_owned(),
7399 fixed_args: vec![
7400 "-NoLogo".to_owned(),
7401 "-NoProfile".to_owned(),
7402 "-NonInteractive".to_owned(),
7403 "-ExecutionPolicy".to_owned(),
7404 "Bypass".to_owned(),
7405 "-Command".to_owned(),
7406 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7407 ],
7408 }
7409 }
7410
7411 #[cfg(not(windows))]
7412 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7413 gate4agent_types::LaunchSpec {
7414 program: "python3".to_owned(),
7415 fixed_args: vec![
7416 "-u".to_owned(),
7417 "-c".to_owned(),
7418 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7419 ],
7420 }
7421 }
7422
7423 #[cfg(windows)]
7424 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7425function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7426$initialize = [Console]::ReadLine() | ConvertFrom-Json
7427Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7428$newSession = [Console]::ReadLine() | ConvertFrom-Json
7429Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{}}
7430while ($true) {
7431 $line = [Console]::ReadLine()
7432 if ($null -eq $line) { exit 0 }
7433}"#;
7434 #[cfg(not(windows))]
7435 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"import json,sys
7436def read_message():
7437 line=sys.stdin.readline()
7438 if not line: return None
7439 return json.loads(line)
7440def write_message(message):
7441 print(json.dumps(message),flush=True)
7442
7443initialize=read_message()
7444write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7445new_session=read_message()
7446write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{}})
7447while True:
7448 msg=read_message()
7449 if msg is None:
7450 sys.exit(0)"#;
7451
7452 fn fixture_acp_spawn_agent_id() -> AgentId {
7453 AgentId::new("claude").expect("builtin catalog names 'claude'")
7454 }
7455
7456 fn fixture_acp_spawn_agent_spec(launch: gate4agent_types::LaunchSpec) -> FixtureAgentSpec {
7462 let mut spec = gate4agent_catalog::builtin_registry()
7463 .get(&fixture_acp_spawn_agent_id())
7464 .cloned()
7465 .expect("builtin catalog must declare claude");
7466 spec.capabilities
7467 .transports
7468 .acp
7469 .as_mut()
7470 .expect("claude must declare ACP capability")
7471 .launch_override = Some(launch);
7472 spec
7473 }
7474
7475 fn fixture_acp_spawn_key() -> NativeSessionKey {
7476 NativeSessionKey {
7477 instance_id: gate4agent_types::AgentInstanceId(9_101),
7478 generation: gate4agent_types::SessionGeneration(1),
7479 }
7480 }
7481
7482 async fn spawn_native_acp_fixture(
7488 launch: gate4agent_types::LaunchSpec,
7489 provider_session_identity: bool,
7490 ) -> (NativeEffectShell, NativeSessionKey, ControlObservation) {
7491 let mut policy = ProviderRuntimePolicy::none();
7492 policy.provider_session_identity = provider_session_identity;
7493 let key = fixture_acp_spawn_key();
7494 let mut shell = NativeEffectShell::new(
7495 FixtureAgentRegistry::new([fixture_acp_spawn_agent_spec(launch)])
7496 .expect("single-agent fixture catalog"),
7497 );
7498 let envelope = gate4agent_types::EffectEnvelope {
7499 operation_id: gate4agent_types::OperationId(1),
7500 instance_id: key.instance_id,
7501 generation: key.generation,
7502 effect: gate4agent_types::ControlEffect::Spawn {
7503 agent_id: fixture_acp_spawn_agent_id(),
7504 transport: TransportKind::Acp,
7505 runtime_policy: policy,
7506 request: gate4agent_types::StartRequest {
7507 working_directory: std::env::current_dir()
7508 .expect("cwd")
7509 .to_string_lossy()
7510 .into_owned(),
7511 terminal_size: gate4agent_types::TerminalSize {
7512 rows: 24,
7513 columns: 80,
7514 },
7515 initial_prompt: None,
7516 session_options: None,
7517 approval_level: ApprovalLevel::Unmanaged,
7518 },
7519 },
7520 };
7521 let observation = shell.execute(envelope).await.observation;
7522 (shell, key, observation)
7523 }
7524
7525 #[tokio::test]
7526 async fn acp_spawn_with_a_real_sessionid_emits_session_identity_observed_after_session_start() {
7527 let (mut shell, key, spawned) =
7528 spawn_native_acp_fixture(acp_fixture_launch(), true).await;
7529 match spawned {
7530 ControlObservation::Spawned { .. } => {}
7531 other => panic!("expected Spawned, got {other:?}"),
7532 }
7533
7534 let mut provider_events = shell
7535 .collect_provider_events()
7536 .into_iter()
7537 .filter_map(|envelope| match envelope.observation {
7538 ControlObservation::ProviderEvent { event, .. } => Some(event),
7539 _ => None,
7540 });
7541
7542 match provider_events.next() {
7543 Some(ProviderEvent::SessionStarted { .. }) => {}
7544 other => panic!("expected SessionStarted first, got {other:?}"),
7545 }
7546 match provider_events.next() {
7547 Some(ProviderEvent::SessionIdentityObserved { identity }) => {
7548 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
7549 assert_eq!(identity.id, "fixture-acp-session");
7550 assert!(identity.transcript_path.is_none());
7551 }
7552 other => panic!("expected SessionIdentityObserved second, got {other:?}"),
7553 }
7554 assert!(
7555 provider_events.next().is_none(),
7556 "expected exactly one SessionIdentityObserved and nothing after it"
7557 );
7558
7559 let _ = shell.stop_native(key, true).await;
7560 }
7561
7562 #[tokio::test]
7563 async fn acp_spawn_with_no_sessionid_emits_no_session_identity_observed() {
7564 let (mut shell, key, spawned) =
7565 spawn_native_acp_fixture(acp_fixture_launch_no_session_id(), true).await;
7566 match spawned {
7567 ControlObservation::Spawned { .. } => {}
7568 other => panic!("expected Spawned, got {other:?}"),
7569 }
7570
7571 let provider_events: Vec<_> = shell
7572 .collect_provider_events()
7573 .into_iter()
7574 .filter_map(|envelope| match envelope.observation {
7575 ControlObservation::ProviderEvent { event, .. } => Some(event),
7576 _ => None,
7577 })
7578 .collect();
7579
7580 assert!(
7581 provider_events
7582 .iter()
7583 .any(|event| matches!(event, ProviderEvent::SessionStarted { .. })),
7584 "expected SessionStarted even when the agent reported no sessionId, got {provider_events:?}"
7585 );
7586 assert!(
7587 !provider_events
7588 .iter()
7589 .any(|event| matches!(event, ProviderEvent::SessionIdentityObserved { .. })),
7590 "an agent that violates ACP's sessionId MUST must not be granted an identity: \
7591 got {provider_events:?}"
7592 );
7593
7594 let _ = shell.stop_native(key, true).await;
7595 }
7596}
7597
7598#[cfg(test)]
7599mod resume_tests;