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