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