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 )
533 .await
534 }
535 ControlEffect::Stop { force } => self.stop_native(key, force).await,
536 ControlEffect::WriteInput {
537 input,
538 required_foreground,
539 } => match self.pty_sessions.get(&key) {
540 Some(owned) => match required_foreground {
541 ForegroundRequirement::Any
542 if matches!(
543 input.kind(),
544 PreparedInputKind::TerminalText
545 | PreparedInputKind::TerminalBytes
546 | PreparedInputKind::TerminalControl
547 ) =>
548 {
549 match owned.session.send_terminal_input(input).await {
550 Ok(()) => ControlObservation::InputCompleted,
551 Err(error) => ControlObservation::InputFailed {
552 message: error.to_string(),
553 },
554 }
555 }
556 ForegroundRequirement::Shell
557 if input.kind() == PreparedInputKind::ShellCommand =>
558 {
559 if !owned.runtime_policy.semantic_readiness {
560 ControlObservation::InputFailed {
561 message: "semantic shell input is not admitted by the provider runtime policy"
562 .to_owned(),
563 }
564 } else {
565 match owned.session.send_shell_input(input).await {
566 Ok(()) => ControlObservation::InputCompleted,
567 Err(error) => ControlObservation::InputFailed {
568 message: error.to_string(),
569 },
570 }
571 }
572 }
573 ForegroundRequirement::Agent { agent_id }
574 if matches!(
575 input.kind(),
576 PreparedInputKind::InsertDraft
577 | PreparedInputKind::SubmitPrompt
578 | PreparedInputKind::AgentCommand
579 ) && &agent_id == owned.session.agent_id() =>
580 {
581 if !owned.runtime_policy.semantic_readiness
582 || !owned.runtime_policy.structured_prompt
583 {
584 return completion_observation(
585 operation_id,
586 instance_id,
587 generation,
588 ControlObservation::InputFailed {
589 message: "semantic input is not admitted by the provider runtime policy"
590 .to_owned(),
591 },
592 );
593 }
594 let intent = match input.kind() {
595 PreparedInputKind::InsertDraft
596 | PreparedInputKind::AgentCommand => ReadinessIntent::DraftPaste,
597 PreparedInputKind::SubmitPrompt => ReadinessIntent::FollowupPrompt,
598 PreparedInputKind::ShellCommand
599 | PreparedInputKind::TerminalText
600 | PreparedInputKind::TerminalBytes
601 | PreparedInputKind::TerminalControl => unreachable!(),
602 };
603 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
604 return completion_observation(
605 operation_id,
606 instance_id,
607 generation,
608 ControlObservation::InputFailed {
609 message: "session agent disappeared from native catalog"
610 .to_owned(),
611 },
612 );
613 };
614 match wait_for_readiness(&owned.session, &spec, intent, false).await {
615 Ok(permit) => {
616 let result = if input.kind() == PreparedInputKind::AgentCommand
617 {
618 owned.session.send_agent_command_input(input, permit).await
619 } else {
620 owned.session.send_prepared_input(input, permit).await
621 };
622 match result {
623 Ok(()) => ControlObservation::InputCompleted,
624 Err(error) => ControlObservation::InputFailed {
625 message: error.to_string(),
626 },
627 }
628 }
629 Err(message) => ControlObservation::InputFailed { message },
630 }
631 }
632 required_foreground => ControlObservation::InputFailed {
633 message: format!(
634 "prepared input kind {:?} does not satisfy route {:?}",
635 input.kind(),
636 required_foreground
637 ),
638 },
639 },
640 None => ControlObservation::InputFailed {
641 message: "typed PTY input requires a PTY session".to_owned(),
642 },
643 },
644 ControlEffect::SubmitPrompt { prompt } => match self.acp_sessions.get(&key) {
645 Some(owned) if !owned.runtime_policy.structured_prompt => {
646 ControlObservation::InputFailed {
647 message: "structured prompt is not admitted by the provider runtime policy"
648 .to_owned(),
649 }
650 }
651 Some(owned) => match owned.session.start_prompt(&prompt).await {
652 Ok(()) => ControlObservation::InputCompleted,
653 Err(error) => ControlObservation::InputFailed {
654 message: error.to_string(),
655 },
656 },
657 None => ControlObservation::InputFailed {
658 message: "semantic follow-up prompts require an ACP session".to_owned(),
659 },
660 },
661 ControlEffect::Interrupt => match self.acp_sessions.get(&key) {
662 Some(owned) => match owned.session.cancel().await {
663 Ok(()) => ControlObservation::InputCompleted,
664 Err(error) => ControlObservation::InputFailed {
665 message: error.to_string(),
666 },
667 },
668 None => ControlObservation::InputFailed {
669 message: "semantic interrupt requires an ACP session".to_owned(),
670 },
671 },
672 ControlEffect::ResolveInteraction { target, response } => {
673 resolve_acp_interaction_observation(
674 self.acp_sessions.get(&key).map(|owned| &owned.session),
675 target,
676 response,
677 )
678 }
679 ControlEffect::SetSessionMode { mode_id } => {
680 set_acp_session_mode_observation(
681 self.acp_sessions.get(&key).map(|owned| &owned.session),
682 mode_id,
683 )
684 .await
685 }
686 ControlEffect::SetSessionConfigOption {
687 option_id,
688 value_json,
689 } => {
690 set_acp_session_config_option_observation(
691 self.acp_sessions.get(&key).map(|owned| &owned.session),
692 option_id,
693 value_json,
694 )
695 .await
696 }
697 ControlEffect::SetSessionModel { model_id } => {
698 set_acp_session_model_observation(
699 self.acp_sessions.get(&key).map(|owned| &owned.session),
700 model_id,
701 )
702 }
703 ControlEffect::Resize { size } if !size.is_valid() => {
704 ControlObservation::ResizeFailed {
705 message: "terminal size is outside the supported range".to_owned(),
706 }
707 }
708 ControlEffect::Resize { size } => match self.pty_sessions.get(&key) {
709 Some(owned) => match owned.session.resize(size.rows, size.columns).await {
710 Ok(()) => ControlObservation::ResizeCompleted { size },
711 Err(error) => ControlObservation::ResizeFailed {
712 message: error.to_string(),
713 },
714 },
715 None => ControlObservation::ResizeFailed {
716 message: "terminal resize requires a PTY session".to_owned(),
717 },
718 },
719 ControlEffect::ObserveForeground => match self.pty_sessions.get(&key) {
720 Some(owned) => match owned.session.observe_foreground().await {
721 Ok(observation) => ControlObservation::ForegroundObserved {
722 process: canonical_foreground(
723 owned.session.agent_id().clone(),
724 &observation,
725 ),
726 },
727 Err(error) => ControlObservation::ForegroundFailed {
728 message: error.to_string(),
729 },
730 },
731 None => ControlObservation::ForegroundFailed {
732 message: "foreground observation requires a PTY session".to_owned(),
733 },
734 },
735 ControlEffect::ProbeCapabilities { .. } => {
736 ControlObservation::CapabilityProbeFailed {
737 failure: CapabilityProbeFailure::ExecutorUnavailable,
738 }
739 }
740 ControlEffect::DiscoverHistory { .. } | ControlEffect::LoadHistory { .. } => {
741 ControlObservation::HistoryFailed {
742 message: "history effects require the dedicated native history authority"
743 .to_owned(),
744 }
745 }
746 ControlEffect::AuthorizeResume { .. } => ControlObservation::ResumeFailed {
747 message: "resume authorization requires the dedicated native authority"
748 .to_owned(),
749 },
750 }
751 };
752
753 completion_observation(operation_id, instance_id, generation, observation)
754 }
755
756 async fn spawn_native(
757 &mut self,
758 key: NativeSessionKey,
759 operation_id: OperationId,
760 spawn: NativeSpawnRequest,
761 pty_env: Vec<EnvMutation>,
762 mcp_server: Option<McpServerSpec>,
763 ) -> ControlObservation {
764 let NativeSpawnRequest {
765 agent_id,
766 transport,
767 request,
768 runtime_policy,
769 mut launch_extra_args,
770 instance_extra_args,
771 resumed_provider_session,
772 one_shot_session_persistence,
773 } = spawn;
774 if let Err(message) =
775 validate_instance_launch_arguments(&agent_id, transport, &instance_extra_args)
776 {
777 return ControlObservation::SpawnFailed { message };
778 }
779 if let Err(message) = validate_spawn_runtime_policy(
780 runtime_policy,
781 transport,
782 request.initial_prompt.is_some(),
783 resumed_provider_session.is_some(),
784 ) {
785 return ControlObservation::SpawnFailed { message };
786 }
787 if self.session_exists(key) {
788 return ControlObservation::SpawnFailed {
789 message: format!(
790 "native session {:?}/{:?} already exists",
791 key.instance_id, key.generation
792 ),
793 };
794 }
795 if !request.terminal_size.is_valid() {
796 return ControlObservation::SpawnFailed {
797 message: "terminal size is outside the supported range".to_owned(),
798 };
799 }
800 if request.working_directory.is_empty()
801 || request.working_directory.len() > WORKING_DIRECTORY_MAX_BYTES
802 || request.working_directory.contains('\0')
803 {
804 return ControlObservation::SpawnFailed {
805 message: "working directory is invalid".to_owned(),
806 };
807 }
808 let Some(spec) = self.catalog.get(&agent_id).cloned() else {
809 return ControlObservation::SpawnFailed {
810 message: format!("agent '{agent_id}' is absent from native catalog"),
811 };
812 };
813 let working_dir = PathBuf::from(&request.working_directory);
814
815 match transport {
816 TransportKind::Pty if !spec.capabilities.transports.pty => {
817 ControlObservation::SpawnFailed {
818 message: format!("agent '{agent_id}' does not support PTY transport"),
819 }
820 }
821 TransportKind::Pty => {
822 let pty_env = with_pty_terminal_capability_defaults(pty_env);
827 let fresh_provider_session = prepare_fresh_pty_provider_session(
828 spec.capabilities.transports.pty_adapter.as_ref(),
829 resumed_provider_session.is_some(),
830 runtime_policy.provider_session_identity,
831 &mut launch_extra_args,
832 );
833 launch_extra_args.extend(instance_extra_args);
834 let mut authoritative_provider_session = resumed_provider_session
835 .clone()
836 .or(fresh_provider_session);
837 let probe_kimi_identity = should_probe_pty_identity(
838 runtime_policy,
839 spec.capabilities.transports.pty_adapter.as_ref(),
840 authoritative_provider_session.is_some(),
841 "kimi",
842 );
843 let probe_codex_identity = should_probe_pty_identity(
844 runtime_policy,
845 spec.capabilities.transports.pty_adapter.as_ref(),
846 authoritative_provider_session.is_some(),
847 "codex",
848 );
849 tracing::info!(
862 agent_id = %agent_id,
863 instance_id = ?key.instance_id,
864 generation = ?key.generation,
865 terminal_size = ?request.terminal_size,
866 program = %spec.launch.program,
867 fixed_args = ?spec.launch.fixed_args,
868 extra_args = ?redact_provider_arguments(&launch_extra_args),
869 has_initial_prompt = request.initial_prompt.is_some(),
870 "spawning provider process over a PTY",
871 );
872 match PtySession::spawn_agent_with_size(
873 &spec,
874 LaunchRequest {
875 working_dir,
876 env: pty_env,
877 platform: RuntimePlatform::current(),
878 prompt: request.initial_prompt,
879 session_options: request.session_options,
880 extra_args: launch_extra_args,
881 remote: false,
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 env: acp_spec.env.clone(),
1277 ..AcpSessionOptions::default()
1278 };
1279 let spawned = match acp_spec.launch_override.as_ref() {
1280 Some(launch) => {
1281 AcpSession::spawn_with_launch(tool, &working_dir, acp_options, launch)
1282 .await
1283 }
1284 None => AcpSession::spawn(tool, &working_dir, acp_options).await,
1285 };
1286 match spawned {
1287 Ok(session) => {
1288 if let Some(mode_id) = acp_mode_id.as_ref() {
1289 if let Err(message) =
1290 apply_acp_approval_mode(&session, mode_id, request.approval_level)
1291 .await
1292 {
1293 let _ = session.kill().await;
1294 return ControlObservation::SpawnFailed { message };
1295 }
1296 }
1297 let process_id = session.process_id();
1298 let events = session.subscribe();
1299 let session_id = session
1300 .acp_session_id()
1301 .await
1302 .unwrap_or_else(|| session.session_id().to_owned());
1303 let identity_observed = if runtime_policy.provider_session_identity {
1333 match session.provider_reported_session_id().await {
1334 Some(id) => Some(ProviderEvent::SessionIdentityObserved {
1335 identity: ProviderSessionIdentity {
1336 key: ProviderSessionKey::SessionId,
1337 id,
1338 transcript_path: None,
1339 },
1340 }),
1341 None => {
1342 tracing::warn!(
1343 agent_id = %agent_id,
1344 adapter = %acp_spec.adapter.id,
1345 "ACP session/new returned no sessionId; provider \
1346 session identity stays IdentityPending",
1347 );
1348 None
1349 }
1350 }
1351 } else {
1352 None
1353 };
1354 if let Some(prompt) = request.initial_prompt {
1355 if let Err(error) = session.start_prompt(&prompt).await {
1356 let _ = session.kill().await;
1357 return ControlObservation::SpawnFailed {
1358 message: error.to_string(),
1359 };
1360 }
1361 }
1362 let announced_mode = session.current_mode_id();
1364 self.acp_sessions.insert(
1365 key,
1366 OwnedProviderSession {
1367 source,
1368 session,
1369 events,
1370 pending_events: {
1371 let mut seeded = VecDeque::from([AgentEvent::SessionStart {
1372 session_id,
1373 model: String::new(),
1374 tools: Vec::new(),
1375 }]);
1376 if let Some(mode_id) = announced_mode {
1399 seeded.push_back(AgentEvent::ModeChanged { mode_id });
1400 }
1401 seeded
1402 },
1403 pending_provider_events: VecDeque::from_iter(identity_observed),
1404 next_provider_sequence: 1,
1405 observed_exit_code: None,
1406 runtime_policy,
1407 },
1408 );
1409 ControlObservation::Spawned { process_id }
1410 }
1411 Err(error) => ControlObservation::SpawnFailed {
1412 message: error.to_string(),
1413 },
1414 }
1415 }
1416 }
1417 }
1418
1419 async fn spawn_resume(
1420 &mut self,
1421 key: NativeSessionKey,
1422 operation_id: OperationId,
1423 agent_id: AgentId,
1424 transport: TransportKind,
1425 provider_session: gate4agent_types::ProviderSessionIdentity,
1426 runtime_policy: ProviderRuntimePolicy,
1427 request: ResumeLaunchRequest,
1428 pty_env: Vec<EnvMutation>,
1429 instance_extra_args: Vec<OsString>,
1430 one_shot_session_persistence: OneShotSessionPersistence,
1431 ) -> ControlObservation {
1432 if let Err(message) = validate_spawn_runtime_policy(
1433 runtime_policy,
1434 transport,
1435 request.initial_prompt.is_some(),
1436 true,
1437 ) {
1438 return ControlObservation::SpawnFailed { message };
1439 }
1440 if let Err(error) = request.validate() {
1441 return ControlObservation::SpawnFailed {
1442 message: error.to_string(),
1443 };
1444 }
1445 let Some(spec) = self.catalog.get(&agent_id) else {
1446 return ControlObservation::SpawnFailed {
1447 message: format!("agent '{agent_id}' is absent from native catalog"),
1448 };
1449 };
1450 let Some(binding) = spec.capabilities.adapters.resume.as_ref() else {
1451 return ControlObservation::SpawnFailed {
1452 message: format!("agent '{agent_id}' does not declare Resume capability"),
1453 };
1454 };
1455 let plan = match build_resume_plan_for_identity(&binding.id, &provider_session) {
1456 Ok(Some(plan)) => plan,
1457 Ok(None) => {
1458 return ControlObservation::SpawnFailed {
1459 message: format!("agent '{agent_id}' has no live Resume plan"),
1460 }
1461 }
1462 Err(error) => {
1463 return ControlObservation::SpawnFailed {
1464 message: error.to_string(),
1465 }
1466 }
1467 };
1468 if transport == TransportKind::Pipe {
1469 let Some(pipe) = spec.capabilities.transports.pipe.as_ref() else {
1470 return ControlObservation::SpawnFailed {
1471 message: format!("agent '{agent_id}' does not support Pipe transport"),
1472 };
1473 };
1474 if pipe.protocol != PipeProtocol::StructuredJsonl {
1475 return ControlObservation::SpawnFailed {
1476 message: format!(
1477 "agent '{agent_id}' does not expose a resumable structured Pipe contract"
1478 ),
1479 };
1480 }
1481 }
1482 let start = StartRequest {
1483 working_directory: request.working_directory,
1484 terminal_size: request.terminal_size,
1485 initial_prompt: request.initial_prompt,
1486 session_options: None,
1492 approval_level: ApprovalLevel::default(),
1493 };
1494 self.spawn_native(
1495 key,
1496 operation_id,
1497 NativeSpawnRequest {
1498 agent_id,
1499 transport,
1500 request: start,
1501 runtime_policy,
1502 launch_extra_args: if transport == TransportKind::Pty {
1503 plan.args.into_iter().map(OsString::from).collect()
1504 } else {
1505 Vec::new()
1506 },
1507 instance_extra_args,
1508 resumed_provider_session: Some(provider_session),
1509 one_shot_session_persistence,
1510 },
1511 pty_env,
1512 None,
1513 )
1514 .await
1515 }
1516
1517 async fn stop_native(&mut self, key: NativeSessionKey, force: bool) -> ControlObservation {
1518 if let Some(owned) = self.pty_sessions.remove(&key) {
1519 let shutdown = owned.session.shutdown().await;
1520 return match shutdown {
1521 Ok(outcome) => ControlObservation::StopCompleted {
1522 forced: force || outcome.termination.is_some(),
1523 exit_code: outcome.exit_code,
1524 final_terminal: Some(terminal_frame(outcome.terminal, owned.last_screen_state.clone())),
1528 },
1529 Err(error) => {
1530 eprintln!(
1531 "[gate4agent-shell-native] PTY stop failed for {key:?} (force={force}): {error}",
1532 );
1533 ControlObservation::StopFailed {
1534 message: error.to_string(),
1535 }
1536 }
1537 };
1538 }
1539 if let Some(owned) = self.pipe_sessions.remove(&key) {
1540 return match owned.session.stop(force).await {
1553 Ok(outcome) => ControlObservation::StopCompleted {
1554 forced: outcome.forced,
1555 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1556 final_terminal: None,
1557 },
1558 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1559 forced: false,
1560 exit_code: owned.observed_exit_code,
1561 final_terminal: None,
1562 },
1563 Err(error) => ControlObservation::StopFailed {
1564 message: error.to_string(),
1565 },
1566 };
1567 }
1568 if let Some(mut owned) = self.one_shot_sessions.remove(&key) {
1569 return match owned.session.kill().await {
1570 Ok(()) => ControlObservation::StopCompleted {
1571 forced: true,
1572 exit_code: owned.observed_exit_code,
1573 final_terminal: None,
1574 },
1575 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1576 forced: false,
1577 exit_code: owned.observed_exit_code,
1578 final_terminal: None,
1579 },
1580 Err(error) => ControlObservation::StopFailed {
1581 message: error.to_string(),
1582 },
1583 };
1584 }
1585 if let Some(owned) = self.acp_sessions.remove(&key) {
1586 return match owned.session.stop(force).await {
1597 Ok(outcome) => ControlObservation::StopCompleted {
1598 forced: outcome.forced,
1599 exit_code: outcome.exit_code.or(owned.observed_exit_code),
1600 final_terminal: None,
1601 },
1602 Err(_) if owned.session.reader_finished() => ControlObservation::StopCompleted {
1603 forced: false,
1604 exit_code: owned.observed_exit_code,
1605 final_terminal: None,
1606 },
1607 Err(error) => ControlObservation::StopFailed {
1608 message: error.to_string(),
1609 },
1610 };
1611 }
1612 eprintln!("[gate4agent-shell-native] stop skipped: no session owns {key:?} in any transport map");
1618 ControlObservation::StopFailed {
1619 message: missing_session_message(key),
1620 }
1621 }
1622
1623 fn session_exists(&self, key: NativeSessionKey) -> bool {
1624 self.pty_sessions.contains_key(&key)
1625 || self.pipe_sessions.contains_key(&key)
1626 || self.one_shot_sessions.contains_key(&key)
1627 || self.acp_sessions.contains_key(&key)
1628 }
1629
1630 pub async fn collect_exits(&mut self) -> Vec<ObservationEnvelope> {
1633 let completed: Vec<_> = self
1634 .pty_sessions
1635 .iter()
1636 .filter_map(|(key, owned)| owned.session.reader_finished().then_some(*key))
1637 .collect();
1638 let mut observations = Vec::with_capacity(completed.len());
1639 for key in completed {
1640 let owned = self
1641 .pty_sessions
1642 .remove(&key)
1643 .expect("completed key came from the owned session map");
1644 let last_screen_state = owned.last_screen_state.clone();
1645 let (exit_code, final_terminal) = match owned.session.shutdown().await {
1646 Ok(outcome) => (
1647 outcome.exit_code,
1648 Some(terminal_frame(outcome.terminal, last_screen_state)),
1649 ),
1650 Err(_) => (None, None),
1651 };
1652 observations.push(ObservationEnvelope {
1653 operation_id: None,
1654 instance_id: key.instance_id,
1655 generation: key.generation,
1656 observation: ControlObservation::ProcessExited {
1657 exit_code,
1658 final_terminal,
1659 },
1660 });
1661 }
1662 collect_provider_exits(&mut self.pipe_sessions, &mut observations, |session| {
1663 session.reader_finished()
1664 });
1665 collect_provider_exits(&mut self.one_shot_sessions, &mut observations, |session| {
1666 session.reader_finished()
1667 });
1668 collect_provider_exits(&mut self.acp_sessions, &mut observations, |session| {
1669 session.reader_finished()
1670 });
1671 observations
1672 }
1673
1674 pub fn collect_provider_events(&mut self) -> Vec<ObservationEnvelope> {
1677 let mut observations = self.pending_observations.drain(..).collect::<Vec<_>>();
1678 for (key, owned) in &mut self.pty_sessions {
1679 if let Some(provider) = &mut owned.provider {
1680 drain_pty_provider(*key, provider, &mut observations);
1681 }
1682 }
1683 collect_provider_map(&mut self.pipe_sessions, &mut observations, |_| Vec::new());
1684 collect_provider_map(&mut self.one_shot_sessions, &mut observations, |_| Vec::new());
1685 for owned in self.acp_sessions.values() {
1697 owned.session.expire_deadlines();
1698 }
1699 collect_provider_map(&mut self.acp_sessions, &mut observations, AcpSession::available_modes);
1700 observations
1701 }
1702
1703 pub fn collect_terminal_frames(&mut self) -> Vec<ObservationEnvelope> {
1717 let mut observations = Vec::new();
1718 let pty_sessions = &mut self.pty_sessions;
1724 let efficiency_facts = &mut self.efficiency_facts;
1725 for (key, owned) in pty_sessions {
1726 if terminal_state_capture_should_skip(
1727 owned.session.terminal_sequence(),
1728 owned.last_terminal_sequence,
1729 ) {
1730 efficiency_facts.record_terminal_state_skip();
1731 continue;
1732 }
1733 let capture_start = Instant::now();
1734 let terminal_state = owned.session.terminal_state();
1735 efficiency_facts.record_terminal_state_capture(capture_start.elapsed());
1736 match terminal_state {
1737 Ok(snapshot) if snapshot.sequence > owned.last_terminal_sequence => {
1738 owned.last_terminal_sequence = snapshot.sequence;
1739 owned.terminal_stale_published = false;
1740
1741 owned.last_screen_gate = startup_operator_gate(&snapshot.contents);
1745 owned.last_screen_failure =
1756 screen_failure_for_generation(&snapshot.contents, owned.ever_reached_ready);
1757 let merged = classify_pty_screen_state(
1758 owned.last_foreground_verdict.as_ref(),
1759 owned.last_screen_gate.as_ref(),
1760 owned.last_screen_failure,
1761 );
1762 if !snapshot.contents.trim().is_empty() {
1773 owned.screen_had_content = true;
1774 }
1775 if merged == PtyScreenState::Ready && owned.screen_had_content {
1776 owned.ever_reached_ready = true;
1777 }
1778 if merged != owned.last_screen_state {
1779 if foreground_probe_rearms_immediately(&owned.last_screen_state, &merged) {
1780 owned.next_foreground_probe = Some(Instant::now());
1781 }
1782 owned.last_screen_state = merged.clone();
1783 observations.push(ObservationEnvelope {
1784 operation_id: None,
1785 instance_id: key.instance_id,
1786 generation: key.generation,
1787 observation: ControlObservation::ScreenState {
1788 state: merged.clone(),
1789 },
1790 });
1791 }
1792
1793 let frame = terminal_frame(snapshot, merged);
1794 efficiency_facts.record_terminal_frame_published(terminal_frame_byte_len(&frame));
1795 observations.push(ObservationEnvelope {
1796 operation_id: None,
1797 instance_id: key.instance_id,
1798 generation: key.generation,
1799 observation: ControlObservation::TerminalFrame { frame },
1800 });
1801 }
1802 Ok(_) => {}
1803 Err(error) if !owned.terminal_stale_published => {
1804 owned.terminal_stale_published = true;
1805 observations.push(ObservationEnvelope {
1806 operation_id: None,
1807 instance_id: key.instance_id,
1808 generation: key.generation,
1809 observation: ControlObservation::TerminalStale {
1810 message: error.to_string(),
1811 },
1812 });
1813 }
1814 Err(_) => {}
1815 }
1816 }
1817 observations
1818 }
1819
1820 pub async fn reclassify_foreground(&mut self) -> Vec<ObservationEnvelope> {
1838 let catalog = &self.catalog;
1839 let now = Instant::now();
1840 let due: Vec<NativeSessionKey> = self
1841 .pty_sessions
1842 .iter()
1843 .filter(|(_, owned)| owned.next_foreground_probe.is_some_and(|at| now >= at))
1844 .map(|(key, _)| *key)
1845 .collect();
1846
1847 let mut observations = Vec::new();
1848 for key in due {
1849 let Some(owned) = self.pty_sessions.get_mut(&key) else {
1850 continue;
1851 };
1852 let probe_result = owned.session.observe_foreground_timed().await;
1853 match probe_result {
1854 Ok((observation, timing)) => {
1855 self.efficiency_facts.record_foreground_probe(timing);
1868 let verdict = match catalog.get(&owned.agent_id) {
1869 Some(spec) => resolve_foreground_verdict(
1870 spec,
1871 &observation,
1872 RuntimePlatform::current(),
1873 ),
1874 None => ForegroundVerdict::Foreign {
1880 process: observation.observed_process.clone(),
1881 },
1882 };
1883 owned.last_foreground_verdict = Some(verdict);
1884 let merged = classify_pty_screen_state(
1885 owned.last_foreground_verdict.as_ref(),
1886 owned.last_screen_gate.as_ref(),
1887 owned.last_screen_failure,
1888 );
1889 if merged == PtyScreenState::Ready && owned.screen_had_content {
1894 owned.ever_reached_ready = true;
1895 }
1896 if merged != owned.last_screen_state {
1897 owned.last_screen_state = merged.clone();
1898 observations.push(ObservationEnvelope {
1899 operation_id: None,
1900 instance_id: key.instance_id,
1901 generation: key.generation,
1902 observation: ControlObservation::ScreenState { state: merged },
1903 });
1904 }
1905 owned.next_foreground_probe =
1906 match foreground_probe_schedule(&owned.last_screen_state) {
1907 ForegroundProbeSchedule::Disarmed => None,
1908 ForegroundProbeSchedule::Armed => {
1909 Some(now + FOREGROUND_RECLASSIFY_INTERVAL)
1910 }
1911 };
1912 }
1913 Err(_) => {
1914 owned.next_foreground_probe = Some(now + FOREGROUND_RECLASSIFY_INTERVAL);
1921 }
1922 }
1923 }
1924 observations
1925 }
1926}
1927
1928const PTY_TERM_DEFAULT_KEY: &str = "TERM";
1935const PTY_TERM_DEFAULT_VALUE: &str = "xterm-256color";
1936const PTY_COLORTERM_DEFAULT_KEY: &str = "COLORTERM";
1937const PTY_COLORTERM_DEFAULT_VALUE: &str = "truecolor";
1938
1939fn with_pty_terminal_capability_defaults(mut pty_env: Vec<EnvMutation>) -> Vec<EnvMutation> {
1945 let already_mutated = |env: &[EnvMutation], key: &str| {
1946 env.iter()
1947 .any(|mutation| mutation.key.as_os_str() == OsStr::new(key))
1948 };
1949 if !already_mutated(&pty_env, PTY_TERM_DEFAULT_KEY) {
1950 pty_env.push(EnvMutation {
1951 key: OsString::from(PTY_TERM_DEFAULT_KEY),
1952 value: Some(OsString::from(PTY_TERM_DEFAULT_VALUE)),
1953 });
1954 }
1955 if !already_mutated(&pty_env, PTY_COLORTERM_DEFAULT_KEY) {
1956 pty_env.push(EnvMutation {
1957 key: OsString::from(PTY_COLORTERM_DEFAULT_KEY),
1958 value: Some(OsString::from(PTY_COLORTERM_DEFAULT_VALUE)),
1959 });
1960 }
1961 pty_env
1962}
1963
1964fn missing_session_message(key: NativeSessionKey) -> String {
1965 format!(
1966 "native session {:?}/{:?} does not exist",
1967 key.instance_id, key.generation
1968 )
1969}
1970
1971fn host_policy_for_approval_level(level: ApprovalLevel) -> HostPolicy {
1996 match level {
1997 ApprovalLevel::FullAuto => HostPolicy::Yolo,
1998 ApprovalLevel::ReadOnly => HostPolicy::ReadOnly,
1999 ApprovalLevel::Moderate | ApprovalLevel::Unmanaged => HostPolicy::Auto,
2000 }
2001}
2002
2003fn defers_permission_requests(agent_id: &AgentId, level: ApprovalLevel) -> bool {
2034 match approval_level_resolution(agent_id, level) {
2035 ApprovalLevelResolution::Supported {
2036 asks_for_permission,
2037 ..
2038 } => asks_for_permission,
2039 ApprovalLevelResolution::Unsupported => true,
2040 }
2041}
2042
2043const ACP_MODE_CONFIRMATION_TIMEOUT: Duration = Duration::from_secs(5);
2053
2054fn required_acp_mode(agent_id: &AgentId, level: ApprovalLevel) -> Result<Option<ModeId>, String> {
2071 let (acp_mode_id, carries_argv_flags) = match approval_level_resolution(agent_id, level) {
2072 ApprovalLevelResolution::Unsupported => (None, false),
2073 ApprovalLevelResolution::Supported { acp_mode_id, args, .. } => {
2074 (acp_mode_id, !args.is_empty())
2075 }
2076 };
2077 match (acp_mode_id, level) {
2078 (Some(mode_id), _) => Ok(Some(mode_id)),
2079 (None, ApprovalLevel::Unmanaged) => Ok(None),
2080 (None, _) if carries_argv_flags => Ok(None),
2089 (None, _) => Err(format!(
2090 "agent '{agent_id}' has no verified ACP mode for {level:?} and the level carries no \
2091 vendor flags to apply through argv either; refusing rather than launching at the \
2092 vendor's own (wider-authority) default"
2093 )),
2094 }
2095}
2096
2097fn acp_approval_level_args(agent_id: &AgentId, level: ApprovalLevel) -> Vec<String> {
2114 match approval_level_resolution(agent_id, level) {
2115 ApprovalLevelResolution::Supported { args, acp_mode_id: None, .. } => args,
2116 ApprovalLevelResolution::Supported { acp_mode_id: Some(_), .. } => Vec::new(),
2117 ApprovalLevelResolution::Unsupported => Vec::new(),
2118 }
2119}
2120
2121#[derive(Debug)]
2129struct ApprovalLevelNotOfferedByAgent {
2130 level: ApprovalLevel,
2131 offered: Vec<String>,
2132}
2133
2134impl std::fmt::Display for ApprovalLevelNotOfferedByAgent {
2135 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2136 write!(
2137 formatter,
2138 "ApprovalLevelNotOfferedByAgent {{ level: {:?}, offered: {:?} }}",
2139 self.level, self.offered
2140 )
2141 }
2142}
2143
2144fn approval_level_not_offered_message(
2150 level: ApprovalLevel,
2151 mode_id: &ModeId,
2152 offered: &[SessionMode],
2153) -> Option<String> {
2154 if offered.iter().any(|mode| mode.id == mode_id.as_str()) {
2155 None
2156 } else {
2157 Some(
2158 ApprovalLevelNotOfferedByAgent {
2159 level,
2160 offered: offered.iter().map(|mode| mode.id.clone()).collect(),
2161 }
2162 .to_string(),
2163 )
2164 }
2165}
2166
2167async fn apply_acp_approval_mode(
2185 session: &AcpSession,
2186 mode_id: &ModeId,
2187 level: ApprovalLevel,
2188) -> Result<(), String> {
2189 if let Some(message) =
2190 approval_level_not_offered_message(level, mode_id, &session.available_modes())
2191 {
2192 return Err(message);
2193 }
2194
2195 let mut confirmation = session.subscribe();
2198 session
2199 .set_mode(mode_id.as_str())
2200 .await
2201 .map_err(|error| format!("session/set_mode to '{mode_id}' failed: {error}"))?;
2202
2203 let _ = tokio::time::timeout(ACP_MODE_CONFIRMATION_TIMEOUT, async {
2204 loop {
2205 match confirmation.recv().await {
2206 Ok(AgentEvent::ModeChanged { mode_id: changed }) if changed == mode_id.as_str() => {
2207 return;
2208 }
2209 Ok(_) => continue,
2210 Err(_) => return,
2211 }
2212 }
2213 })
2214 .await;
2215
2216 Ok(())
2217}
2218
2219fn validate_spawn_runtime_policy(
2220 policy: ProviderRuntimePolicy,
2221 transport: TransportKind,
2222 has_initial_prompt: bool,
2223 is_resume: bool,
2224) -> Result<(), String> {
2225 policy
2226 .validate()
2227 .map_err(|error| format!("provider runtime policy is invalid: {error}"))?;
2228 if transport != TransportKind::Acp {
2237 require_runtime_capability(policy, ProviderRuntimeCapability::RawPtyLifecycle)?;
2238 if transport != TransportKind::Pty {
2239 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2240 }
2241 if has_initial_prompt {
2242 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticReadiness)?;
2243 require_runtime_capability(policy, ProviderRuntimeCapability::StructuredPrompt)?;
2244 }
2245 if is_resume && has_initial_prompt {
2246 require_runtime_capability(policy, ProviderRuntimeCapability::ProviderSessionIdentity)?;
2247 require_runtime_capability(policy, ProviderRuntimeCapability::SemanticResume)?;
2248 }
2249 }
2250 Ok(())
2251}
2252
2253
2254fn is_codex_config_c_overlay_args(arguments: &[OsString]) -> bool {
2255 if arguments.is_empty() || arguments.len() % 2 != 0 {
2256 return false;
2257 }
2258 arguments.chunks_exact(2).all(|pair| {
2259 pair[0].as_os_str() == "-c"
2260 && pair[1]
2261 .to_str()
2262 .is_some_and(|value| !value.is_empty() && value.contains('=') && !value.contains('\0'))
2263 })
2264}
2265
2266fn validate_instance_launch_arguments(
2267 agent_id: &AgentId,
2268 transport: TransportKind,
2269 arguments: &[OsString],
2270) -> Result<(), String> {
2271 if arguments.is_empty() {
2272 return Ok(());
2273 }
2274 let acp_codex_c_overlay = transport == TransportKind::Acp
2275 && agent_id.as_str() == "codex"
2276 && is_codex_config_c_overlay_args(arguments);
2277 if transport != TransportKind::Pty && !acp_codex_c_overlay {
2278 return Err(
2279 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
2280 .to_owned(),
2281 );
2282 }
2283 if arguments.len() > INSTANCE_LAUNCH_ARGS_MAX {
2284 return Err("native instance launch argument count exceeds its bound".to_owned());
2285 }
2286 let mut total_bytes = 0usize;
2287 for argument in arguments {
2288 let argument = argument.to_string_lossy();
2289 if argument.contains('\0') {
2290 return Err("native instance launch argument is invalid".to_owned());
2291 }
2292 if argument.len() > INSTANCE_LAUNCH_ARG_MAX_BYTES {
2293 return Err("native instance launch argument exceeds its bound".to_owned());
2294 }
2295 total_bytes = total_bytes.saturating_add(argument.len());
2296 if total_bytes > INSTANCE_LAUNCH_ARGS_TOTAL_MAX_BYTES {
2297 return Err("native instance launch argument payload exceeds its bound".to_owned());
2298 }
2299 if agent_id.as_str() == "claude"
2300 && RESERVED_CLAUDE_LAUNCH_FLAGS.iter().any(|reserved| {
2301 argument == *reserved
2302 || (reserved.starts_with("--")
2303 && argument
2304 .strip_prefix(reserved)
2305 .is_some_and(|suffix| suffix.starts_with('=')))
2306 || (reserved.len() == 2
2307 && argument
2308 .strip_prefix(reserved)
2309 .is_some_and(|suffix| {
2310 !suffix.is_empty() && !suffix.starts_with('-')
2311 }))
2312 })
2313 {
2314 return Err(
2315 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
2316 .to_owned(),
2317 );
2318 }
2319 }
2320 Ok(())
2321}
2322
2323fn argument_looks_like_credential(value: &str) -> bool {
2336 const CREDENTIAL_PREFIXES: &[&str] = &["sk-", "sk_", "ghp_", "gho_", "ghs_", "xox", "bearer "];
2337 const CREDENTIAL_MARKERS: &[&str] = &[
2338 "apikey", "api_key", "api-key", "secret", "password", "passwd", "token=",
2339 ];
2340 let lower = value.to_ascii_lowercase();
2341 CREDENTIAL_PREFIXES
2342 .iter()
2343 .any(|prefix| lower.starts_with(prefix))
2344 || CREDENTIAL_MARKERS
2345 .iter()
2346 .any(|marker| lower.contains(marker))
2347 || has_prefixed_hex64_credential_shape(&lower)
2348}
2349
2350fn has_prefixed_hex64_credential_shape(lower: &str) -> bool {
2359 let Some((prefix, digest)) = lower.split_once('_') else {
2360 return false;
2361 };
2362 (2..=8).contains(&prefix.len())
2363 && prefix
2364 .bytes()
2365 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
2366 && digest.len() == 64
2367 && digest
2368 .bytes()
2369 .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
2370}
2371
2372fn redact_provider_argument(value: &OsStr) -> String {
2376 let text = value.to_string_lossy();
2377 if argument_looks_like_credential(&text) {
2378 "[redacted-credential-shaped-argument]".to_owned()
2379 } else {
2380 text.into_owned()
2381 }
2382}
2383
2384fn redact_provider_arguments(values: &[OsString]) -> Vec<String> {
2387 values.iter().map(|value| redact_provider_argument(value)).collect()
2388}
2389
2390fn require_runtime_capability(
2391 policy: ProviderRuntimePolicy,
2392 capability: ProviderRuntimeCapability,
2393) -> Result<(), String> {
2394 if policy.admits(capability) {
2395 Ok(())
2396 } else {
2397 Err(format!(
2398 "provider runtime capability {capability:?} is not admitted"
2399 ))
2400 }
2401}
2402
2403fn should_attach_pty_provider_stream(policy: ProviderRuntimePolicy) -> bool {
2404 policy.semantic_readiness || policy.provider_session_identity
2405}
2406
2407fn should_probe_pty_identity(
2408 policy: ProviderRuntimePolicy,
2409 adapter: Option<&gate4agent_types::AdapterBinding>,
2410 authoritative_identity_present: bool,
2411 expected_adapter: &str,
2412) -> bool {
2413 !authoritative_identity_present
2414 && policy.semantic_readiness
2415 && policy.structured_prompt
2416 && policy.provider_session_identity
2417 && adapter.is_some_and(|adapter| adapter.id.as_str() == expected_adapter)
2418}
2419
2420fn prepare_fresh_pty_provider_session(
2421 adapter: Option<&gate4agent_types::AdapterBinding>,
2422 is_resume: bool,
2423 identity_permitted: bool,
2424 launch_extra_args: &mut Vec<OsString>,
2425) -> Option<ProviderSessionIdentity> {
2426 let adapter = adapter?;
2427 if is_resume || !identity_permitted || adapter.id.as_str() != "claude-code" {
2428 return None;
2429 }
2430 let identity = ProviderSessionIdentity {
2431 key: ProviderSessionKey::SessionId,
2432 id: Uuid::new_v4().to_string(),
2433 transcript_path: None,
2434 };
2435 launch_extra_args.push(OsString::from("--session-id"));
2436 launch_extra_args.push(OsString::from(&identity.id));
2437 Some(identity)
2438}
2439
2440fn drain_pty_provider(
2441 key: NativeSessionKey,
2442 provider: &mut OwnedPtyProvider,
2443 observations: &mut Vec<ObservationEnvelope>,
2444) {
2445 while let Some(event) = provider.pending_events.pop_front() {
2446 push_provider_observation(key, provider, event, observations);
2447 }
2448
2449 loop {
2450 let envelope = match provider.replay.pop_front() {
2451 Some(envelope) => Some(envelope),
2452 None => provider.receiver.try_recv().unwrap_or_default(),
2453 };
2454 let Some(envelope) = envelope else {
2455 break;
2456 };
2457 match envelope.event {
2458 PtyEvent::Output(data) => {
2459 let raw = provider.utf8.push(&data);
2460 if raw.is_empty() {
2461 continue;
2462 }
2463 if provider.semantic_events {
2464 if let Some(info) = provider.rate_limits.detect(&raw) {
2465 push_provider_observation(
2466 key,
2467 provider,
2468 rate_limit_event(info),
2469 observations,
2470 );
2471 }
2472 }
2473 let identity = provider
2474 .kimi_identity
2475 .as_mut()
2476 .and_then(|extractor| extractor.push(&raw));
2477 if let Some(identity) = identity {
2478 if !provider.provider_session_started {
2479 push_provider_observation(
2480 key,
2481 provider,
2482 ProviderEvent::SessionStarted {
2483 session_id: identity.id.clone(),
2484 model: String::new(),
2485 tools: Vec::new(),
2486 },
2487 observations,
2488 );
2489 provider.provider_session_started = true;
2490 }
2491 push_provider_observation(
2492 key,
2493 provider,
2494 ProviderEvent::SessionIdentityObserved { identity },
2495 observations,
2496 );
2497 }
2498 if provider.semantic_events {
2499 let messages = provider
2500 .pipeline
2501 .get_mut()
2502 .unwrap_or_else(|poisoned| poisoned.into_inner())
2503 .process(&raw);
2504 for message in messages {
2505 if let Some(event) = parsed_provider_event(message) {
2506 push_provider_observation(key, provider, event, observations);
2507 }
2508 }
2509 }
2510 }
2511 PtyEvent::DataGap {
2512 from_sequence,
2513 to_sequence,
2514 ..
2515 } => {
2516 provider.utf8.clear();
2517 if let Some(extractor) = &mut provider.kimi_identity {
2518 extractor.reset_stream();
2519 }
2520 provider
2521 .pipeline
2522 .get_mut()
2523 .unwrap_or_else(|poisoned| poisoned.into_inner())
2524 .clear();
2525 let missed = to_sequence
2526 .checked_sub(from_sequence)
2527 .and_then(|difference| difference.checked_add(1));
2528 if let Some((source_sequence, missed)) = missed.and_then(|missed| {
2529 reserve_provider_gap_sequence(&mut provider.next_provider_sequence, missed)
2530 .map(|source_sequence| (source_sequence, missed))
2531 }) {
2532 observations.push(ObservationEnvelope {
2533 operation_id: None,
2534 instance_id: key.instance_id,
2535 generation: key.generation,
2536 observation: ControlObservation::ProviderGap {
2537 source: provider.source.clone(),
2538 source_sequence,
2539 missed,
2540 },
2541 });
2542 }
2543 }
2544 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
2545 push_provider_observation(
2546 key,
2547 provider,
2548 ProviderEvent::Error { message },
2549 observations,
2550 );
2551 }
2552 PtyEvent::Started
2553 | PtyEvent::Resized(_)
2554 | PtyEvent::ForegroundProcess(_)
2555 | PtyEvent::SnapshotAvailable { .. }
2556 | PtyEvent::Exited { .. } => {}
2557 }
2558 }
2559}
2560
2561fn push_provider_observation(
2562 key: NativeSessionKey,
2563 provider: &mut OwnedPtyProvider,
2564 event: ProviderEvent,
2565 observations: &mut Vec<ObservationEnvelope>,
2566) {
2567 let sequence = provider.next_provider_sequence;
2568 provider.next_provider_sequence = provider.next_provider_sequence.saturating_add(1);
2569 observations.push(ObservationEnvelope {
2570 operation_id: None,
2571 instance_id: key.instance_id,
2572 generation: key.generation,
2573 observation: ControlObservation::ProviderEvent {
2574 source: provider.source.clone(),
2575 sequence,
2576 event,
2577 },
2578 });
2579}
2580
2581fn reserve_provider_gap_sequence(next_sequence: &mut u64, missed: u64) -> Option<u64> {
2582 if missed == 0 {
2583 return None;
2584 }
2585 let Some(source_sequence) = missed
2586 .checked_sub(1)
2587 .and_then(|offset| next_sequence.checked_add(offset))
2588 else {
2589 *next_sequence = u64::MAX;
2590 return None;
2591 };
2592 let Some(next) = source_sequence.checked_add(1) else {
2593 *next_sequence = u64::MAX;
2594 return None;
2595 };
2596 *next_sequence = next;
2597 Some(source_sequence)
2598}
2599
2600fn parsed_provider_event(message: ParsedMessage) -> Option<ProviderEvent> {
2601 match message.class {
2602 MessageClass::AiResponse => Some(ProviderEvent::Text {
2603 text: message.content,
2604 is_delta: message.metadata.is_partial,
2605 }),
2606 MessageClass::ThinkingIndicator => Some(ProviderEvent::Thinking {
2607 text: message.content,
2608 }),
2609 MessageClass::Error => Some(ProviderEvent::Error {
2610 message: message.content,
2611 }),
2612 MessageClass::PromptReady => Some(ProviderEvent::Ready),
2613 MessageClass::ToolApproval => Some(ProviderEvent::InteractionRequested {
2614 request_id: None,
2615 interaction_kind: ProviderInteractionKind::Approval,
2616 tool_name: message
2617 .metadata
2618 .tool_name
2619 .unwrap_or_else(|| "unknown".to_owned()),
2620 title: None,
2624 prompt: message.content,
2625 options: Vec::new(),
2626 agent_id: None,
2627 }),
2628 MessageClass::InfoMessage
2629 | MessageClass::UiElement
2630 | MessageClass::UserEcho
2631 | MessageClass::Menu
2632 | MessageClass::Raw => None,
2633 }
2634}
2635
2636fn rate_limit_event(info: gate4agent::core::types::RateLimitInfo) -> ProviderEvent {
2637 ProviderEvent::RateLimited {
2638 limit_type: provider_rate_limit_kind(info.limit_type),
2639 resets_at: info.resets_at.map(|value| value.to_rfc3339()),
2640 usage_percent: info.usage_percent.map(|value| value.to_string()),
2641 raw_message: info.raw_message,
2642 }
2643}
2644
2645fn provider_host_request_decision(decision: HostRequestDecision) -> ProviderHostRequestDecision {
2652 match decision {
2653 HostRequestDecision::Granted { by } => {
2654 ProviderHostRequestDecision::Granted { by: provider_host_decision_authority(by) }
2655 }
2656 HostRequestDecision::Denied { by } => {
2657 ProviderHostRequestDecision::Denied { by: provider_host_decision_authority(by) }
2658 }
2659 HostRequestDecision::Deferred => ProviderHostRequestDecision::Deferred,
2660 }
2661}
2662
2663fn provider_host_decision_authority(by: HostDecisionAuthority) -> ProviderHostDecisionAuthority {
2664 match by {
2665 HostDecisionAuthority::Gate => ProviderHostDecisionAuthority::Gate,
2666 HostDecisionAuthority::Policy => ProviderHostDecisionAuthority::Policy,
2667 HostDecisionAuthority::Operator => ProviderHostDecisionAuthority::Operator,
2668 HostDecisionAuthority::DeadlinePolicy => ProviderHostDecisionAuthority::DeadlinePolicy,
2669 }
2670}
2671
2672fn provider_host_request_outcome(outcome: HostRequestOutcome) -> ProviderHostRequestOutcome {
2680 match outcome {
2681 HostRequestOutcome::Executed => ProviderHostRequestOutcome::Executed,
2682 HostRequestOutcome::Failed { error } => ProviderHostRequestOutcome::Failed { error },
2683 }
2684}
2685
2686fn provider_rate_limit_kind(
2690 limit_type: gate4agent::core::types::RateLimitType,
2691) -> ProviderRateLimitKind {
2692 use gate4agent::core::types::RateLimitType;
2693 match limit_type {
2694 RateLimitType::Session => ProviderRateLimitKind::Session,
2695 RateLimitType::Daily => ProviderRateLimitKind::Daily,
2696 RateLimitType::Weekly => ProviderRateLimitKind::Weekly,
2697 RateLimitType::Unknown => ProviderRateLimitKind::Unknown,
2698 }
2699}
2700
2701fn collect_provider_map<S>(
2707 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2708 observations: &mut Vec<ObservationEnvelope>,
2709 mode_catalogue: impl Fn(&S) -> Vec<SessionMode>,
2710) {
2711 for (key, owned) in sessions {
2712 let available_modes = mode_catalogue(&owned.session);
2713 drain_provider_stream(
2714 *key,
2715 &owned.source,
2716 &mut owned.events,
2717 &mut owned.pending_events,
2718 &mut owned.pending_provider_events,
2719 &mut owned.next_provider_sequence,
2720 Some(&mut owned.observed_exit_code),
2721 observations,
2722 &available_modes,
2723 );
2724 }
2725}
2726
2727fn push_sequenced_provider_event(
2734 key: NativeSessionKey,
2735 source: &ProviderSource,
2736 next_provider_sequence: &mut u64,
2737 observations: &mut Vec<ObservationEnvelope>,
2738 event: ProviderEvent,
2739) {
2740 let sequence = *next_provider_sequence;
2741 *next_provider_sequence = next_provider_sequence.saturating_add(1);
2742 observations.push(ObservationEnvelope {
2743 operation_id: None,
2744 instance_id: key.instance_id,
2745 generation: key.generation,
2746 observation: ControlObservation::ProviderEvent {
2747 source: source.clone(),
2748 sequence,
2749 event,
2750 },
2751 });
2752}
2753
2754fn drain_provider_stream(
2755 key: NativeSessionKey,
2756 source: &ProviderSource,
2757 events: &mut broadcast::Receiver<AgentEvent>,
2758 pending_events: &mut VecDeque<AgentEvent>,
2759 pending_provider_events: &mut VecDeque<ProviderEvent>,
2760 next_provider_sequence: &mut u64,
2761 mut observed_exit_code: Option<&mut Option<i32>>,
2762 observations: &mut Vec<ObservationEnvelope>,
2763 available_modes: &[SessionMode],
2764) {
2765 loop {
2766 if let Some(event) = pending_events.pop_front() {
2776 match event {
2777 AgentEvent::Exited { code } => {
2778 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2779 *exit_code = Some(code);
2780 }
2781 }
2782 event => {
2783 if let Some(event) = provider_event(event, available_modes) {
2784 push_sequenced_provider_event(
2785 key,
2786 source,
2787 next_provider_sequence,
2788 observations,
2789 event,
2790 );
2791 }
2792 }
2793 }
2794 continue;
2795 }
2796 if let Some(event) = pending_provider_events.pop_front() {
2797 push_sequenced_provider_event(key, source, next_provider_sequence, observations, event);
2798 continue;
2799 }
2800 match events.try_recv() {
2801 Ok(AgentEvent::Exited { code }) => {
2802 if let Some(exit_code) = observed_exit_code.as_deref_mut() {
2803 *exit_code = Some(code);
2804 }
2805 }
2806 Ok(event) => {
2807 if let Some(event) = provider_event(event, available_modes) {
2808 push_sequenced_provider_event(
2809 key,
2810 source,
2811 next_provider_sequence,
2812 observations,
2813 event,
2814 );
2815 }
2816 }
2817 Err(broadcast::error::TryRecvError::Lagged(missed)) => {
2818 if let Some(source_sequence) =
2819 reserve_provider_gap_sequence(next_provider_sequence, missed)
2820 {
2821 observations.push(ObservationEnvelope {
2822 operation_id: None,
2823 instance_id: key.instance_id,
2824 generation: key.generation,
2825 observation: ControlObservation::ProviderGap {
2826 source: source.clone(),
2827 source_sequence,
2828 missed,
2829 },
2830 });
2831 }
2832 }
2833 Err(broadcast::error::TryRecvError::Empty | broadcast::error::TryRecvError::Closed) => {
2834 break
2835 }
2836 }
2837 }
2838}
2839
2840fn collect_provider_exits<S>(
2841 sessions: &mut BTreeMap<NativeSessionKey, OwnedProviderSession<S>>,
2842 observations: &mut Vec<ObservationEnvelope>,
2843 finished: impl Fn(&S) -> bool,
2844) {
2845 let completed: Vec<_> = sessions
2846 .iter()
2847 .filter_map(|(key, owned)| {
2848 (owned.observed_exit_code.is_some() || finished(&owned.session)).then_some(*key)
2849 })
2850 .collect();
2851 for key in completed {
2852 let owned = sessions
2853 .remove(&key)
2854 .expect("completed provider key came from the owned session map");
2855 observations.push(ObservationEnvelope {
2856 operation_id: None,
2857 instance_id: key.instance_id,
2858 generation: key.generation,
2859 observation: ControlObservation::ProcessExited {
2860 exit_code: owned.observed_exit_code,
2861 final_terminal: None,
2862 },
2863 });
2864 }
2865}
2866
2867const RPC_REQUEST_ID_NUMBER_PREFIX: &str = "number:";
2873const RPC_REQUEST_ID_STRING_PREFIX: &str = "string:";
2874
2875fn encode_rpc_request_id(id: &RpcId) -> String {
2887 match id {
2888 RpcId::Number(number) => format!("{RPC_REQUEST_ID_NUMBER_PREFIX}{number}"),
2889 RpcId::String(value) => format!("{RPC_REQUEST_ID_STRING_PREFIX}{value}"),
2890 }
2891}
2892
2893fn decode_rpc_request_id(raw: &str) -> Option<RpcId> {
2898 if let Some(number) = raw.strip_prefix(RPC_REQUEST_ID_NUMBER_PREFIX) {
2899 return number.parse::<u64>().ok().map(RpcId::Number);
2900 }
2901 raw.strip_prefix(RPC_REQUEST_ID_STRING_PREFIX)
2902 .map(|value| RpcId::String(value.to_owned()))
2903}
2904
2905fn resolve_acp_interaction_observation(
2918 session: Option<&AcpSession>,
2919 target: ProviderInteractionTarget,
2920 response: ProviderInteractionResponse,
2921) -> ControlObservation {
2922 let interaction_id = target.interaction_id;
2923 let fail = |message: String| ControlObservation::InteractionResolutionFailed {
2924 interaction_id,
2925 message,
2926 };
2927 let Some(session) = session else {
2928 return fail("semantic interaction resolution requires an ACP session".to_owned());
2929 };
2930 let Some(provider_request_id) = target.provider_request_id.as_deref() else {
2931 return fail("ACP interaction resolution requires a provider request id".to_owned());
2932 };
2933 let Some(id) = decode_rpc_request_id(provider_request_id) else {
2934 return fail(format!(
2935 "ACP interaction resolution request id {provider_request_id:?} is not a valid JSON-RPC id"
2936 ));
2937 };
2938 match resolve_acp_permission_interaction(session, &id, response) {
2939 Ok(()) => ControlObservation::InteractionResolutionCompleted { interaction_id },
2940 Err(message) => fail(message),
2941 }
2942}
2943
2944fn resolve_acp_permission_interaction(
2968 session: &AcpSession,
2969 id: &RpcId,
2970 response: ProviderInteractionResponse,
2971) -> Result<(), String> {
2972 let choice = match response {
2973 ProviderInteractionResponse::ApproveOnce => OperatorPermissionChoice::Approve,
2974 ProviderInteractionResponse::Deny => OperatorPermissionChoice::Reject,
2975 ProviderInteractionResponse::Answer { .. } => {
2976 return Err("ACP permission interactions do not accept free-text answers".to_owned())
2977 }
2978 };
2979 session.resolve_pending_request_as(id, choice).map_err(|error| error.to_string())
2980}
2981
2982async fn set_acp_session_mode_observation(
2995 session: Option<&AcpSession>,
2996 mode_id: String,
2997) -> ControlObservation {
2998 let Some(session) = session else {
2999 return ControlObservation::SessionModeSetFailed {
3000 message: "session mode switch requires an ACP session".to_owned(),
3001 };
3002 };
3003 let catalogue = session.available_modes();
3004 if catalogue.is_empty() {
3005 return ControlObservation::SessionModeSetFailed {
3006 message: "the provider announces no session-mode capability".to_owned(),
3007 };
3008 }
3009 if !catalogue.iter().any(|mode| mode.id == mode_id) {
3010 return ControlObservation::SessionModeSetFailed {
3011 message: format!("the provider never offered mode {mode_id:?}"),
3012 };
3013 }
3014 match session.set_mode(&mode_id).await {
3015 Ok(()) => ControlObservation::SessionModeSet { mode_id },
3016 Err(error) => ControlObservation::SessionModeSetFailed {
3017 message: error.to_string(),
3018 },
3019 }
3020}
3021
3022async fn set_acp_session_config_option_observation(
3038 session: Option<&AcpSession>,
3039 option_id: String,
3040 value_json: String,
3041) -> ControlObservation {
3042 let Some(session) = session else {
3043 return ControlObservation::SessionConfigOptionSetFailed {
3044 message: "session config-option switch requires an ACP session".to_owned(),
3045 };
3046 };
3047 let catalogue = session.config_options();
3048 if catalogue.is_empty() {
3049 return ControlObservation::SessionConfigOptionSetFailed {
3050 message: "the provider announces no session config-option capability".to_owned(),
3051 };
3052 }
3053 if !catalogue.iter().any(|option| option.id == option_id) {
3054 return ControlObservation::SessionConfigOptionSetFailed {
3055 message: format!("the provider never offered config option {option_id:?}"),
3056 };
3057 }
3058 let value = match value_json.parse() {
3059 Ok(value) => value,
3060 Err(error) => {
3061 return ControlObservation::SessionConfigOptionSetFailed {
3062 message: format!("session config option value is not valid JSON: {error}"),
3063 }
3064 }
3065 };
3066 match session.set_config_option(&option_id, value).await {
3067 Ok(()) => ControlObservation::SessionConfigOptionSet { option_id },
3068 Err(error) => ControlObservation::SessionConfigOptionSetFailed {
3069 message: error.to_string(),
3070 },
3071 }
3072}
3073
3074fn set_acp_session_model_observation(
3083 session: Option<&AcpSession>,
3084 model_id: String,
3085) -> ControlObservation {
3086 if session.is_none() {
3087 return ControlObservation::SessionModelSetFailed {
3088 message: "session model switch requires an ACP session".to_owned(),
3089 };
3090 }
3091 ControlObservation::SessionModelSetFailed {
3092 message: format!(
3093 "this provider offers no host-invocable model-switch method (requested model {model_id:?})"
3094 ),
3095 }
3096}
3097
3098fn map_provider_stop_reason(reason: StopReason) -> ProviderStopReason {
3111 match reason {
3112 StopReason::EndTurn => ProviderStopReason::EndTurn,
3113 StopReason::MaxTokens => ProviderStopReason::MaxTokens,
3114 StopReason::MaxTurnRequests => ProviderStopReason::MaxTurnRequests,
3115 StopReason::Refusal => ProviderStopReason::Refusal,
3116 StopReason::Cancelled => ProviderStopReason::Cancelled,
3117 StopReason::Other(value) => ProviderStopReason::Other { value },
3118 StopReason::ProviderError { code, message, vendor_code } => {
3119 ProviderStopReason::ProviderError { code, message, vendor_code }
3120 }
3121 }
3122}
3123
3124fn provider_event(event: AgentEvent, available_modes: &[SessionMode]) -> Option<ProviderEvent> {
3125 match event {
3126 AgentEvent::SessionStart {
3127 session_id,
3128 model,
3129 tools,
3130 } => Some(ProviderEvent::SessionStarted {
3131 session_id,
3132 model,
3133 tools,
3134 }),
3135 AgentEvent::Text { text, is_delta } => Some(ProviderEvent::Text { text, is_delta }),
3136 AgentEvent::Thinking { text } => Some(ProviderEvent::Thinking { text }),
3137 AgentEvent::ToolStart { id, name, input } => Some(ProviderEvent::ToolStarted {
3138 id,
3139 name,
3140 input_json: input.to_string(),
3141 agent_id: None,
3142 }),
3143 AgentEvent::ToolResult {
3144 id,
3145 output,
3146 is_error,
3147 duration_ms,
3148 non_execution_kind,
3149 } => Some(ProviderEvent::ToolCompleted {
3150 id,
3151 output,
3152 is_error,
3153 duration_ms,
3154 agent_id: None,
3155 non_execution_kind,
3156 }),
3157 AgentEvent::TurnComplete {
3158 input_tokens,
3159 output_tokens,
3160 cache_read_tokens,
3161 cache_write_tokens,
3162 reasoning_tokens,
3163 context_window,
3164 is_cumulative,
3165 } => Some(ProviderEvent::TurnCompleted {
3166 usage: TokenUsage {
3167 input_tokens,
3168 output_tokens,
3169 cache_read_tokens,
3170 cache_write_tokens,
3171 reasoning_tokens,
3172 context_window,
3173 },
3174 is_cumulative,
3175 }),
3176 AgentEvent::ContextWindowUsage { usage } => {
3177 Some(ProviderEvent::ContextWindowUsage {
3178 usage: ProviderContextWindowUsage {
3179 uncached_input_tokens: usage.uncached_input_tokens,
3180 cache_read_tokens: usage.cache_read_tokens,
3181 cache_write_tokens: usage.cache_write_tokens,
3182 output_tokens: usage.output_tokens,
3183 unattributed_tokens: usage.unattributed_tokens,
3184 used_tokens: usage.used_tokens,
3185 capacity_tokens: usage.capacity_tokens,
3186 },
3187 })
3188 }
3189 AgentEvent::SessionEnd {
3190 result,
3191 cost_usd,
3192 is_error,
3193 stop_reason,
3194 } => Some(ProviderEvent::SessionEnded {
3195 result,
3196 cost_usd: cost_usd.map(|cost| cost.to_string()),
3197 is_error,
3198 stop_reason: stop_reason.map(map_provider_stop_reason),
3199 }),
3200 AgentEvent::Error { message } => Some(ProviderEvent::Error { message }),
3201 AgentEvent::TurnInterrupted { reason } => {
3211 tracing::warn!(reason = %reason, "acp turn interrupted");
3212 Some(ProviderEvent::TurnInterrupted)
3213 }
3214 AgentEvent::PtyParsed(message) => parsed_provider_event(message),
3215 AgentEvent::PtyReady => Some(ProviderEvent::Ready),
3216 AgentEvent::PtyToolApproval {
3217 tool_name,
3218 description,
3219 } => Some(ProviderEvent::InteractionRequested {
3220 request_id: None,
3221 interaction_kind: ProviderInteractionKind::Approval,
3222 tool_name,
3223 title: None,
3227 prompt: description.unwrap_or_default(),
3228 options: Vec::new(),
3229 agent_id: None,
3230 }),
3231 AgentEvent::RateLimit(info) => Some(rate_limit_event(info)),
3232 AgentEvent::RpcIncomingRequest {
3246 id,
3247 method,
3248 params,
3249 decision,
3250 reason: _,
3254 outcome: _,
3258 } if method == "session/request_permission"
3259 && matches!(decision, HostRequestDecision::Deferred) =>
3260 {
3261 let tool_call = params.as_ref().and_then(|params| params.get("toolCall"));
3262 let field = |name: &str| {
3263 tool_call
3264 .and_then(|tool_call| tool_call.get(name))
3265 .and_then(|value| value.as_str())
3266 .filter(|value| !value.is_empty())
3267 .map(str::to_owned)
3268 };
3269 let title = field("title");
3278 let options: Vec<ProviderInteractionOption> = params
3290 .as_ref()
3291 .and_then(|params| params.get("options"))
3292 .and_then(|options| options.as_array())
3293 .map(|options| {
3294 options
3295 .iter()
3296 .filter_map(|option| {
3297 let option_id = option.get("optionId")?.as_str()?.to_owned();
3298 let name = option.get("name")?.as_str()?.to_owned();
3299 let kind = option.get("kind")?.as_str()?.to_owned();
3300 Some(ProviderInteractionOption { option_id, name, kind })
3301 })
3302 .collect()
3303 })
3304 .unwrap_or_default();
3305 Some(ProviderEvent::InteractionRequested {
3306 request_id: Some(encode_rpc_request_id(&id)),
3307 interaction_kind: ProviderInteractionKind::Approval,
3308 tool_name: field("kind").unwrap_or(method),
3309 title,
3310 prompt: field("title").unwrap_or_default(),
3311 options,
3312 agent_id: None,
3313 })
3314 }
3315 AgentEvent::RpcIncomingRequest {
3316 id: _,
3317 method,
3318 params,
3319 decision,
3320 outcome,
3329 reason,
3330 } => Some(ProviderEvent::HostRequestObserved {
3331 method,
3332 params_json: params.map(|value| value.to_string()).unwrap_or_default(),
3333 decision: provider_host_request_decision(decision),
3334 outcome: provider_host_request_outcome(outcome),
3335 reason,
3336 }),
3337 AgentEvent::RpcNotification { method, params } => {
3338 Some(ProviderEvent::UnrecognizedNotification {
3339 method,
3340 payload_json: params.to_string(),
3341 })
3342 }
3343 AgentEvent::Started { .. } | AgentEvent::Exited { .. } | AgentEvent::PtyRaw { .. } => None,
3344 AgentEvent::UserMessage { text, is_delta } => {
3345 Some(ProviderEvent::UserMessage { text, is_delta })
3346 }
3347 AgentEvent::Plan { steps } => Some(ProviderEvent::Plan {
3348 steps: steps.into_iter().map(provider_plan_step).collect(),
3349 }),
3350 AgentEvent::AvailableCommandsUpdate { commands } => {
3351 Some(ProviderEvent::AvailableCommandsUpdated {
3352 commands: commands
3353 .into_iter()
3354 .map(|command| ProviderAvailableCommand {
3355 name: command.name,
3356 description: command.description,
3357 input_hint: command.input_hint,
3358 })
3359 .collect(),
3360 })
3361 }
3362 AgentEvent::ModeChanged { mode_id } => Some(ProviderEvent::ModeChanged {
3363 mode_id,
3364 available: available_modes.iter().cloned().map(provider_mode_info).collect(),
3365 }),
3366 AgentEvent::SessionInfoUpdate { title } => {
3367 Some(ProviderEvent::SessionInfoUpdated { title })
3368 }
3369 AgentEvent::UsageUpdate {
3370 used_tokens,
3371 context_window,
3372 cost_amount,
3373 cost_currency,
3374 } => Some(ProviderEvent::UsageUpdated {
3375 used_tokens,
3376 context_window,
3377 cost_amount: cost_amount.map(|amount| amount.to_string()),
3378 cost_currency,
3379 }),
3380 AgentEvent::ConfigOptionsUpdate { options } => Some(ProviderEvent::ConfigOptionsUpdated {
3381 options: options.into_iter().map(provider_config_option).collect(),
3382 }),
3383 AgentEvent::ModelsUpdate { .. }
3390 | AgentEvent::ProviderModelChanged { .. }
3391 | AgentEvent::SettingsUpdate { .. }
3392 | AgentEvent::HookExecutionUpdate { .. }
3393 | AgentEvent::McpServersUpdate { .. }
3394 | AgentEvent::McpInitProgress { .. }
3395 | AgentEvent::McpInitialized { .. }
3396 | AgentEvent::AnnouncementsUpdate { .. } => None,
3397 }
3398}
3399
3400fn provider_plan_priority(priority: gate4agent::core::types::PlanStepPriority) -> ProviderPlanPriority {
3404 use gate4agent::core::types::PlanStepPriority;
3405 match priority {
3406 PlanStepPriority::High => ProviderPlanPriority::High,
3407 PlanStepPriority::Medium => ProviderPlanPriority::Medium,
3408 PlanStepPriority::Low => ProviderPlanPriority::Low,
3409 }
3410}
3411
3412fn provider_plan_status(status: gate4agent::core::types::PlanStepStatus) -> ProviderPlanStatus {
3414 use gate4agent::core::types::PlanStepStatus;
3415 match status {
3416 PlanStepStatus::Pending => ProviderPlanStatus::Pending,
3417 PlanStepStatus::InProgress => ProviderPlanStatus::InProgress,
3418 PlanStepStatus::Completed => ProviderPlanStatus::Completed,
3419 }
3420}
3421
3422fn provider_plan_step(step: gate4agent::core::types::PlanStep) -> ProviderPlanStep {
3423 ProviderPlanStep {
3424 content: step.content,
3425 priority: provider_plan_priority(step.priority),
3426 status: provider_plan_status(step.status),
3427 }
3428}
3429
3430fn provider_mode_info(mode: SessionMode) -> ProviderModeInfo {
3434 ProviderModeInfo {
3435 id: mode.id,
3436 name: mode.name,
3437 description: mode.description,
3438 }
3439}
3440
3441fn provider_config_option_kind(
3444 kind: gate4agent::core::types::ConfigOptionKind,
3445) -> ProviderConfigOptionKind {
3446 use gate4agent::core::types::ConfigOptionKind;
3447 match kind {
3448 ConfigOptionKind::Select => ProviderConfigOptionKind::Select,
3449 ConfigOptionKind::Boolean => ProviderConfigOptionKind::Boolean,
3450 ConfigOptionKind::Unknown => ProviderConfigOptionKind::Unknown,
3451 }
3452}
3453
3454fn provider_config_option(option: gate4agent::core::types::ConfigOptionInfo) -> ProviderConfigOption {
3460 ProviderConfigOption {
3461 id: option.id,
3462 name: option.name,
3463 description: option.description,
3464 category: option.category,
3465 kind: provider_config_option_kind(option.kind),
3466 value_json: option.value.to_string(),
3467 choices: option
3468 .choices
3469 .into_iter()
3470 .map(|choice| ProviderConfigChoice {
3471 value_json: choice.value.to_string(),
3472 label: choice.label,
3473 })
3474 .collect(),
3475 }
3476}
3477
3478fn builtin_legacy_adapter_runtimes() -> AdapterRuntimeRegistry<CliTool> {
3479 let definitions = [
3485 ("claude-code", CliTool::ClaudeCode),
3486 ("codex", CliTool::Codex),
3487 ("kimi", CliTool::KimiCode),
3488 ("grok", CliTool::Grok),
3489 ];
3490 let mut runtimes = AdapterRuntimeRegistry::default();
3491 for (id, tool) in definitions {
3492 for family in [
3493 AdapterFamily::PtySemantic,
3494 AdapterFamily::Pipe,
3495 AdapterFamily::Acp,
3496 ] {
3497 let Some(binding) = builtin_adapter_registry().binding(family, id) else {
3498 continue;
3499 };
3500 runtimes
3501 .insert(family, binding.clone(), tool)
3502 .expect("built-in native adapter runtime must be unique");
3503 }
3504 }
3505 if let Some(binding) = builtin_adapter_registry().binding(AdapterFamily::Acp, "registry-acp") {
3506 runtimes
3507 .insert(AdapterFamily::Acp, binding.clone(), CliTool::External)
3508 .expect("registry-acp runtime must be unique");
3509 }
3510
3511 runtimes
3512}
3513
3514fn terminal_frame(snapshot: PtyTerminalSnapshot, screen_state: PtyScreenState) -> TerminalFrame {
3515 TerminalFrame {
3516 sequence: snapshot.sequence,
3517 size: TerminalSize {
3518 rows: snapshot.size.rows,
3519 columns: snapshot.size.cols,
3520 },
3521 cursor_row: snapshot.cursor.0,
3522 cursor_column: snapshot.cursor.1,
3523 contents: snapshot.contents,
3524 formatted: snapshot.formatted,
3525 scrollback_formatted: snapshot.scrollback_formatted,
3526 alternate_screen: snapshot.alternate_screen,
3527 mouse_protocol_enabled: snapshot.mouse_protocol_enabled,
3528 mouse_protocol_encoding: match snapshot.mouse_protocol_encoding {
3529 PtyMouseProtocolEncoding::Default => TerminalMouseProtocolEncoding::Default,
3530 PtyMouseProtocolEncoding::Utf8 => TerminalMouseProtocolEncoding::Utf8,
3531 PtyMouseProtocolEncoding::Sgr => TerminalMouseProtocolEncoding::Sgr,
3532 },
3533 produced_at_unix_ms: snapshot.produced_at_unix_ms,
3536 screen_state,
3537 bracketed_paste: Some(snapshot.bracketed_paste),
3542 }
3543}
3544
3545fn terminal_state_capture_should_skip<E>(sequence: Result<u64, E>, last_captured: u64) -> bool {
3553 matches!(sequence, Ok(sequence) if sequence <= last_captured)
3554}
3555
3556fn terminal_frame_byte_len(frame: &TerminalFrame) -> u64 {
3562 let scrollback_bytes: usize = frame.scrollback_formatted.iter().map(Vec::len).sum();
3563 (frame.formatted.len() + scrollback_bytes) as u64
3564}
3565
3566fn canonical_foreground(
3567 agent_id: AgentId,
3568 observation: &PtyForegroundObservation,
3569) -> ForegroundProcess {
3570 let kind = if observation.readiness.process_name.as_deref() == Some(agent_id.as_str()) {
3571 ForegroundProcessKind::Agent { agent_id }
3572 } else if observation.readiness.is_shell {
3573 ForegroundProcessKind::Shell
3574 } else {
3575 ForegroundProcessKind::Other
3576 };
3577 ForegroundProcess {
3578 root_process_id: observation.root_pid,
3579 process_id: observation.observed_pid,
3580 process_name: observation.observed_process.clone(),
3581 kind,
3582 }
3583}
3584
3585fn completion_observation(
3586 operation_id: OperationId,
3587 instance_id: AgentInstanceId,
3588 generation: SessionGeneration,
3589 observation: ControlObservation,
3590) -> ObservationEnvelope {
3591 ObservationEnvelope {
3592 operation_id: Some(operation_id),
3593 instance_id,
3594 generation,
3595 observation,
3596 }
3597}
3598
3599async fn wait_for_readiness(
3600 session: &PtySession,
3601 spec: &AgentSpec,
3602 intent: ReadinessIntent,
3603 detect_startup_gates: bool,
3604) -> Result<ReadinessPermit, String> {
3605 let started = Instant::now();
3606 let (terminal, attachment) = attach_readiness_boundary(session)?;
3607 let mut receiver = attachment.receiver;
3608 let mut tracker = ReadinessTracker::new(spec, RuntimePlatform::current(), intent);
3609 let mut diagnostics = ReadinessDiagnostics {
3610 draft_signal: Some(spec.readiness.draft_signal),
3611 ..ReadinessDiagnostics::default()
3612 };
3613 seed_readiness_from_terminal(
3614 &terminal,
3615 &mut tracker,
3616 &mut diagnostics,
3617 elapsed_ms(started),
3618 )?;
3619 let interval = Duration::from_millis(spec.readiness.poll_interval_ms.max(1));
3620 let mut next_probe = Instant::now();
3621
3622 for event in attachment.replay {
3623 observe_readiness_event(
3624 &mut tracker,
3625 &mut diagnostics,
3626 event.event,
3627 elapsed_ms(started),
3628 )?;
3629 if detect_startup_gates {
3630 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3631 ensure_no_startup_operator_gate(session, spec)?;
3632 }
3633 }
3634
3635 loop {
3636 if detect_startup_gates {
3637 ensure_no_startup_operator_gate(session, spec)?;
3638 }
3639 if Instant::now() >= next_probe {
3640 let foreground = session
3641 .observe_foreground()
3642 .await
3643 .map_err(|error| error.to_string())?;
3644 diagnostics.observe_foreground(&foreground.readiness);
3645 tracker.observe_foreground(&foreground.readiness, elapsed_ms(started));
3646 next_probe = Instant::now() + interval;
3647 }
3648 tracker.poll(elapsed_ms(started));
3649 if readiness_complete(tracker.status(), &diagnostics)? {
3650 if detect_startup_gates {
3651 ensure_no_startup_operator_gate(session, spec)?;
3652 }
3653 return tracker
3654 .into_permit()
3655 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3656 }
3657
3658 let wait = next_probe.saturating_duration_since(Instant::now());
3659 match tokio::time::timeout(wait, receiver.recv()).await {
3660 Ok(Ok(event)) => {
3661 if matches!(&event.event, PtyEvent::DataGap { .. }) {
3662 let (terminal, attachment) = attach_readiness_boundary(session)?;
3663 receiver = attachment.receiver;
3664 tracker = ReadinessTracker::new(
3665 spec,
3666 RuntimePlatform::current(),
3667 intent,
3668 );
3669 diagnostics = ReadinessDiagnostics {
3670 draft_signal: Some(spec.readiness.draft_signal),
3671 ..ReadinessDiagnostics::default()
3672 };
3673 seed_readiness_from_terminal(
3674 &terminal,
3675 &mut tracker,
3676 &mut diagnostics,
3677 elapsed_ms(started),
3678 )?;
3679 for retained in attachment.replay {
3680 observe_readiness_event(
3681 &mut tracker,
3682 &mut diagnostics,
3683 retained.event,
3684 elapsed_ms(started),
3685 )?;
3686 }
3687 } else {
3688 observe_readiness_event(
3689 &mut tracker,
3690 &mut diagnostics,
3691 event.event,
3692 elapsed_ms(started),
3693 )?;
3694 }
3695 if detect_startup_gates {
3696 ensure_no_readiness_operator_gate(&diagnostics, spec)?;
3697 ensure_no_startup_operator_gate(session, spec)?;
3698 }
3699 }
3700 Ok(Err(error)) => return Err(error.to_string()),
3701 Err(_) => {
3702 tracker.poll(elapsed_ms(started));
3703 }
3704 }
3705 if readiness_complete(tracker.status(), &diagnostics)? {
3706 if detect_startup_gates {
3707 ensure_no_startup_operator_gate(session, spec)?;
3708 }
3709 return tracker
3710 .into_permit()
3711 .ok_or_else(|| "ready tracker did not issue a permit".to_owned());
3712 }
3713 }
3714}
3715
3716fn attach_readiness_boundary(
3717 session: &PtySession,
3718) -> Result<(PtyTerminalSnapshot, PtyAttachment), String> {
3719 let terminal = session.terminal_state().map_err(|error| error.to_string())?;
3720 let cursor = PtyReplayCursor {
3721 provider_revision: terminal.provider_revision.clone(),
3722 generation: terminal.generation,
3723 next_sequence: terminal.sequence.saturating_add(1).max(1),
3724 };
3725 let attachment = session
3726 .attach_events(cursor)
3727 .map_err(|error| error.to_string())?;
3728 Ok((terminal, attachment))
3729}
3730
3731fn seed_readiness_from_terminal(
3732 terminal: &PtyTerminalSnapshot,
3733 tracker: &mut ReadinessTracker<'_>,
3734 diagnostics: &mut ReadinessDiagnostics,
3735 elapsed_ms: u64,
3736) -> Result<(), String> {
3737 const ENABLE_BRACKETED_PASTE: &[u8] = b"\x1b[?2004h";
3738 if terminal.bracketed_paste {
3739 diagnostics.observe_output(ENABLE_BRACKETED_PASTE);
3740 tracker.observe_output(ENABLE_BRACKETED_PASTE, elapsed_ms);
3741 }
3742 if !terminal.formatted.is_empty() {
3743 diagnostics.observe_output(&terminal.formatted);
3744 tracker.observe_output(&terminal.formatted, elapsed_ms);
3745 }
3746 Ok(())
3747}
3748
3749const STARTUP_GATE_SETTLE_MS: u64 = 350;
3750const STARTUP_GATE_POLL_MS: u64 = 25;
3751const FOREGROUND_RECLASSIFY_INTERVAL: Duration = Duration::from_secs(1);
3765const CODEX_PASTE_ENTER_SUPPRESSION_MS: u64 = 120;
3769const CODEX_POST_RENDER_MARGIN_MS: u64 = 30;
3770const CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3771const KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS: u64 = 5_000;
3772
3773async fn probe_fresh_codex_session_identity(
3774 session: &PtySession,
3775 spec: &AgentSpec,
3776) -> Result<Option<ProviderSessionIdentity>, String> {
3777 let permit = match wait_for_readiness(session, spec, ReadinessIntent::DraftPaste, true).await {
3778 Ok(permit) => permit,
3779 Err(_) => return Ok(None),
3780 };
3781 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3782 return Ok(None);
3783 }
3784 let baseline = session
3785 .terminal_state()
3786 .map_err(|error| error.to_string())?;
3787 let mut extractor = CodexPtySessionIdentityExtractor::default();
3788 session
3789 .send_input_action(
3790 InputAction::AgentCommand(AgentCommand {
3791 agent_id: spec.id.clone(),
3792 name: "status".to_owned(),
3793 arguments: Vec::new(),
3794 }),
3795 permit,
3796 )
3797 .await
3798 .map_err(|error| format!("Codex /status identity probe failed: {error}"))?;
3799
3800 let deadline = Instant::now()
3801 + Duration::from_millis(
3802 spec.readiness
3803 .timeout_ms
3804 .min(CODEX_SESSION_STATUS_PROBE_TIMEOUT_MS)
3805 .max(1),
3806 );
3807 loop {
3808 let snapshot = session
3809 .terminal_state()
3810 .map_err(|error| error.to_string())?;
3811 if snapshot.sequence > baseline.sequence {
3812 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3813 return Ok(Some(identity));
3814 }
3815 }
3816 if Instant::now() >= deadline {
3817 return Ok(None);
3818 }
3819 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3820 }
3821}
3822
3823async fn probe_fresh_kimi_session_identity(
3824 session: &PtySession,
3825 spec: &AgentSpec,
3826) -> Result<Option<ProviderSessionIdentity>, String> {
3827 let permit = match wait_for_readiness(
3828 session,
3829 spec,
3830 ReadinessIntent::FollowupPrompt,
3831 true,
3832 )
3833 .await
3834 {
3835 Ok(permit) => permit,
3836 Err(_) => return Ok(None),
3837 };
3838 if wait_for_startup_operator_gate(session, spec).await.is_err() {
3839 return Ok(None);
3840 }
3841 let baseline = session
3842 .terminal_state()
3843 .map_err(|error| error.to_string())?;
3844 let mut extractor = KimiPtySessionIdentityExtractor::default();
3845 if let Some(identity) = extractor.observe_screen(&baseline.contents) {
3846 return Ok(Some(identity));
3847 }
3848 session
3849 .send_input_action(
3850 InputAction::SubmitPrompt(PromptPayload {
3851 text: "/status".to_owned(),
3852 framing: PromptFraming::BracketedPaste,
3853 }),
3854 permit,
3855 )
3856 .await
3857 .map_err(|error| format!("Kimi /status identity probe failed: {error}"))?;
3858
3859 let deadline = Instant::now()
3860 + Duration::from_millis(
3861 spec.readiness
3862 .timeout_ms
3863 .min(KIMI_SESSION_STATUS_PROBE_TIMEOUT_MS)
3864 .max(1),
3865 );
3866 loop {
3867 let snapshot = session
3868 .terminal_state()
3869 .map_err(|error| error.to_string())?;
3870 if snapshot.sequence > baseline.sequence {
3871 if let Some(identity) = extractor.observe_screen(&snapshot.contents) {
3872 return Ok(Some(identity));
3873 }
3874 }
3875 if Instant::now() >= deadline {
3876 return Ok(None);
3877 }
3878 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
3879 }
3880}
3881
3882async fn deliver_pending_initial_prompt(
3883 session: &mut PtySession,
3884 spec: &AgentSpec,
3885) -> Result<(), String> {
3886 if session.pending_followup_prompt().is_none() {
3887 return Ok(());
3888 }
3889 let mut permit =
3890 wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3891 wait_for_startup_operator_gate(session, spec).await?;
3892 let render_confirmed_submit = spec.id.as_str() == "claude"
3893 || (RuntimePlatform::current() == RuntimePlatform::Windows
3894 && spec.id.as_str() == "codex");
3895 if render_confirmed_submit {
3896 let prompt = session
3897 .pending_followup_prompt()
3898 .ok_or_else(|| "deferred initial prompt disappeared before paste".to_owned())?
3899 .to_owned();
3900 let baseline = session
3901 .terminal_state()
3902 .map_err(|error| error.to_string())?;
3903 let inserted = session
3904 .insert_pending_followup_prompt(PromptFraming::BracketedPaste, &permit)
3905 .await
3906 .map_err(|error| error.to_string())?;
3907 if !inserted {
3908 return Err("deferred initial prompt was not inserted".to_owned());
3909 }
3910 wait_for_prompt_render(
3911 session,
3912 spec,
3913 &prompt,
3914 &baseline,
3915 spec.readiness.timeout_ms,
3916 )
3917 .await?;
3918 if RuntimePlatform::current() == RuntimePlatform::Windows && spec.id.as_str() == "codex" {
3919 tokio::time::sleep(Duration::from_millis(
3920 CODEX_PASTE_ENTER_SUPPRESSION_MS + CODEX_POST_RENDER_MARGIN_MS,
3921 ))
3922 .await;
3923 }
3924 permit = wait_for_readiness(session, spec, ReadinessIntent::FollowupPrompt, true).await?;
3925 wait_for_startup_operator_gate(session, spec).await?;
3926 }
3927 ensure_no_startup_operator_gate(session, spec)?;
3928 let submitted = session
3929 .submit_pending_followup(PromptFraming::BracketedPaste, permit)
3930 .await
3931 .map_err(|error| error.to_string())?;
3932 if !submitted {
3933 return Err("deferred initial prompt disappeared before delivery".to_owned());
3934 }
3935 Ok(())
3936}
3937
3938async fn wait_for_prompt_render(
3939 session: &PtySession,
3940 spec: &AgentSpec,
3941 prompt: &str,
3942 baseline: &PtyTerminalSnapshot,
3943 timeout_ms: u64,
3944) -> Result<(), String> {
3945 let probe = prompt_render_probe(&gate4agent_types::sanitize_prompt_text(prompt));
3946 let deadline = Instant::now() + Duration::from_millis(timeout_ms.max(1));
3947 loop {
3948 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
3949 if let Some(gate) = startup_operator_gate(&snapshot.contents) {
3950 return Err(startup_operator_error(spec, &gate));
3951 }
3952 if prompt_rendered(&snapshot, baseline, &probe) {
3953 return Ok(());
3954 }
3955 if Instant::now() >= deadline {
3956 let tail = terminal_tail(&snapshot.contents);
3957 let compact_tail = compact_alphanumeric(&tail);
3958 let baseline_tail = terminal_tail(&baseline.contents).to_ascii_lowercase();
3959 let normalized_tail = tail.to_ascii_lowercase();
3960 let retained = render_ack_event_summary(session, baseline.sequence);
3961 let foreground = session.observe_foreground().await.ok();
3962 let foreground_name = foreground
3963 .as_ref()
3964 .and_then(|observation| observation.readiness.process_name.as_deref())
3965 .map(safe_process_label)
3966 .unwrap_or_else(|| "none".to_owned());
3967 let child_live = retained.exit_code.is_none() && foreground.is_some();
3968 return Err(format!(
3969 "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={})",
3970 spec.id,
3971 baseline.sequence,
3972 snapshot.sequence,
3973 snapshot.sequence.saturating_sub(baseline.sequence),
3974 snapshot.cursor != baseline.cursor,
3975 baseline.bracketed_paste,
3976 snapshot.bracketed_paste,
3977 tail.chars().count(),
3978 probe.chars().count(),
3979 !probe.is_empty() && compact_tail.contains(&probe),
3980 paste_placeholder_visible(&baseline_tail),
3981 paste_placeholder_visible(&normalized_tail),
3982 child_live,
3983 foreground_name,
3984 retained.output,
3985 retained.foreground,
3986 retained.snapshots,
3987 retained.resized,
3988 retained.gaps,
3989 retained.reader_errors,
3990 retained.operator_actions,
3991 retained
3992 .exit_code
3993 .map_or_else(|| "none".to_owned(), |code| code.to_string()),
3994 if retained.output_flags.is_empty() {
3995 "none".to_owned()
3996 } else {
3997 retained.output_flags.join(",")
3998 },
3999 ));
4000 }
4001 tokio::time::sleep(Duration::from_millis(STARTUP_GATE_POLL_MS)).await;
4002 }
4003}
4004
4005#[derive(Default)]
4006struct RenderAckEventSummary {
4007 output: usize,
4008 foreground: usize,
4009 snapshots: usize,
4010 resized: usize,
4011 gaps: usize,
4012 reader_errors: usize,
4013 operator_actions: usize,
4014 exit_code: Option<i32>,
4015 output_flags: Vec<&'static str>,
4016}
4017
4018fn render_ack_event_summary(session: &PtySession, baseline_sequence: u64) -> RenderAckEventSummary {
4019 let mut summary = RenderAckEventSummary::default();
4020 let Ok(attachment) = session.attach_retained_events() else {
4021 return summary;
4022 };
4023 for envelope in attachment
4024 .replay
4025 .into_iter()
4026 .filter(|envelope| envelope.sequence > baseline_sequence)
4027 {
4028 match envelope.event {
4029 PtyEvent::Output(bytes) => {
4030 summary.output = summary.output.saturating_add(1);
4031 observe_render_ack_output_flags(&mut summary.output_flags, &bytes);
4032 }
4033 PtyEvent::ForegroundProcess(_) => {
4034 summary.foreground = summary.foreground.saturating_add(1);
4035 }
4036 PtyEvent::SnapshotAvailable { .. } => {
4037 summary.snapshots = summary.snapshots.saturating_add(1);
4038 }
4039 PtyEvent::Resized(_) => {
4040 summary.resized = summary.resized.saturating_add(1);
4041 }
4042 PtyEvent::DataGap { .. } => {
4043 summary.gaps = summary.gaps.saturating_add(1);
4044 }
4045 PtyEvent::ReaderError { .. } => {
4046 summary.reader_errors = summary.reader_errors.saturating_add(1);
4047 }
4048 PtyEvent::OperatorActionRequired { .. } => {
4049 summary.operator_actions = summary.operator_actions.saturating_add(1);
4050 }
4051 PtyEvent::Exited { code } => summary.exit_code = Some(code),
4052 PtyEvent::Started => {}
4053 }
4054 }
4055 summary
4056}
4057
4058fn observe_render_ack_output_flags(flags: &mut Vec<&'static str>, bytes: &[u8]) {
4059 let normalized = String::from_utf8_lossy(bytes).to_ascii_lowercase();
4060 for (label, marker) in [
4061 ("error", "error"),
4062 ("panic", "panic"),
4063 ("fatal", "fatal"),
4064 ("login", "login"),
4065 ("auth", "auth"),
4066 ("permission", "permission"),
4067 ("rate-limit", "rate limit"),
4068 ("usage-limit", "usage limit"),
4069 ("update", "update"),
4070 ("working", "working"),
4071 ("thinking", "thinking"),
4072 ] {
4073 if normalized.contains(marker) && !flags.contains(&label) {
4074 flags.push(label);
4075 }
4076 }
4077}
4078
4079fn safe_process_label(process_name: &str) -> String {
4080 process_name
4081 .chars()
4082 .take(64)
4083 .map(|character| {
4084 if character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | '-') {
4085 character
4086 } else {
4087 '?'
4088 }
4089 })
4090 .collect()
4091}
4092
4093fn prompt_rendered(
4094 snapshot: &PtyTerminalSnapshot,
4095 baseline: &PtyTerminalSnapshot,
4096 probe: &str,
4097) -> bool {
4098 if snapshot.sequence <= baseline.sequence {
4099 return false;
4100 }
4101 let tail = terminal_tail(&snapshot.contents);
4102 let compact = compact_alphanumeric(&tail);
4103 if !probe.is_empty() && compact.contains(probe) {
4104 return true;
4105 }
4106 let normalized_tail = tail.to_ascii_lowercase();
4107 let normalized_baseline = terminal_tail(&baseline.contents).to_ascii_lowercase();
4108 paste_placeholder_visible(&normalized_tail)
4109 && !paste_placeholder_visible(&normalized_baseline)
4110}
4111
4112fn paste_placeholder_visible(normalized_tail: &str) -> bool {
4113 normalized_tail.contains("[pasted content")
4117 || normalized_tail.contains("[pasted text #")
4118}
4119
4120fn terminal_tail(contents: &str) -> String {
4121 let mut lines = contents.lines().rev().take(12).collect::<Vec<_>>();
4122 lines.reverse();
4123 lines.join("\n")
4124}
4125
4126fn prompt_render_probe(prompt: &str) -> String {
4127 let compact = compact_alphanumeric(prompt);
4128 let chars = compact.chars().collect::<Vec<_>>();
4129 chars[chars.len().saturating_sub(32)..].iter().collect()
4130}
4131
4132fn compact_alphanumeric(value: &str) -> String {
4133 value
4134 .chars()
4135 .filter(|character| character.is_alphanumeric())
4136 .flat_map(char::to_lowercase)
4137 .collect()
4138}
4139
4140async fn wait_for_startup_operator_gate(
4141 session: &PtySession,
4142 spec: &AgentSpec,
4143) -> Result<(), String> {
4144 let deadline = Instant::now() + Duration::from_millis(STARTUP_GATE_SETTLE_MS);
4145 loop {
4146 ensure_no_startup_operator_gate(session, spec)?;
4147 let now = Instant::now();
4148 if now >= deadline {
4149 return Ok(());
4150 }
4151 tokio::time::sleep(
4152 deadline
4153 .saturating_duration_since(now)
4154 .min(Duration::from_millis(STARTUP_GATE_POLL_MS)),
4155 )
4156 .await;
4157 }
4158}
4159
4160fn ensure_no_startup_operator_gate(session: &PtySession, spec: &AgentSpec) -> Result<(), String> {
4180 let snapshot = session.terminal_state().map_err(|error| error.to_string())?;
4181 match startup_operator_gate(&snapshot.contents) {
4182 Some(gate) => Err(startup_operator_error(spec, &gate)),
4183 None => Ok(()),
4184 }
4185}
4186
4187fn startup_operator_error(spec: &AgentSpec, gate: &OperatorGateState) -> String {
4188 format!(
4189 "agent '{}' requires operator action at startup ({gate}); initial prompt was not submitted",
4190 spec.id
4191 )
4192}
4193
4194fn ensure_no_readiness_operator_gate(
4195 diagnostics: &ReadinessDiagnostics,
4196 spec: &AgentSpec,
4197) -> Result<(), String> {
4198 match &diagnostics.operator_gate {
4199 Some(gate) => Err(startup_operator_error(spec, gate)),
4200 None => Ok(()),
4201 }
4202}
4203
4204fn normalize_screen_text(contents: &str) -> String {
4211 contents
4212 .split_whitespace()
4213 .collect::<Vec<_>>()
4214 .join(" ")
4215 .to_ascii_lowercase()
4216}
4217
4218const PACKAGE_MANAGER_INSTALL_MARKERS: &[&str] = &[
4224 "npm install -g",
4225 "npm i -g",
4226 "npm update -g",
4227 "pip install --upgrade",
4228 "pip install -u",
4229 "yarn global add",
4230 "pnpm add -g",
4231];
4232
4233const PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS: &[&str] = &[
4239 "update ran successfully",
4240 "please restart",
4241 "update complete",
4242 "updated successfully",
4243];
4244
4245fn operator_gate(kind: OperatorGateKind, subject: OperatorGateSubject, contents: &str) -> OperatorGateState {
4256 let (input, options) = parse_operator_gate_options(contents);
4257 OperatorGateState::new(kind)
4258 .with_subject(subject)
4259 .with_options(input, options)
4260}
4261
4262fn startup_operator_gate(contents: &str) -> Option<OperatorGateState> {
4263 let normalized = normalize_screen_text(contents);
4264 if [
4265 "trust this folder",
4266 "trust the files in this folder",
4267 "trust the contents of this directory",
4268 "do you trust this directory",
4269 ]
4270 .iter()
4271 .any(|marker| normalized.contains(marker))
4272 {
4273 return Some(operator_gate(
4274 OperatorGateKind::WorkspaceTrust,
4275 OperatorGateSubject::Directory { path: None },
4276 contents,
4277 ));
4278 }
4279 if normalized.contains("quick safety check")
4280 && (normalized.contains("yes, i trust this folder")
4281 || normalized.contains("continue without these permissions"))
4282 {
4283 return Some(operator_gate(
4284 OperatorGateKind::WorkspaceTrust,
4285 OperatorGateSubject::Directory { path: None },
4286 contents,
4287 ));
4288 }
4289 if normalized.contains("hooks need review") && normalized.contains("continue without trusting")
4304 {
4305 return Some(operator_gate(
4306 OperatorGateKind::HookTrust,
4307 OperatorGateSubject::Hooks { count: None },
4308 contents,
4309 ));
4310 }
4311 if [
4312 "select authentication method",
4313 "choose how to authenticate",
4314 "no auth type is selected",
4315 ]
4316 .iter()
4317 .any(|marker| normalized.contains(marker))
4318 {
4319 return Some(operator_gate(
4320 OperatorGateKind::Authentication,
4321 OperatorGateSubject::Account,
4322 contents,
4323 ));
4324 }
4325 if normalized.contains("sign in")
4326 && (normalized.contains("openai")
4327 || normalized.contains("chatgpt")
4328 || normalized.contains("codex"))
4329 {
4330 return Some(operator_gate(
4331 OperatorGateKind::Authentication,
4332 OperatorGateSubject::Account,
4333 contents,
4334 ));
4335 }
4336 if normalized.contains("select login method") {
4345 return Some(operator_gate(
4346 OperatorGateKind::Authentication,
4347 OperatorGateSubject::Account,
4348 contents,
4349 ));
4350 }
4351 if normalized.contains("sign in") && normalized.contains("paste code") {
4363 return Some(
4364 OperatorGateState::new(OperatorGateKind::Authentication)
4365 .with_subject(OperatorGateSubject::Account)
4366 .with_options(OperatorGateInput::TextEntry, Vec::new()),
4367 );
4368 }
4369 if normalized.contains("kimi code update available")
4370 && normalized.contains("install update now")
4371 {
4372 return Some(operator_gate(
4373 OperatorGateKind::VendorUpdate,
4374 OperatorGateSubject::Unknown,
4375 contents,
4376 ));
4377 }
4378 if PACKAGE_MANAGER_INSTALL_MARKERS
4389 .iter()
4390 .any(|marker| normalized.contains(marker))
4391 && PACKAGE_MANAGER_UPDATE_COMPLETION_MARKERS
4392 .iter()
4393 .any(|marker| normalized.contains(marker))
4394 {
4395 return Some(operator_gate(
4396 OperatorGateKind::VendorUpdate,
4397 OperatorGateSubject::Unknown,
4398 contents,
4399 ));
4400 }
4401 if normalized.contains("choose the text style that looks best with your terminal") {
4402 return Some(operator_gate(
4403 OperatorGateKind::TerminalAppearance,
4404 OperatorGateSubject::Appearance,
4405 contents,
4406 ));
4407 }
4408 if normalized.contains("welcome to claude code for")
4409 && (normalized.contains("open files") || normalized.contains("selected lines"))
4410 {
4411 return Some(operator_gate(
4412 OperatorGateKind::Onboarding,
4413 OperatorGateSubject::Unknown,
4414 contents,
4415 ));
4416 }
4417 if normalized.contains("welcome to claude code")
4418 && (normalized.contains("press enter") || normalized.contains("enter to continue"))
4419 {
4420 return Some(operator_gate(
4421 OperatorGateKind::Onboarding,
4422 OperatorGateSubject::Unknown,
4423 contents,
4424 ));
4425 }
4426 if normalized.contains("migration") && normalized.contains("enter confirm") && normalized.contains("esc")
4427 {
4428 return Some(operator_gate(
4429 OperatorGateKind::ConfigurationMigration,
4430 OperatorGateSubject::Unknown,
4431 contents,
4432 ));
4433 }
4434 None
4435}
4436
4437fn parse_operator_gate_options(contents: &str) -> (OperatorGateInput, Vec<OperatorGateOption>) {
4459 let numbered: Vec<OperatorGateOption> = contents
4460 .lines()
4461 .filter_map(parse_numbered_gate_option_line)
4462 .take(OPERATOR_GATE_OPTIONS_MAX)
4463 .collect();
4464 if !numbered.is_empty() {
4465 return (OperatorGateInput::NumberedList, numbered);
4466 }
4467 let arrow: Vec<OperatorGateOption> = contents
4468 .lines()
4469 .filter_map(parse_arrow_gate_option_line)
4470 .take(OPERATOR_GATE_OPTIONS_MAX)
4471 .collect();
4472 if !arrow.is_empty() {
4473 return (OperatorGateInput::ArrowList, arrow);
4474 }
4475 (OperatorGateInput::Unknown, Vec::new())
4476}
4477
4478const GATE_CURSOR_GLYPHS: [char; 2] = ['\u{203a}', '\u{276f}'];
4492
4493fn parse_numbered_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4494 let trimmed = line.trim_start();
4495 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4503 Some(stripped) => (true, stripped.trim_start()),
4504 None => (false, trimmed),
4505 };
4506 let digits_end = rest.find(|character: char| !character.is_ascii_digit()).unwrap_or(0);
4507 if digits_end == 0 {
4508 return None;
4509 }
4510 let text = rest[digits_end..].strip_prefix('.')?.trim();
4511 if text.is_empty() {
4512 return None;
4513 }
4514 Some(OperatorGateOption {
4515 semantics: classify_operator_gate_option_semantics(text),
4516 text: text.to_owned(),
4517 selected,
4518 })
4519}
4520
4521fn parse_arrow_gate_option_line(line: &str) -> Option<OperatorGateOption> {
4545 let trimmed = line.trim();
4546 if trimmed.is_empty()
4547 || trimmed
4548 .chars()
4549 .any(|character| matches!(character, '.' | '?' | '!' | ':'))
4550 {
4551 return None;
4552 }
4553 let lower = trimmed.to_ascii_lowercase();
4554 if lower.contains('\u{2191}') || lower.contains('\u{2193}') || lower.contains("navigate") {
4555 return None;
4556 }
4557 let (selected, rest) = match trimmed.strip_prefix(GATE_CURSOR_GLYPHS) {
4558 Some(stripped) => (true, stripped.trim()),
4559 None => (false, trimmed),
4560 };
4561 if rest.is_empty() || !rest.chars().any(|character| character.is_alphabetic()) {
4562 return None;
4563 }
4564 let semantics = classify_operator_gate_option_semantics(rest);
4565 if !selected && semantics == OperatorGateOptionSemantics::Unknown {
4566 return None;
4567 }
4568 Some(OperatorGateOption {
4569 semantics,
4570 text: rest.to_owned(),
4571 selected,
4572 })
4573}
4574
4575fn classify_operator_gate_option_semantics(text: &str) -> OperatorGateOptionSemantics {
4583 let lower = text.to_ascii_lowercase();
4584 if lower.contains("review") {
4585 OperatorGateOptionSemantics::Inspect
4586 } else if lower.contains("don't trust")
4587 || lower.contains("do not trust")
4588 || lower.contains("without trusting")
4589 || lower.contains("decline")
4590 {
4591 OperatorGateOptionSemantics::Decline
4592 } else if lower.contains("trust") || lower.contains("continue") || lower.contains("proceed") {
4593 OperatorGateOptionSemantics::Accept
4594 } else if lower.contains("exit") || lower.contains("quit") || lower.contains("cancel") {
4595 OperatorGateOptionSemantics::Exit
4596 } else {
4597 OperatorGateOptionSemantics::Unknown
4598 }
4599}
4600
4601fn looks_like_shell_prompt_line(line: &str) -> bool {
4606 matches!(line.trim_end().chars().last(), Some('$' | '%' | '#' | '>'))
4607}
4608
4609fn screen_failure(contents: &str) -> Option<&'static str> {
4632 let normalized = normalize_screen_text(contents);
4633
4634 if ["panicked at", "unhandled exception", "traceback (most recent call last)"]
4643 .iter()
4644 .any(|marker| normalized.contains(marker))
4645 {
4646 return Some("crash");
4647 }
4648
4649 if normalized.contains("command not found")
4655 || normalized.contains("is not recognized as an internal or external command")
4656 || (normalized.contains("no such file or directory")
4657 && contents.lines().any(looks_like_shell_prompt_line))
4658 {
4659 return Some("missing command");
4660 }
4661
4662 if normalized.contains("api key required") && normalized.contains("grok_api_key") {
4673 return Some("missing api key");
4674 }
4675
4676 None
4677}
4678
4679fn screen_failure_for_generation(contents: &str, ever_reached_ready: bool) -> Option<&'static str> {
4686 if ever_reached_ready {
4687 None
4688 } else {
4689 screen_failure(contents)
4690 }
4691}
4692
4693#[derive(Clone, Debug, Eq, PartialEq)]
4696enum ForegroundVerdict {
4697 Agent,
4699 Foreign { process: String },
4701}
4702
4703fn classify_pty_screen_state(
4729 foreground: Option<&ForegroundVerdict>,
4730 gate: Option<&OperatorGateState>,
4731 failure: Option<&'static str>,
4732) -> PtyScreenState {
4733 if let Some(ForegroundVerdict::Foreign { process }) = foreground {
4734 return PtyScreenState::NotAgent {
4735 observed_process: process.clone(),
4736 };
4737 }
4738 if let Some(reason) = failure {
4739 return PtyScreenState::Failing {
4740 reason: reason.to_owned(),
4741 };
4742 }
4743 if let Some(gate) = gate {
4744 return PtyScreenState::OperatorGate { gate: gate.clone() };
4745 }
4746 if foreground.is_some() {
4747 PtyScreenState::Ready
4748 } else {
4749 PtyScreenState::Unknown
4750 }
4751}
4752
4753fn resolve_foreground_verdict(
4769 spec: &AgentSpec,
4770 observation: &PtyForegroundObservation,
4771 platform: RuntimePlatform,
4772) -> ForegroundVerdict {
4773 let process_name = observation
4774 .readiness
4775 .process_name
4776 .as_deref()
4777 .unwrap_or(observation.observed_process.as_str());
4778 if is_expected_agent_process(spec, process_name, platform)
4779 || is_agent_foreground_wrapper(process_name, platform)
4780 {
4781 ForegroundVerdict::Agent
4782 } else {
4783 ForegroundVerdict::Foreign {
4784 process: observation.observed_process.clone(),
4785 }
4786 }
4787}
4788
4789#[derive(Clone, Copy, Debug, Eq, PartialEq)]
4795enum ForegroundProbeSchedule {
4796 Disarmed,
4798 Armed,
4800}
4801
4802fn foreground_probe_schedule(state: &PtyScreenState) -> ForegroundProbeSchedule {
4803 if matches!(state, PtyScreenState::Ready) {
4804 ForegroundProbeSchedule::Disarmed
4805 } else {
4806 ForegroundProbeSchedule::Armed
4807 }
4808}
4809
4810fn foreground_probe_rearms_immediately(previous: &PtyScreenState, next: &PtyScreenState) -> bool {
4818 matches!(previous, PtyScreenState::Ready) && !matches!(next, PtyScreenState::Ready)
4819}
4820
4821fn observe_readiness_event(
4822 tracker: &mut ReadinessTracker<'_>,
4823 diagnostics: &mut ReadinessDiagnostics,
4824 event: PtyEvent,
4825 elapsed_ms: u64,
4826) -> Result<(), String> {
4827 match event {
4828 PtyEvent::Output(data) => {
4829 diagnostics.observe_output(&data);
4830 tracker.observe_output(&data, elapsed_ms);
4831 }
4832 PtyEvent::ForegroundProcess(observation) => {
4833 diagnostics.observe_foreground(&observation.readiness);
4834 tracker.observe_foreground(&observation.readiness, elapsed_ms);
4835 }
4836 PtyEvent::DataGap { .. } => {
4837 return Err("PTY replay gap prevents positive readiness proof".to_owned());
4838 }
4839 PtyEvent::ReaderError { message } | PtyEvent::OperatorActionRequired { message } => {
4840 return Err(message);
4841 }
4842 PtyEvent::Exited { code } => {
4843 return Err(format!("PTY exited with code {code} before readiness"));
4844 }
4845 PtyEvent::Started | PtyEvent::Resized(_) | PtyEvent::SnapshotAvailable { .. } => {}
4846 }
4847 Ok(())
4848}
4849
4850#[derive(Default)]
4851struct ReadinessDiagnostics {
4852 draft_signal: Option<gate4agent_types::DraftReadySignal>,
4853 output_bytes: usize,
4854 output_chunks: usize,
4855 tail: Vec<u8>,
4856 saw_bracketed_paste: bool,
4857 saw_cursor_show: bool,
4858 saw_cursor_hide: bool,
4859 saw_alternate_screen: bool,
4860 saw_clear_screen: bool,
4861 saw_claude_composer: bool,
4862 saw_codex_composer: bool,
4863 saw_named_foreground: bool,
4864 operator_gate: Option<OperatorGateState>,
4865}
4866
4867impl ReadinessDiagnostics {
4868 fn observe_output(&mut self, data: &[u8]) {
4869 const SIGNAL_TAIL_BYTES: usize = 4_096;
4870 self.output_bytes = self.output_bytes.saturating_add(data.len());
4871 self.output_chunks = self.output_chunks.saturating_add(1);
4872 let mut combined = Vec::with_capacity(self.tail.len().saturating_add(data.len()));
4873 combined.extend_from_slice(&self.tail);
4874 combined.extend_from_slice(data);
4875 self.saw_bracketed_paste |= readiness_bytes_contain(&combined, b"\x1b[?2004h");
4876 self.saw_cursor_show |= readiness_bytes_contain(&combined, b"\x1b[?25h");
4877 self.saw_cursor_hide |= readiness_bytes_contain(&combined, b"\x1b[?25l");
4878 self.saw_alternate_screen |= readiness_bytes_contain(&combined, b"\x1b[?1049h");
4879 self.saw_clear_screen |= readiness_bytes_contain(&combined, b"\x1b[2J");
4880 self.saw_claude_composer |= readiness_bytes_contain(&combined, "❯".as_bytes());
4881 self.saw_codex_composer |= readiness_bytes_contain(&combined, "›".as_bytes());
4882 let text = String::from_utf8_lossy(&combined);
4883 self.operator_gate = self
4884 .operator_gate
4885 .take()
4886 .or_else(|| startup_operator_gate(&strip_ansi_codes(&text)));
4887 self.tail = combined[combined.len().saturating_sub(SIGNAL_TAIL_BYTES)..].to_vec();
4888 }
4889
4890 fn observe_foreground(&mut self, foreground: &gate4agent::agent::ForegroundObservation) {
4891 self.saw_named_foreground |= foreground.process_name.is_some();
4892 }
4893
4894 fn summary(&self) -> String {
4895 format!(
4896 "draft_signal={:?} output_bytes={} output_chunks={} named_foreground={} bracketed_paste={} cursor_show={} cursor_hide={} alternate_screen={} clear_screen={} claude_composer={} codex_composer={} csi={}",
4897 self.draft_signal,
4898 self.output_bytes,
4899 self.output_chunks,
4900 self.saw_named_foreground,
4901 self.saw_bracketed_paste,
4902 self.saw_cursor_show,
4903 self.saw_cursor_hide,
4904 self.saw_alternate_screen,
4905 self.saw_clear_screen,
4906 self.saw_claude_composer,
4907 self.saw_codex_composer,
4908 readiness_csi_signatures(&self.tail),
4909 )
4910 }
4911}
4912
4913fn readiness_csi_signatures(bytes: &[u8]) -> String {
4914 let mut signatures = Vec::new();
4915 let mut index = 0;
4916 while index + 2 < bytes.len() && signatures.len() < 32 {
4917 if bytes[index] != 0x1b || bytes[index + 1] != b'[' {
4918 index += 1;
4919 continue;
4920 }
4921 let mut end = index + 2;
4922 while end < bytes.len() && end.saturating_sub(index) <= 24 {
4923 let byte = bytes[end];
4924 if (0x40..=0x7e).contains(&byte) {
4925 let signature = String::from_utf8_lossy(&bytes[index + 2..=end]).into_owned();
4926 if !signatures.iter().any(|existing| existing == &signature) {
4927 signatures.push(signature);
4928 }
4929 index = end;
4930 break;
4931 }
4932 if !(0x20..=0x3f).contains(&byte) {
4933 break;
4934 }
4935 end += 1;
4936 }
4937 index += 1;
4938 }
4939 if signatures.is_empty() {
4940 "none".to_owned()
4941 } else {
4942 signatures.join("|")
4943 }
4944}
4945
4946fn readiness_bytes_contain(haystack: &[u8], needle: &[u8]) -> bool {
4947 haystack
4948 .windows(needle.len())
4949 .any(|window| window == needle)
4950}
4951
4952fn readiness_complete(
4953 status: ReadinessStatus,
4954 diagnostics: &ReadinessDiagnostics,
4955) -> Result<bool, String> {
4956 match status {
4957 ReadinessStatus::Waiting => Ok(false),
4958 ReadinessStatus::Ready(_) => Ok(true),
4959 ReadinessStatus::TimedOut => Err(format!(
4960 "PTY readiness timed out ({})",
4961 diagnostics.summary()
4962 )),
4963 }
4964}
4965
4966fn elapsed_ms(started: Instant) -> u64 {
4967 u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX)
4968}
4969
4970#[cfg(test)]
4971mod tests {
4972 use super::{
4973 acp_approval_level_args,
4974 approval_level_not_offered_message,
4975 classify_operator_gate_option_semantics,
4976 classify_pty_screen_state,
4977 defers_permission_requests,
4978 foreground_probe_rearms_immediately, foreground_probe_schedule,
4979 argument_looks_like_credential, host_policy_for_approval_level,
4980 mcp_server_acp_entry,
4981 parse_operator_gate_options, prepare_fresh_pty_provider_session,
4982 prompt_render_probe, prompt_rendered, required_acp_mode,
4983 reserve_provider_gap_sequence, resolve_foreground_verdict, screen_failure,
4984 screen_failure_for_generation, with_pty_terminal_capability_defaults,
4985 should_attach_pty_provider_stream, should_probe_pty_identity, startup_operator_gate,
4986 terminal_frame, terminal_frame_byte_len, terminal_state_capture_should_skip,
4987 validate_instance_launch_arguments, validate_spawn_runtime_policy,
4988 ForegroundProbeSchedule, ForegroundVerdict, ReadinessDiagnostics, RateLimitFeed,
4989 Utf8ChunkDecoder,
4990 };
4991 use gate4agent::acp::protocol::{McpServerConfig, SessionMode};
4992 use gate4agent::HostPolicy;
4993 use gate4agent_adapters::builtin_adapter_registry;
4994 use gate4agent_catalog::{EnvMutation, McpServerSpec, ModeId};
4995 use gate4agent::agent::ForegroundObservation;
4996 use gate4agent::core::types::{
4997 AgentEvent, ContextWindowUsage as AgentContextWindowUsage, HostDecisionAuthority,
4998 HostRequestDecision, HostRequestOutcome, RateLimitType,
4999 };
5000 use gate4agent::pty::event::PtyMouseProtocolEncoding;
5001 use gate4agent::pty::{PtyForegroundObservation, PtyForegroundSource, RateLimitDetector};
5002 use gate4agent::CliTool;
5003 use gate4agent_types::{
5004 AdapterFamily, AgentId, ApprovalLevel,
5005 HostDecisionAuthority as ProviderHostDecisionAuthority,
5006 HostRequestDecision as ProviderHostRequestDecision,
5007 HostRequestOutcome as ProviderHostRequestOutcome, OperatorGateInput,
5008 OperatorGateKind, OperatorGateOptionSemantics, OperatorGateState, OperatorGateSubject,
5009 ProviderEvent, ProviderInteractionKind, ProviderInteractionOption, ProviderRuntimePolicy,
5010 PtyScreenState, RuntimePlatform, TerminalMouseProtocolEncoding, TransportKind,
5011 };
5012 use std::ffi::{OsStr, OsString};
5013
5014 fn snapshot(sequence: u64, contents: &str) -> super::PtyTerminalSnapshot {
5015 super::PtyTerminalSnapshot {
5016 pty_id: "fixture".to_owned(),
5017 provider_revision: "fixture-r1".to_owned(),
5018 generation: 1,
5019 sequence,
5020 size: gate4agent::pty::PtySize { rows: 24, cols: 80 },
5021 cursor: (0, 0),
5022 bracketed_paste: false,
5023 contents: contents.to_owned(),
5024 formatted: Vec::new(),
5025 scrollback_formatted: Vec::new(),
5026 alternate_screen: false,
5027 mouse_protocol_enabled: false,
5028 mouse_protocol_encoding: PtyMouseProtocolEncoding::Default,
5029 produced_at_unix_ms: 0,
5030 }
5031 }
5032
5033 #[test]
5034 fn terminal_frame_preserves_scrollback_and_terminal_input_metadata() {
5035 let mut snapshot = snapshot(7, "visible");
5036 snapshot.scrollback_formatted = vec![b"older".to_vec()];
5037 snapshot.alternate_screen = true;
5038 snapshot.mouse_protocol_enabled = true;
5039 snapshot.mouse_protocol_encoding = PtyMouseProtocolEncoding::Sgr;
5040 snapshot.produced_at_unix_ms = 1_700_000_000_000;
5041
5042 let frame = terminal_frame(snapshot, PtyScreenState::default());
5043 assert_eq!(frame.scrollback_formatted, vec![b"older".to_vec()]);
5044 assert!(frame.alternate_screen);
5045 assert!(frame.mouse_protocol_enabled);
5046 assert_eq!(frame.mouse_protocol_encoding, TerminalMouseProtocolEncoding::Sgr);
5047 assert_eq!(frame.produced_at_unix_ms, 1_700_000_000_000);
5049 }
5050
5051 #[test]
5052 fn terminal_frame_byte_len_sums_formatted_and_every_scrollback_row() {
5053 let mut snapshot = snapshot(9, "visible");
5054 snapshot.formatted = b"\x1b[2Jvisible".to_vec();
5055 snapshot.scrollback_formatted =
5056 vec![b"row one".to_vec(), b"row two, longer".to_vec()];
5057 let expected = snapshot.formatted.len()
5058 + snapshot.scrollback_formatted[0].len()
5059 + snapshot.scrollback_formatted[1].len();
5060
5061 let frame = terminal_frame(snapshot, PtyScreenState::default());
5062 assert_eq!(terminal_frame_byte_len(&frame), expected as u64);
5063 }
5064
5065 #[test]
5066 fn the_sequence_gate_skips_only_when_the_sequence_did_not_advance() {
5067 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(5), 5));
5068 assert!(terminal_state_capture_should_skip(Ok::<u64, ()>(4), 5));
5069 assert!(!terminal_state_capture_should_skip(Ok::<u64, ()>(6), 5));
5070 assert!(!terminal_state_capture_should_skip(Err::<u64, ()>(()), 5));
5073 }
5074
5075 #[test]
5076 fn structured_context_usage_maps_without_pty_inference() {
5077 let mapped = super::provider_event(
5078 AgentEvent::ContextWindowUsage {
5079 usage: AgentContextWindowUsage {
5080 uncached_input_tokens: 70,
5081 cache_read_tokens: 20,
5082 cache_write_tokens: 0,
5083 output_tokens: 10,
5084 unattributed_tokens: 5,
5085 used_tokens: 105,
5086 capacity_tokens: 100,
5087 },
5088 },
5089 &[],
5090 );
5091 assert_eq!(
5092 mapped,
5093 Some(ProviderEvent::ContextWindowUsage {
5094 usage: gate4agent_types::ContextWindowUsage {
5095 uncached_input_tokens: 70,
5096 cache_read_tokens: 20,
5097 cache_write_tokens: 0,
5098 output_tokens: 10,
5099 unattributed_tokens: 5,
5100 used_tokens: 105,
5101 capacity_tokens: 100,
5102 }
5103 })
5104 );
5105 assert_eq!(
5106 ProviderEvent::ContextWindowUsage {
5107 usage: gate4agent_types::ContextWindowUsage {
5108 uncached_input_tokens: 70,
5109 cache_read_tokens: 20,
5110 cache_write_tokens: 0,
5111 output_tokens: 10,
5112 unattributed_tokens: 5,
5113 used_tokens: 104,
5114 capacity_tokens: 100,
5115 },
5116 }
5117 .validate_ingress(),
5118 Err(gate4agent_types::ProviderEventValidationError::ContextWindowSegmentsMismatch {
5119 segment_sum: 105,
5120 used_tokens: 104,
5121 })
5122 );
5123 assert!(
5124 super::provider_event(AgentEvent::PtyRaw { data: b"105/100".to_vec() }, &[]).is_none()
5125 );
5126 }
5127
5128 #[test]
5137 fn turn_interrupted_maps_to_the_provider_event_that_unblocks_the_next_prompt() {
5138 let mapped = super::provider_event(
5139 AgentEvent::TurnInterrupted {
5140 reason: "session/prompt timed out after 120s".to_owned(),
5141 },
5142 &[],
5143 );
5144 assert_eq!(mapped, Some(ProviderEvent::TurnInterrupted));
5145 }
5146
5147 #[test]
5148 fn tool_result_non_execution_kind_carries_through_to_tool_completed() {
5149 let mapped = super::provider_event(
5150 AgentEvent::ToolResult {
5151 id: "t1".to_owned(),
5152 output: "denied".to_owned(),
5153 is_error: true,
5154 duration_ms: None,
5155 non_execution_kind: Some("permission-rule".to_owned()),
5156 },
5157 &[],
5158 );
5159 assert_eq!(
5160 mapped,
5161 Some(ProviderEvent::ToolCompleted {
5162 id: "t1".to_owned(),
5163 output: "denied".to_owned(),
5164 is_error: true,
5165 duration_ms: None,
5166 agent_id: None,
5167 non_execution_kind: Some("permission-rule".to_owned()),
5168 })
5169 );
5170 }
5171
5172 #[test]
5173 fn session_end_stop_reason_carries_through_to_session_ended() {
5174 use gate4agent::StopReason;
5175
5176 let refusal = super::provider_event(
5177 AgentEvent::SessionEnd {
5178 result: "refusal".to_owned(),
5179 cost_usd: None,
5180 is_error: true,
5181 stop_reason: Some(StopReason::Refusal),
5182 },
5183 &[],
5184 );
5185 assert_eq!(
5186 refusal,
5187 Some(ProviderEvent::SessionEnded {
5188 result: "refusal".to_owned(),
5189 cost_usd: None,
5190 is_error: true,
5191 stop_reason: Some(gate4agent_types::ProviderStopReason::Refusal),
5192 })
5193 );
5194
5195 let quota = super::provider_event(
5196 AgentEvent::SessionEnd {
5197 result: "JSON-RPC error -32603: Internal error".to_owned(),
5198 cost_usd: None,
5199 is_error: true,
5200 stop_reason: Some(StopReason::ProviderError {
5201 code: -32603,
5202 message: "You've hit your usage limit.".to_owned(),
5203 vendor_code: Some("usageLimitExceeded".to_owned()),
5204 }),
5205 },
5206 &[],
5207 );
5208 assert_eq!(
5209 quota,
5210 Some(ProviderEvent::SessionEnded {
5211 result: "JSON-RPC error -32603: Internal error".to_owned(),
5212 cost_usd: None,
5213 is_error: true,
5214 stop_reason: Some(gate4agent_types::ProviderStopReason::ProviderError {
5215 code: -32603,
5216 message: "You've hit your usage limit.".to_owned(),
5217 vendor_code: Some("usageLimitExceeded".to_owned()),
5218 }),
5219 })
5220 );
5221 }
5222
5223 #[test]
5224 fn host_request_reaches_the_operator_with_method_and_host_decision() {
5225 let denied = super::provider_event(
5226 AgentEvent::RpcIncomingRequest {
5227 id: gate4agent::rpc::message::RpcId::Number(1),
5228 method: "fs/read_text_file".to_owned(),
5229 params: None,
5230 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Policy },
5231 outcome: HostRequestOutcome::Executed,
5232 reason: None,
5233 },
5234 &[],
5235 );
5236 assert_eq!(
5237 denied,
5238 Some(ProviderEvent::HostRequestObserved {
5239 method: "fs/read_text_file".to_owned(),
5240 params_json: String::new(),
5241 decision: ProviderHostRequestDecision::Denied {
5242 by: ProviderHostDecisionAuthority::Policy
5243 },
5244 outcome: ProviderHostRequestOutcome::Executed,
5245 reason: None,
5246 })
5247 );
5248
5249 let granted = super::provider_event(
5250 AgentEvent::RpcIncomingRequest {
5251 id: gate4agent::rpc::message::RpcId::Number(2),
5252 method: "terminal/create".to_owned(),
5253 params: None,
5254 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5255 outcome: HostRequestOutcome::Executed,
5256 reason: None,
5257 },
5258 &[],
5259 );
5260 assert_eq!(
5261 granted,
5262 Some(ProviderEvent::HostRequestObserved {
5263 method: "terminal/create".to_owned(),
5264 params_json: String::new(),
5265 decision: ProviderHostRequestDecision::Granted {
5266 by: ProviderHostDecisionAuthority::Policy
5267 },
5268 outcome: ProviderHostRequestOutcome::Executed,
5269 reason: None,
5270 })
5271 );
5272
5273 let gate_denied = super::provider_event(
5277 AgentEvent::RpcIncomingRequest {
5278 id: gate4agent::rpc::message::RpcId::Number(3),
5279 method: "terminal/create".to_owned(),
5280 params: None,
5281 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5282 outcome: HostRequestOutcome::Executed,
5283 reason: None,
5284 },
5285 &[],
5286 );
5287 assert_eq!(
5288 gate_denied,
5289 Some(ProviderEvent::HostRequestObserved {
5290 method: "terminal/create".to_owned(),
5291 params_json: String::new(),
5292 decision: ProviderHostRequestDecision::Denied {
5293 by: ProviderHostDecisionAuthority::Gate
5294 },
5295 outcome: ProviderHostRequestOutcome::Executed,
5296 reason: None,
5297 })
5298 );
5299
5300 let operator_granted = super::provider_event(
5301 AgentEvent::RpcIncomingRequest {
5302 id: gate4agent::rpc::message::RpcId::Number(4),
5303 method: "session/request_permission".to_owned(),
5304 params: None,
5305 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Operator },
5306 outcome: HostRequestOutcome::Executed,
5307 reason: None,
5308 },
5309 &[],
5310 );
5311 assert_eq!(
5312 operator_granted,
5313 Some(ProviderEvent::HostRequestObserved {
5314 method: "session/request_permission".to_owned(),
5315 params_json: String::new(),
5316 decision: ProviderHostRequestDecision::Granted {
5317 by: ProviderHostDecisionAuthority::Operator
5318 },
5319 outcome: ProviderHostRequestOutcome::Executed,
5320 reason: None,
5321 })
5322 );
5323
5324 let deadline_denied = super::provider_event(
5325 AgentEvent::RpcIncomingRequest {
5326 id: gate4agent::rpc::message::RpcId::Number(5),
5327 method: "session/request_permission".to_owned(),
5328 params: None,
5329 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::DeadlinePolicy },
5330 outcome: HostRequestOutcome::Executed,
5331 reason: None,
5332 },
5333 &[],
5334 );
5335 assert_eq!(
5336 deadline_denied,
5337 Some(ProviderEvent::HostRequestObserved {
5338 method: "session/request_permission".to_owned(),
5339 params_json: String::new(),
5340 decision: ProviderHostRequestDecision::Denied {
5341 by: ProviderHostDecisionAuthority::DeadlinePolicy
5342 },
5343 outcome: ProviderHostRequestOutcome::Executed,
5344 reason: None,
5345 })
5346 );
5347
5348 }
5354
5355 #[test]
5362 fn granted_host_request_execution_failure_carries_through_as_a_failed_outcome() {
5363 let spawn_error = "terminal/create spawn failed: os error 3";
5364 let mapped = super::provider_event(
5365 AgentEvent::RpcIncomingRequest {
5366 id: gate4agent::rpc::message::RpcId::Number(10),
5367 method: "terminal/create".to_owned(),
5368 params: None,
5369 decision: HostRequestDecision::Granted { by: HostDecisionAuthority::Policy },
5370 outcome: HostRequestOutcome::Failed { error: spawn_error.to_owned() },
5371 reason: None,
5372 },
5373 &[],
5374 );
5375 assert_eq!(
5376 mapped,
5377 Some(ProviderEvent::HostRequestObserved {
5378 method: "terminal/create".to_owned(),
5379 params_json: String::new(),
5380 decision: ProviderHostRequestDecision::Granted {
5381 by: ProviderHostDecisionAuthority::Policy
5382 },
5383 outcome: ProviderHostRequestOutcome::Failed { error: spawn_error.to_owned() },
5384 reason: None,
5385 })
5386 );
5387 mapped.expect("mapped").validate_ingress().expect("bounded free-text error validates");
5388 }
5389
5390 #[test]
5397 fn host_request_reason_carries_through_to_the_operator() {
5398 let gate_text =
5399 "blocked by dangerous-command gate: rule=filesystem-wipe, argument=rm -rf /";
5400 let denied = super::provider_event(
5401 AgentEvent::RpcIncomingRequest {
5402 id: gate4agent::rpc::message::RpcId::Number(9),
5403 method: "terminal/create".to_owned(),
5404 params: None,
5405 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Gate },
5406 outcome: HostRequestOutcome::Executed,
5407 reason: Some(gate_text.to_owned()),
5408 },
5409 &[],
5410 );
5411 assert_eq!(
5412 denied,
5413 Some(ProviderEvent::HostRequestObserved {
5414 method: "terminal/create".to_owned(),
5415 params_json: String::new(),
5416 decision: ProviderHostRequestDecision::Denied {
5417 by: ProviderHostDecisionAuthority::Gate
5418 },
5419 outcome: ProviderHostRequestOutcome::Executed,
5420 reason: Some(gate_text.to_owned()),
5421 })
5422 );
5423
5424 denied.expect("mapped").validate_ingress().expect("bounded free-text reason validates");
5429 }
5430
5431 #[test]
5432 fn deferred_acp_permission_request_becomes_an_interaction_with_its_id() {
5433 let with_title = super::provider_event(
5434 AgentEvent::RpcIncomingRequest {
5435 id: gate4agent::rpc::message::RpcId::Number(6),
5436 method: "session/request_permission".to_owned(),
5437 params: Some(serde_json::json!({
5438 "sessionId": "s1",
5439 "toolCall": {"toolCallId": "t1", "kind": "edit", "title": "Edit src/main.rs"},
5440 "options": [
5441 {"optionId": "allow", "name": "Allow", "kind": "allow_once"},
5442 {"optionId": "reject", "name": "Reject", "kind": "reject_once"},
5443 ],
5444 })),
5445 decision: HostRequestDecision::Deferred,
5446 outcome: HostRequestOutcome::Executed,
5447 reason: None,
5448 },
5449 &[],
5450 );
5451 assert_eq!(
5460 with_title,
5461 Some(ProviderEvent::InteractionRequested {
5462 request_id: Some("number:6".to_owned()),
5463 interaction_kind: ProviderInteractionKind::Approval,
5464 tool_name: "edit".to_owned(),
5465 title: Some("Edit src/main.rs".to_owned()),
5466 prompt: "Edit src/main.rs".to_owned(),
5467 options: vec![
5468 ProviderInteractionOption {
5469 option_id: "allow".to_owned(),
5470 name: "Allow".to_owned(),
5471 kind: "allow_once".to_owned(),
5472 },
5473 ProviderInteractionOption {
5474 option_id: "reject".to_owned(),
5475 name: "Reject".to_owned(),
5476 kind: "reject_once".to_owned(),
5477 },
5478 ],
5479 agent_id: None,
5480 })
5481 );
5482
5483 let without_title = super::provider_event(
5489 AgentEvent::RpcIncomingRequest {
5490 id: gate4agent::rpc::message::RpcId::String("agent-7".to_owned()),
5491 method: "session/request_permission".to_owned(),
5492 params: None,
5493 decision: HostRequestDecision::Deferred,
5494 outcome: HostRequestOutcome::Executed,
5495 reason: None,
5496 },
5497 &[],
5498 );
5499 assert_eq!(
5500 without_title,
5501 Some(ProviderEvent::InteractionRequested {
5502 request_id: Some("string:agent-7".to_owned()),
5503 interaction_kind: ProviderInteractionKind::Approval,
5504 tool_name: "session/request_permission".to_owned(),
5505 title: None,
5506 prompt: String::new(),
5507 options: Vec::new(),
5508 agent_id: None,
5509 })
5510 );
5511
5512 let resolved = super::provider_event(
5516 AgentEvent::RpcIncomingRequest {
5517 id: gate4agent::rpc::message::RpcId::Number(6),
5518 method: "session/request_permission".to_owned(),
5519 params: None,
5520 decision: HostRequestDecision::Denied { by: HostDecisionAuthority::Operator },
5521 outcome: HostRequestOutcome::Executed,
5522 reason: None,
5523 },
5524 &[],
5525 );
5526 assert_eq!(
5527 resolved,
5528 Some(ProviderEvent::HostRequestObserved {
5529 method: "session/request_permission".to_owned(),
5530 params_json: String::new(),
5531 decision: ProviderHostRequestDecision::Denied {
5532 by: ProviderHostDecisionAuthority::Operator
5533 },
5534 outcome: ProviderHostRequestOutcome::Executed,
5535 reason: None,
5536 })
5537 );
5538 }
5539
5540 #[test]
5541 fn unrecognized_notification_reaches_the_operator_as_a_raw_event_instead_of_vanishing() {
5542 let mapped = super::provider_event(
5543 AgentEvent::RpcNotification {
5544 method: "session/update".to_owned(),
5545 params: Default::default(),
5546 },
5547 &[],
5548 );
5549 assert_eq!(
5550 mapped,
5551 Some(ProviderEvent::UnrecognizedNotification {
5552 method: "session/update".to_owned(),
5553 payload_json: "null".to_owned(),
5554 })
5555 );
5556 }
5557
5558 #[test]
5559 fn pty_terminal_capability_defaults_never_override_a_caller_supplied_term() {
5560 let caller_supplied = vec![EnvMutation {
5561 key: OsString::from("TERM"),
5562 value: Some(OsString::from("dumb")),
5563 }];
5564 let filled = with_pty_terminal_capability_defaults(caller_supplied);
5565
5566 let term_values: Vec<_> = filled
5567 .iter()
5568 .filter(|mutation| mutation.key.as_os_str() == OsStr::new("TERM"))
5569 .collect();
5570 assert_eq!(term_values.len(), 1, "TERM must not be duplicated");
5571 assert_eq!(term_values[0].value.as_deref(), Some(OsStr::new("dumb")));
5572
5573 let colorterm = filled
5574 .iter()
5575 .find(|mutation| mutation.key.as_os_str() == OsStr::new("COLORTERM"))
5576 .expect("COLORTERM default is filled in when the caller left it unset");
5577 assert_eq!(colorterm.value.as_deref(), Some(OsStr::new("truecolor")));
5578 }
5579
5580 #[test]
5586 fn mcp_server_acp_entry_translates_a_spec_into_one_stdio_entry() {
5587 let spec = McpServerSpec::new(
5588 "test-mcp-server",
5589 OsString::from("C:\\example\\example-mcp-server.exe"),
5590 vec![OsString::from("--session-proxy")],
5591 vec![
5592 (
5593 OsString::from("TEST_MCP_SESSION_ENDPOINT"),
5594 OsString::from("\\\\.\\pipe\\example-mcp-server-s1"),
5595 ),
5596 (
5597 OsString::from("TEST_MCP_SESSION_TOKEN"),
5598 OsString::from("tok-abc"),
5599 ),
5600 ],
5601 )
5602 .unwrap();
5603
5604 let server = mcp_server_acp_entry(&spec);
5605 match server {
5606 McpServerConfig::Stdio { name, command, args, env } => {
5607 assert_eq!(name, "test-mcp-server", "ACP v1 requires a name; the adapter registers by it");
5608 assert_eq!(command, "C:\\example\\example-mcp-server.exe");
5609 assert_eq!(args, vec!["--session-proxy".to_string()]);
5610 assert_eq!(env.len(), 2, "exactly the entries the spec was given, nothing else");
5611 assert_eq!(
5612 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_ENDPOINT").map(|pair| pair.value.as_str()),
5613 Some("\\\\.\\pipe\\example-mcp-server-s1")
5614 );
5615 assert_eq!(
5616 env.iter().find(|pair| pair.name == "TEST_MCP_SESSION_TOKEN").map(|pair| pair.value.as_str()),
5617 Some("tok-abc")
5618 );
5619 }
5620 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5621 }
5622 }
5623
5624 #[test]
5625 fn mcp_server_acp_entry_carries_zero_env_pairs_when_the_spec_carries_none() {
5626 let spec = McpServerSpec::new(
5627 "test-mcp-server",
5628 OsString::from("C:\\example\\example-mcp-server.exe"),
5629 vec![OsString::from("--session-proxy")],
5630 Vec::new(),
5631 )
5632 .unwrap();
5633
5634 let server = mcp_server_acp_entry(&spec);
5635 match server {
5636 McpServerConfig::Stdio { env, .. } => assert!(env.is_empty()),
5637 McpServerConfig::Sse { .. } => panic!("expected Stdio variant"),
5638 }
5639 }
5640
5641 #[test]
5642 fn credential_shape_rule_matches_prefixed_hex64_not_bare_digest_or_uuid() {
5643 let hex64 = "a1b2c3d4e5f6".repeat(5) + "a1b2";
5644 assert_eq!(hex64.len(), 64);
5645
5646 let prefixed_token = format!("g4aho_{hex64}");
5647 assert!(
5648 argument_looks_like_credential(&prefixed_token),
5649 "a short lowercase prefix plus '_' plus 64 lowercase hex chars is a credential"
5650 );
5651
5652 assert!(
5653 !argument_looks_like_credential(&hex64),
5654 "a bare 64-hex digest with no prefix is a legitimate diagnostic, not a credential"
5655 );
5656
5657 assert!(
5658 !argument_looks_like_credential("550e8400-e29b-41d4-a716-446655440000"),
5659 "a UUID must not be mistaken for a prefixed-hex64 credential"
5660 );
5661 }
5662
5663 #[test]
5664 fn native_instance_launch_arguments_fail_closed_before_shell_spawn() {
5665 let claude = AgentId::new("claude").unwrap();
5666 assert_eq!(
5667 validate_instance_launch_arguments(
5668 &claude,
5669 TransportKind::Pipe,
5670 &[OsString::from("--bundle-mode")],
5671 )
5672 .unwrap_err(),
5673 "native instance launch arguments require PTY transport (or Codex -c overlays on ACP)"
5674 );
5675 assert_eq!(
5676 validate_instance_launch_arguments(
5677 &claude,
5678 TransportKind::Pty,
5679 &[OsString::from("--resume=session-secret")],
5680 )
5681 .unwrap_err(),
5682 "native instance launch arguments conflict with Claude session, resume, or prompt authority"
5683 );
5684 assert!(validate_instance_launch_arguments(
5685 &claude,
5686 TransportKind::Pty,
5687 &[
5688 OsString::from("--permission-mode"),
5689 OsString::from("default"),
5690 ],
5691 )
5692 .is_ok());
5693 }
5694
5695 fn kind_of(contents: &str) -> Option<OperatorGateKind> {
5699 startup_operator_gate(contents).map(|gate| gate.kind)
5700 }
5701
5702 #[test]
5703 fn startup_operator_gates_are_classified_without_returning_terminal_text() {
5704 assert_eq!(kind_of(" Trust this\nfolder? "), Some(OperatorGateKind::WorkspaceTrust));
5705 assert_eq!(
5706 kind_of("No auth type is selected"),
5707 Some(OperatorGateKind::Authentication)
5708 );
5709 assert_eq!(
5710 kind_of("Sign in with OpenAI to use Codex"),
5711 Some(OperatorGateKind::Authentication)
5712 );
5713 assert_eq!(
5719 kind_of(
5720 "Claude Code can be used with your Claude subscription or billed based on \
5721 API usage through your Console account.\n\
5722 Select login method:\n\
5723 \u{276f} 1. Claude ...\n\
5724 2. API usage billing\n\
5725 3. 3rd-party platform \u{b7} Amazon Bedrock ..."
5726 ),
5727 Some(OperatorGateKind::Authentication)
5728 );
5729 assert_eq!(
5730 kind_of(
5731 "Browser didn't open? Use the url below to sign in (c to copy)\n\
5732 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
5733 Paste code here"
5734 ),
5735 Some(OperatorGateKind::Authentication)
5736 );
5737 assert_eq!(
5742 kind_of(
5743 "Once you sign in, copy the generated token and paste it into your .env file; \
5744 no code entry happens on this screen."
5745 ),
5746 None
5747 );
5748 assert_eq!(
5749 kind_of("Kimi Code Update Available\nInstall update now (0.32.0)\nEnter confirm"),
5750 Some(OperatorGateKind::VendorUpdate)
5751 );
5752 assert_eq!(
5753 kind_of(
5754 "Welcome to Claude Code\nChoose the text style that looks best with your terminal"
5755 ),
5756 Some(OperatorGateKind::TerminalAppearance)
5757 );
5758 assert_eq!(
5759 kind_of(
5760 "Welcome to Claude Code for VS Code\nClaude has context of open files and selected lines"
5761 ),
5762 Some(OperatorGateKind::Onboarding)
5763 );
5764 assert_eq!(
5765 kind_of("Welcome to Claude Code\n❯ Press Enter to continue"),
5766 Some(OperatorGateKind::Onboarding)
5767 );
5768 assert_eq!(kind_of("Welcome to Claude Code\n❯ ready\nEnter to send"), None);
5769 assert_eq!(
5770 kind_of(
5771 "Quick safety check: Is this a project you trust?\nYes, I trust this folder\nNo, continue without these permissions"
5772 ),
5773 Some(OperatorGateKind::WorkspaceTrust)
5774 );
5775 assert_eq!(kind_of("ready for a prompt"), None);
5776 assert_eq!(
5781 kind_of(
5782 "Updating Codex via `npm install -g @openai/codex`...\n\
5783 npm warn cleanup Failed to remove some directories\n\
5784 Update ran successfully! Please restart Codex."
5785 ),
5786 Some(OperatorGateKind::VendorUpdate)
5787 );
5788 assert_eq!(
5798 kind_of(
5799 " Hooks need review\n\
5800 6 hooks are new or changed.\n\
5801 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5802 2. Trust all and continue\n\
5803 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5804 ),
5805 Some(OperatorGateKind::HookTrust)
5806 );
5807 assert_eq!(
5810 kind_of(
5811 " Hooks need review\n\
5812 42 hooks are new or changed.\n\
5813 Hooks can run outside the sandbox after you trust them.\u{203a} 1. Review hooks\n\
5814 2. Trust all and continue\n\
5815 3. Continue without trusting (hooks won't run) Press enter to confirm or esc to go back"
5816 ),
5817 Some(OperatorGateKind::HookTrust)
5818 );
5819 assert_eq!(
5823 kind_of(
5824 "I reviewed the pre-commit hooks in this repo and they look safe to trust; \
5825 I'll leave the hooks config as-is and continue with the refactor."
5826 ),
5827 None
5828 );
5829 }
5830
5831 #[test]
5838 fn startup_operator_gate_parses_a_numbered_hook_trust_option_list() {
5839 let contents = "Hooks need review\n\
5840 \u{203a} 1. Review hooks\n \
5841 2. Trust all and continue\n \
5842 3. Continue without trusting (hooks won't run)\n\
5843 Press enter to confirm or esc to go back";
5844 let gate = startup_operator_gate(contents).expect("hook trust must classify");
5845 assert_eq!(gate.kind, OperatorGateKind::HookTrust);
5846 assert_eq!(gate.input, OperatorGateInput::NumberedList);
5847 assert_eq!(
5848 gate.options,
5849 vec![
5850 gate4agent_types::OperatorGateOption {
5851 text: "Review hooks".to_owned(),
5852 semantics: OperatorGateOptionSemantics::Inspect,
5853 selected: true,
5854 },
5855 gate4agent_types::OperatorGateOption {
5856 text: "Trust all and continue".to_owned(),
5857 semantics: OperatorGateOptionSemantics::Accept,
5858 selected: false,
5859 },
5860 gate4agent_types::OperatorGateOption {
5861 text: "Continue without trusting (hooks won't run)".to_owned(),
5862 semantics: OperatorGateOptionSemantics::Decline,
5863 selected: false,
5864 },
5865 ],
5866 );
5867 }
5868
5869 #[test]
5876 fn startup_operator_gate_parses_an_arrow_workspace_trust_option_list() {
5877 let contents = "Do you trust the files in this folder?\n \
5878 Trust this folder\n \
5879 Enable project MCP servers. Remembered for this folder.\n\u{276f} \
5880 Don't trust\n \
5881 Exit Kimi Code. Asked again next launch.\n \
5882 \u{2191}\u{2193} navigate \u{b7} Enter select \u{b7} Esc exit";
5883 let gate = startup_operator_gate(contents).expect("workspace trust must classify");
5884 assert_eq!(gate.kind, OperatorGateKind::WorkspaceTrust);
5885 assert_eq!(gate.input, OperatorGateInput::ArrowList);
5886 assert_eq!(
5887 gate.options,
5888 vec![
5889 gate4agent_types::OperatorGateOption {
5890 text: "Trust this folder".to_owned(),
5891 semantics: OperatorGateOptionSemantics::Accept,
5892 selected: false,
5893 },
5894 gate4agent_types::OperatorGateOption {
5895 text: "Don't trust".to_owned(),
5896 semantics: OperatorGateOptionSemantics::Decline,
5897 selected: true,
5898 },
5899 ],
5900 );
5901 }
5902
5903 #[test]
5907 fn startup_operator_gate_without_a_recognized_option_list_reports_unknown_input() {
5908 let gate = startup_operator_gate("No auth type is selected")
5909 .expect("authentication must classify");
5910 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5911 assert_eq!(gate.input, OperatorGateInput::Unknown);
5912 assert!(gate.options.is_empty());
5913 }
5914
5915 #[test]
5924 fn startup_operator_gate_parses_claudes_login_method_chooser_including_its_cursor_row() {
5925 let contents = "Select login method:\n\
5926 \u{276f} 1. Claude ...\n\
5927 2. API usage billing\n\
5928 3. 3rd-party platform \u{b7} Amazon Bedrock ...";
5929 let gate = startup_operator_gate(contents).expect("authentication must classify");
5930 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5931 assert_eq!(gate.subject, OperatorGateSubject::Account);
5932 assert_eq!(gate.input, OperatorGateInput::NumberedList);
5933 assert_eq!(
5934 gate.options,
5935 vec![
5936 gate4agent_types::OperatorGateOption {
5937 text: "Claude ...".to_owned(),
5938 semantics: OperatorGateOptionSemantics::Unknown,
5939 selected: true,
5940 },
5941 gate4agent_types::OperatorGateOption {
5942 text: "API usage billing".to_owned(),
5943 semantics: OperatorGateOptionSemantics::Unknown,
5944 selected: false,
5945 },
5946 gate4agent_types::OperatorGateOption {
5947 text: "3rd-party platform \u{b7} Amazon Bedrock ...".to_owned(),
5948 semantics: OperatorGateOptionSemantics::Unknown,
5949 selected: false,
5950 },
5951 ],
5952 );
5953 }
5954
5955 #[test]
5960 fn startup_operator_gate_oauth_wait_screen_reports_text_entry_input() {
5961 let contents = "Browser didn't open? Use the url below to sign in (c to copy)\n\
5962 https://claude.com/oauth/authorize?client_id=abc&redirect_uri=https%3A%2F%2Fconsole.anthropic.com&code_challenge=xyz\n\
5963 Paste code here";
5964 let gate = startup_operator_gate(contents).expect("oauth wait screen must classify");
5965 assert_eq!(gate.kind, OperatorGateKind::Authentication);
5966 assert_eq!(gate.subject, OperatorGateSubject::Account);
5967 assert_eq!(gate.input, OperatorGateInput::TextEntry);
5968 assert!(gate.options.is_empty());
5969 }
5970
5971 #[test]
5977 fn parse_operator_gate_options_recognizes_numbered_and_arrow_shapes_and_nothing_else() {
5978 assert_eq!(
5979 parse_operator_gate_options("Press enter to confirm or esc to go back"),
5980 (OperatorGateInput::Unknown, Vec::new()),
5981 );
5982 let (input, options) = parse_operator_gate_options(
5983 "\u{203a} 1. Review hooks\n 2. Trust all and continue",
5984 );
5985 assert_eq!(input, OperatorGateInput::NumberedList);
5986 assert_eq!(options.len(), 2);
5987 let (input, options) = parse_operator_gate_options(
5988 " Trust this folder\n Enable project MCP servers. Remembered for this folder.\n\u{276f} Don't trust",
5989 );
5990 assert_eq!(input, OperatorGateInput::ArrowList);
5991 assert_eq!(options.len(), 2);
5992 }
5993
5994 #[test]
5995 fn classify_operator_gate_option_semantics_reads_the_verb_not_the_position() {
5996 assert_eq!(
5997 classify_operator_gate_option_semantics("Review hooks"),
5998 OperatorGateOptionSemantics::Inspect,
5999 );
6000 assert_eq!(
6001 classify_operator_gate_option_semantics("Trust all and continue"),
6002 OperatorGateOptionSemantics::Accept,
6003 );
6004 assert_eq!(
6005 classify_operator_gate_option_semantics("Continue without trusting (hooks won't run)"),
6006 OperatorGateOptionSemantics::Decline,
6007 );
6008 assert_eq!(
6009 classify_operator_gate_option_semantics("Don't trust"),
6010 OperatorGateOptionSemantics::Decline,
6011 );
6012 assert_eq!(
6013 classify_operator_gate_option_semantics("Exit Kimi Code"),
6014 OperatorGateOptionSemantics::Exit,
6015 );
6016 assert_eq!(
6017 classify_operator_gate_option_semantics("Something unrecognized"),
6018 OperatorGateOptionSemantics::Unknown,
6019 );
6020 }
6021
6022 #[test]
6023 fn screen_failure_recognizes_crash_and_missing_command_banners() {
6024 assert_eq!(
6025 screen_failure("thread 'main' panicked at 'index out of bounds', src/main.rs:12:5"),
6026 Some("crash")
6027 );
6028 assert_eq!(
6029 screen_failure("Traceback (most recent call last):\n File \"a.py\", line 1"),
6030 Some("crash")
6031 );
6032 assert_eq!(
6033 screen_failure("bash: fooagent: command not found"),
6034 Some("missing command")
6035 );
6036 assert_eq!(
6037 screen_failure("C:\\workspace> fooagent\n'fooagent' is not recognized as an internal or external command"),
6038 Some("missing command")
6039 );
6040 assert_eq!(
6041 screen_failure(
6042 "workspace/project $ fooagent: no such file or directory\nworkspace/project $"
6043 ),
6044 Some("missing command")
6045 );
6046 assert_eq!(
6049 screen_failure("The build log mentions no such file or directory near line 40."),
6050 None
6051 );
6052 assert_eq!(
6056 screen_failure("fooagent-installer: fatal error: missing header <stdio.h>"),
6057 None
6058 );
6059 }
6060
6061 #[test]
6062 fn screen_failure_recognizes_grok_missing_api_key_banner() {
6063 assert_eq!(
6068 screen_failure(
6069 "\u{274c} Error: API key required. Set GROK_API_KEY environment variable, \
6070 use --api-key flag, or set \"apiKey\" field in ~/.grok/user-settings.json"
6071 ),
6072 Some("missing api key")
6073 );
6074 assert_eq!(
6078 screen_failure(
6079 "You'll need an API key for this provider before it works; check the docs \
6080 for how to configure one."
6081 ),
6082 None
6083 );
6084 }
6085
6086 #[test]
6087 fn screen_failure_no_longer_has_an_authentication_expired_bucket() {
6088 assert_eq!(
6093 screen_failure("Your session token has expired. Please re-authenticate."),
6094 None
6095 );
6096 assert_eq!(
6097 screen_failure("The stored credential was revoked by the workspace admin."),
6098 None
6099 );
6100 }
6101
6102 #[test]
6103 fn screen_failure_does_not_false_positive_on_an_agent_narrating_an_error() {
6104 let narration = "I looked at the traceback you pasted -- it's a Python \
6109 exception, a plain ValueError from a retry loop, not a real crash. \
6110 Our harness logs the word fatal in its own banner for visibility, \
6111 but nothing actually panicked. The command definitely exists; it \
6112 just needed different flags, and your token is still valid.";
6113 assert_eq!(screen_failure(narration), None);
6114 }
6115
6116 #[test]
6117 fn screen_failure_for_generation_ignores_every_marker_once_the_session_was_ever_ready() {
6118 let shell_command_not_found = "$ frobnicate --help\nbash: frobnicate: command not found\n$";
6123 assert_eq!(
6124 screen_failure_for_generation(shell_command_not_found, true),
6125 None
6126 );
6127
6128 let python_traceback_from_a_ran_script = "$ python broken.py\n\
6129 Traceback (most recent call last):\n File \"broken.py\", line 3, in <module>\n\
6130 ValueError: bad input\n$";
6131 assert_eq!(
6132 screen_failure_for_generation(python_traceback_from_a_ran_script, true),
6133 None
6134 );
6135
6136 let cargo_test_panic = "running 1 test\n\
6137 error[E0308]: mismatched types\n\
6138 thread 'tests::it_fails' panicked at 'assertion failed', src/lib.rs:9:5\n\
6139 test result: FAILED. 0 passed; 1 failed";
6140 assert_eq!(screen_failure_for_generation(cargo_test_panic, true), None);
6141
6142 let agent_narrating_an_expired_token = "The API token has expired; \
6143 I revoked the old credential and issued a new one for you.";
6144 assert_eq!(
6145 screen_failure_for_generation(agent_narrating_an_expired_token, true),
6146 None
6147 );
6148
6149 assert_eq!(
6154 screen_failure_for_generation(shell_command_not_found, false),
6155 Some("missing command")
6156 );
6157 assert_eq!(
6158 screen_failure_for_generation(python_traceback_from_a_ran_script, false),
6159 Some("crash")
6160 );
6161 assert_eq!(screen_failure_for_generation(cargo_test_panic, false), Some("crash"));
6162 }
6163
6164 #[test]
6165 fn classify_pty_screen_state_lets_a_foreign_process_win_over_a_matching_gate_text() {
6166 let foreign = ForegroundVerdict::Foreign {
6171 process: "npm".to_owned(),
6172 };
6173 assert_eq!(
6174 classify_pty_screen_state(Some(&foreign), None, None),
6175 PtyScreenState::NotAgent {
6176 observed_process: "npm".to_owned()
6177 }
6178 );
6179 let vendor_update_gate = OperatorGateState::new(OperatorGateKind::VendorUpdate);
6180 assert_eq!(
6181 classify_pty_screen_state(Some(&foreign), Some(&vendor_update_gate), None),
6182 PtyScreenState::NotAgent {
6183 observed_process: "npm".to_owned()
6184 }
6185 );
6186 }
6187
6188 #[test]
6189 fn classify_pty_screen_state_reports_a_gate_only_when_foreground_matches() {
6190 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6191 assert_eq!(
6192 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), Some(&authentication_gate), None),
6193 PtyScreenState::OperatorGate {
6194 gate: authentication_gate.clone()
6195 }
6196 );
6197 }
6198
6199 #[test]
6200 fn classify_pty_screen_state_reports_failing_for_a_matched_foreground() {
6201 assert_eq!(
6202 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, Some("crash")),
6203 PtyScreenState::Failing {
6204 reason: "crash".to_owned()
6205 }
6206 );
6207 }
6208
6209 #[test]
6210 fn classify_pty_screen_state_prefers_failing_over_a_co_occurring_gate() {
6211 let authentication_gate = OperatorGateState::new(OperatorGateKind::Authentication);
6215 assert_eq!(
6216 classify_pty_screen_state(
6217 Some(&ForegroundVerdict::Agent),
6218 Some(&authentication_gate),
6219 Some("crash")
6220 ),
6221 PtyScreenState::Failing {
6222 reason: "crash".to_owned()
6223 }
6224 );
6225 }
6226
6227 #[test]
6228 fn classify_pty_screen_state_reaches_ready_only_with_matched_foreground_and_clean_text() {
6229 assert_eq!(
6230 classify_pty_screen_state(Some(&ForegroundVerdict::Agent), None, None),
6231 PtyScreenState::Ready
6232 );
6233 }
6234
6235 #[test]
6236 fn classify_pty_screen_state_never_reaches_ready_without_a_foreground_observation() {
6237 assert_eq!(classify_pty_screen_state(None, None, None), PtyScreenState::Unknown);
6240 }
6241
6242 #[test]
6243 fn resolve_foreground_verdict_tolerates_a_spawning_wrapper_like_readiness_does() {
6244 let spec = gate4agent_testkit::interactive_agent_spec();
6252 let observation = PtyForegroundObservation {
6253 root_pid: 1,
6254 observed_pid: 2,
6255 observed_process: "node".to_owned(),
6256 readiness: ForegroundObservation {
6257 process_name: Some("node".to_owned()),
6258 has_child_processes: true,
6259 is_shell: false,
6260 },
6261 source: PtyForegroundSource::ProcessTree,
6262 };
6263 let verdict = resolve_foreground_verdict(&spec, &observation, RuntimePlatform::current());
6264 assert_eq!(verdict, ForegroundVerdict::Agent);
6265 assert_eq!(
6266 classify_pty_screen_state(Some(&verdict), None, None),
6267 PtyScreenState::Ready
6268 );
6269 }
6270
6271 #[test]
6272 fn foreground_probe_disarms_only_once_ready_and_rearms_on_a_fresh_gate() {
6273 assert_eq!(
6274 foreground_probe_schedule(&PtyScreenState::Ready),
6275 ForegroundProbeSchedule::Disarmed
6276 );
6277 assert_eq!(
6278 foreground_probe_schedule(&PtyScreenState::Unknown),
6279 ForegroundProbeSchedule::Armed
6280 );
6281 assert_eq!(
6282 foreground_probe_schedule(&PtyScreenState::OperatorGate {
6283 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate)
6284 }),
6285 ForegroundProbeSchedule::Armed
6286 );
6287 }
6288
6289 #[test]
6290 fn text_only_gate_transition_rearms_the_probe_only_when_leaving_ready() {
6291 let gate = PtyScreenState::OperatorGate {
6292 gate: OperatorGateState::new(OperatorGateKind::VendorUpdate),
6293 };
6294 assert!(foreground_probe_rearms_immediately(
6295 &PtyScreenState::Ready,
6296 &gate
6297 ));
6298 assert!(!foreground_probe_rearms_immediately(
6301 &PtyScreenState::Unknown,
6302 &gate
6303 ));
6304 }
6305
6306 #[test]
6307 fn readiness_diagnostics_detects_an_ansi_split_gate_without_exposing_text() {
6308 let mut diagnostics = ReadinessDiagnostics::default();
6309 diagnostics.observe_output(b"\x1b[31mNo auth ");
6310 diagnostics.observe_output(b"\x1b[0mtype is selected");
6311 assert_eq!(
6312 diagnostics.operator_gate.as_ref().map(|gate| gate.kind),
6313 Some(OperatorGateKind::Authentication)
6314 );
6315 assert!(!diagnostics.summary().contains("No auth"));
6316 }
6317
6318 #[test]
6319 fn semantic_utf8_decoder_preserves_codepoints_split_across_pty_reads() {
6320 let mut decoder = Utf8ChunkDecoder::default();
6321 let bytes = "ready Привет".as_bytes();
6322 let split = bytes
6323 .windows(2)
6324 .position(|window| window[0] >= 0x80 && window[1] >= 0x80)
6325 .expect("Cyrillic text contains adjacent UTF-8 bytes")
6326 + 1;
6327 let first = decoder.push(&bytes[..split]);
6328 let second = decoder.push(&bytes[split..]);
6329 assert_eq!(format!("{first}{second}"), "ready Привет");
6330 assert!(!first.contains('\u{fffd}'));
6331 assert!(!second.contains('\u{fffd}'));
6332 }
6333
6334 #[test]
6335 fn semantic_utf8_decoder_replaces_invalid_bytes_without_stalling() {
6336 let mut decoder = Utf8ChunkDecoder::default();
6337 assert_eq!(decoder.push(b"ok\xfftail"), "ok\u{fffd}tail");
6338 assert_eq!(decoder.push(" Привет".as_bytes()), " Привет");
6339 }
6340
6341 #[test]
6342 fn fresh_claude_pty_preassigns_the_exact_vendor_session_id_argv() {
6343 let claude = builtin_adapter_registry()
6344 .binding(AdapterFamily::PtySemantic, "claude-code")
6345 .expect("Claude PTY binding");
6346 let mut args = Vec::new();
6347 let identity = prepare_fresh_pty_provider_session(Some(claude), false, true, &mut args)
6348 .expect("fresh Claude provider identity");
6349 let parsed = uuid::Uuid::parse_str(&identity.id).expect("valid Claude UUID");
6350 assert_eq!(parsed.get_version_num(), 4);
6351 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
6352 assert!(identity.transcript_path.is_none());
6353 assert_eq!(args, [OsString::from("--session-id"), OsString::from(identity.id)]);
6354 }
6355
6356 #[test]
6357 fn fresh_codex_and_resumed_claude_do_not_preassign_a_second_identity() {
6358 let adapters = builtin_adapter_registry();
6359 let codex = adapters
6360 .binding(AdapterFamily::PtySemantic, "codex")
6361 .expect("Codex PTY binding");
6362 let claude = adapters
6363 .binding(AdapterFamily::PtySemantic, "claude-code")
6364 .expect("Claude PTY binding");
6365 let mut codex_args = Vec::new();
6366 assert!(prepare_fresh_pty_provider_session(Some(codex), false, true, &mut codex_args)
6367 .is_none());
6368 assert!(codex_args.is_empty());
6369
6370 let mut resume_args = vec![OsString::from("--resume"), OsString::from("vendor-id")];
6371 assert!(prepare_fresh_pty_provider_session(Some(claude), true, true, &mut resume_args)
6372 .is_none());
6373 assert_eq!(
6374 resume_args,
6375 [OsString::from("--resume"), OsString::from("vendor-id")]
6376 );
6377 }
6378
6379 #[test]
6380 fn raw_pty_policy_omits_all_identity_and_semantic_startup_paths() {
6381 let adapters = builtin_adapter_registry();
6382 let claude = adapters
6383 .binding(AdapterFamily::PtySemantic, "claude-code")
6384 .expect("Claude PTY binding");
6385 let codex = adapters
6386 .binding(AdapterFamily::PtySemantic, "codex")
6387 .expect("Codex PTY binding");
6388 let kimi = adapters
6389 .binding(AdapterFamily::PtySemantic, "kimi")
6390 .expect("Kimi PTY binding");
6391 let policy = ProviderRuntimePolicy::raw_pty();
6392 let mut args = Vec::new();
6393
6394 assert!(prepare_fresh_pty_provider_session(Some(claude), false, false, &mut args)
6395 .is_none());
6396 assert!(args.is_empty());
6397 assert!(!should_probe_pty_identity(policy, Some(codex), false, "codex"));
6398 assert!(!should_probe_pty_identity(policy, Some(kimi), false, "kimi"));
6399 assert!(!should_attach_pty_provider_stream(policy));
6400 }
6401
6402 #[test]
6403 fn identity_probe_requires_structured_prompt_for_codex_and_kimi() {
6404 let adapters = builtin_adapter_registry();
6405 let codex = adapters
6406 .binding(AdapterFamily::PtySemantic, "codex")
6407 .expect("Codex PTY binding");
6408 let kimi = adapters
6409 .binding(AdapterFamily::PtySemantic, "kimi")
6410 .expect("Kimi PTY binding");
6411 let without_structured_prompt =
6412 ProviderRuntimePolicy::new(true, true, false, true, false, false)
6413 .expect("identity observation policy without structured prompt");
6414
6415 assert!(!should_probe_pty_identity(
6416 without_structured_prompt,
6417 Some(codex),
6418 false,
6419 "codex",
6420 ));
6421 assert!(!should_probe_pty_identity(
6422 without_structured_prompt,
6423 Some(kimi),
6424 false,
6425 "kimi",
6426 ));
6427
6428 let with_structured_prompt =
6429 ProviderRuntimePolicy::new(true, true, true, true, false, false)
6430 .expect("identity probe policy");
6431 assert!(should_probe_pty_identity(
6432 with_structured_prompt,
6433 Some(codex),
6434 false,
6435 "codex",
6436 ));
6437 assert!(should_probe_pty_identity(
6438 with_structured_prompt,
6439 Some(kimi),
6440 false,
6441 "kimi",
6442 ));
6443 }
6444
6445 #[test]
6446 fn runtime_policy_admits_raw_native_resume_but_denies_unverified_prompt_injection() {
6447 let raw = ProviderRuntimePolicy::raw_pty();
6448 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, false).is_ok());
6449 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, false)
6450 .unwrap_err()
6451 .contains("SemanticReadiness"));
6452 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, false, true).is_ok());
6453 assert!(validate_spawn_runtime_policy(raw, TransportKind::Pty, true, true)
6454 .unwrap_err()
6455 .contains("SemanticReadiness"));
6456
6457 let resume_without_prompt =
6458 ProviderRuntimePolicy::new(true, false, false, true, true, false)
6459 .expect("identity and resume policy");
6460 assert!(validate_spawn_runtime_policy(
6461 resume_without_prompt,
6462 TransportKind::Pty,
6463 false,
6464 true,
6465 )
6466 .is_ok());
6467 assert!(validate_spawn_runtime_policy(
6468 resume_without_prompt,
6469 TransportKind::Pty,
6470 true,
6471 true,
6472 )
6473 .unwrap_err()
6474 .contains("SemanticReadiness"));
6475 }
6476
6477 #[test]
6478 fn acp_transport_bypasses_the_pty_semantic_policy_gate_pty_and_pipe_still_enforce_it() {
6479 let no_pty_capabilities_at_all = ProviderRuntimePolicy::new(
6485 false, false, false, false, false, false,
6486 )
6487 .expect("an all-false policy is internally valid");
6488 assert!(validate_spawn_runtime_policy(
6489 no_pty_capabilities_at_all,
6490 TransportKind::Acp,
6491 false,
6492 false,
6493 )
6494 .is_ok());
6495 assert!(validate_spawn_runtime_policy(
6499 no_pty_capabilities_at_all,
6500 TransportKind::Pty,
6501 false,
6502 false,
6503 )
6504 .unwrap_err()
6505 .contains("RawPtyLifecycle"));
6506 assert!(validate_spawn_runtime_policy(
6507 no_pty_capabilities_at_all,
6508 TransportKind::Pipe,
6509 false,
6510 false,
6511 )
6512 .unwrap_err()
6513 .contains("RawPtyLifecycle"));
6514 }
6515
6516 #[test]
6517 fn prompt_render_probe_ignores_terminal_wrapping_and_uses_the_tail() {
6518 let prompt = "prefix with spaces\nand punctuation: final-render-token-1234567890";
6519 let probe = prompt_render_probe(prompt);
6520 assert!("screen prefix with spaces and punctuation final render token 1234567890"
6521 .chars()
6522 .filter(|character| character.is_alphanumeric())
6523 .flat_map(char::to_lowercase)
6524 .collect::<String>()
6525 .contains(&probe));
6526 assert!(probe.chars().count() <= 32);
6527 }
6528
6529 #[test]
6530 fn prompt_render_requires_new_sequence_and_visible_tail_evidence() {
6531 let probe = prompt_render_probe("final render token");
6532 let baseline = snapshot(7, "old composer");
6533 assert!(!prompt_rendered(
6534 &snapshot(7, "final\nrender\ntoken"),
6535 &baseline,
6536 &probe
6537 ));
6538 assert!(!prompt_rendered(
6539 &snapshot(8, "unrelated redraw"),
6540 &baseline,
6541 &probe
6542 ));
6543 assert!(prompt_rendered(
6544 &snapshot(8, "composer\nfinal\nrender\ntoken"),
6545 &baseline,
6546 &probe
6547 ));
6548 assert!(prompt_rendered(
6549 &snapshot(8, "composer [Pasted Content 4096 chars]"),
6550 &baseline,
6551 &probe
6552 ));
6553 assert!(prompt_rendered(
6554 &snapshot(8, "composer [Pasted text #1 +6 lines]"),
6555 &baseline,
6556 &probe
6557 ));
6558 }
6559
6560 #[test]
6561 fn an_existing_paste_placeholder_cannot_pass_on_an_unrelated_redraw() {
6562 let probe = prompt_render_probe("a new long prompt");
6563 assert!(!prompt_rendered(
6564 &snapshot(8, "composer [Pasted Content 4096 chars]\nunrelated redraw"),
6565 &snapshot(7, "composer [Pasted Content 4096 chars]"),
6566 &probe
6567 ));
6568 assert!(!prompt_rendered(
6569 &snapshot(8, "composer [Pasted text #1 +6 lines]\nunrelated redraw"),
6570 &snapshot(7, "composer [Pasted text #1 +6 lines]"),
6571 &probe
6572 ));
6573 }
6574
6575 #[test]
6576 fn punctuation_only_prompt_cannot_pass_on_an_unrelated_redraw() {
6577 let probe = prompt_render_probe("!?---");
6578 assert!(probe.is_empty());
6579 assert!(!prompt_rendered(
6580 &snapshot(2, "unrelated redraw"),
6581 &snapshot(1, "old composer"),
6582 &probe
6583 ));
6584 }
6585
6586 #[test]
6587 fn prompt_probe_matches_the_sanitized_terminal_payload() {
6588 let prompt = "payload\u{1b}tail";
6589 let sanitized = gate4agent_types::sanitize_prompt_text(prompt);
6590 let probe = prompt_render_probe(&sanitized);
6591 assert!(prompt_rendered(
6592 &snapshot(2, "composer payload<ESC>tail"),
6593 &snapshot(1, "old composer"),
6594 &probe
6595 ));
6596 }
6597
6598 #[test]
6599 fn lag_and_data_gap_reserve_missed_provider_source_positions() {
6600 let mut next = 7;
6601 assert_eq!(reserve_provider_gap_sequence(&mut next, 3), Some(9));
6602 assert_eq!(next, 10);
6603 assert_eq!(reserve_provider_gap_sequence(&mut next, 0), None);
6604 assert_eq!(next, 10);
6605
6606 next = u64::MAX;
6607 assert_eq!(reserve_provider_gap_sequence(&mut next, 1), None);
6608 assert_eq!(next, u64::MAX);
6609 }
6610
6611 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) │";
6624
6625 #[test]
6626 fn bare_detector_misses_the_live_ansi_sample_that_rate_limit_feed_catches() {
6627 let bare = RateLimitDetector::new_for_tool(CliTool::Codex);
6630 assert!(bare.detect(CODEX_STATUS_RAW_ANSI).is_none());
6631
6632 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6635 let info = feed
6636 .detect(CODEX_STATUS_RAW_ANSI)
6637 .expect("quota-state line must be recognized once ANSI is stripped");
6638 assert_eq!(info.limit_type, RateLimitType::Session);
6639 assert_eq!(info.usage_percent, Some(0.0));
6640 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6641 }
6642
6643 #[test]
6644 fn rate_limit_feed_reassembles_a_quota_state_line_split_mid_escape_and_mid_row() {
6645 let first =
6649 "│ 5h limit: \x1b[m[████████████████████] 100% left\x1b";
6650 let second = "[2m (resets 00:08 on 31 Aug) │\r\n";
6651
6652 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6653 assert!(
6654 feed.detect(first).is_none(),
6655 "the row is not complete yet, so nothing should match on the first chunk"
6656 );
6657 let info = feed
6658 .detect(second)
6659 .expect("the row completes once the second chunk arrives");
6660 assert_eq!(info.limit_type, RateLimitType::Session);
6661 assert_eq!(info.resets_at_text.as_deref(), Some("00:08 on 31 Aug"));
6662 }
6663
6664 #[test]
6665 fn rate_limit_feed_strips_ansi_before_matching_a_colored_failure_message() {
6666 let raw = "\x1b[31mError: rate limit exceeded\x1b[0m. Please wait.";
6670 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6671 let info = feed
6672 .detect(raw)
6673 .expect("a colored refusal message must still be recognized");
6674 assert_eq!(info.limit_type, RateLimitType::Unknown);
6675 }
6676
6677 #[test]
6678 fn rate_limit_feed_bounds_its_buffer_across_a_newline_free_redraw() {
6679 let mut feed = RateLimitFeed::new_for_tool(CliTool::Codex);
6684 let noise = "x".repeat(super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES * 3);
6685 assert!(feed.detect(&noise).is_none());
6686 assert!(feed.buffer.len() <= super::RATE_LIMIT_FEED_BUFFER_MAX_BYTES);
6687
6688 let info = feed
6689 .detect(CODEX_STATUS_RAW_ANSI)
6690 .expect("a real quota-state line must still be recognized after the noise");
6691 assert_eq!(info.limit_type, RateLimitType::Session);
6692 }
6693
6694 #[test]
6699 fn full_auto_maps_to_the_permissive_host_policy() {
6700 assert_eq!(host_policy_for_approval_level(ApprovalLevel::FullAuto), HostPolicy::Yolo);
6704 }
6705
6706 #[test]
6707 fn read_only_maps_to_the_read_only_host_policy() {
6708 assert_eq!(
6709 host_policy_for_approval_level(ApprovalLevel::ReadOnly),
6710 HostPolicy::ReadOnly
6711 );
6712 }
6713
6714 #[test]
6715 fn moderate_and_unmanaged_both_fall_back_to_the_default_host_policy() {
6716 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Moderate), HostPolicy::Auto);
6717 assert_eq!(host_policy_for_approval_level(ApprovalLevel::Unmanaged), HostPolicy::Auto);
6718 assert_eq!(HostPolicy::default(), HostPolicy::Auto);
6719 }
6720
6721 #[test]
6722 fn no_approval_level_ever_maps_to_a_refusing_policy_except_read_only_itself() {
6723 for level in [
6728 ApprovalLevel::FullAuto,
6729 ApprovalLevel::Moderate,
6730 ApprovalLevel::ReadOnly,
6731 ApprovalLevel::Unmanaged,
6732 ] {
6733 assert_ne!(
6734 host_policy_for_approval_level(level),
6735 HostPolicy::Deny,
6736 "{level:?} must never map to HostPolicy::Deny"
6737 );
6738 }
6739 }
6740
6741 #[test]
6749 fn defers_permission_requests_matches_the_verified_provider_table() {
6750 let claude = AgentId::new("claude").unwrap();
6755 assert!(!defers_permission_requests(&claude, ApprovalLevel::FullAuto));
6756 assert!(defers_permission_requests(&claude, ApprovalLevel::Moderate));
6757 assert!(defers_permission_requests(&claude, ApprovalLevel::ReadOnly));
6761 assert!(!defers_permission_requests(&claude, ApprovalLevel::Unmanaged));
6765
6766 let codex = AgentId::new("codex").unwrap();
6767 assert!(!defers_permission_requests(&codex, ApprovalLevel::FullAuto));
6768 assert!(!defers_permission_requests(&codex, ApprovalLevel::Moderate));
6773 assert!(defers_permission_requests(&codex, ApprovalLevel::ReadOnly));
6774 assert!(!defers_permission_requests(&codex, ApprovalLevel::Unmanaged));
6776
6777 let grok = AgentId::new("grok").unwrap();
6778 assert!(!defers_permission_requests(&grok, ApprovalLevel::FullAuto));
6779 assert!(defers_permission_requests(&grok, ApprovalLevel::Moderate));
6780 assert!(defers_permission_requests(&grok, ApprovalLevel::ReadOnly));
6784 assert!(!defers_permission_requests(&grok, ApprovalLevel::Unmanaged));
6786
6787 let kimi = AgentId::new("kimi").unwrap();
6788 assert!(!defers_permission_requests(&kimi, ApprovalLevel::FullAuto));
6789 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Moderate));
6792 assert!(!defers_permission_requests(&kimi, ApprovalLevel::ReadOnly));
6796 assert!(!defers_permission_requests(&kimi, ApprovalLevel::Unmanaged));
6798 }
6799
6800 fn session_mode(id: &str) -> SessionMode {
6807 SessionMode { id: id.to_owned(), name: id.to_owned(), description: None }
6808 }
6809
6810 #[test]
6811 fn required_acp_mode_matches_the_sourced_table() {
6812 let claude = AgentId::new("claude").unwrap();
6817 assert_eq!(
6818 required_acp_mode(&claude, ApprovalLevel::FullAuto),
6819 Ok(Some(ModeId::new("bypassPermissions")))
6820 );
6821 assert_eq!(
6822 required_acp_mode(&claude, ApprovalLevel::Moderate),
6823 Ok(Some(ModeId::new("acceptEdits")))
6824 );
6825 assert_eq!(
6829 required_acp_mode(&claude, ApprovalLevel::ReadOnly),
6830 Ok(Some(ModeId::new("default")))
6831 );
6832 assert_eq!(required_acp_mode(&claude, ApprovalLevel::Unmanaged), Ok(None));
6833
6834 let codex = AgentId::new("codex").unwrap();
6835 assert_eq!(
6836 required_acp_mode(&codex, ApprovalLevel::FullAuto),
6837 Ok(Some(ModeId::new("agent-full-access")))
6838 );
6839 assert_eq!(
6840 required_acp_mode(&codex, ApprovalLevel::Moderate),
6841 Ok(Some(ModeId::new("agent")))
6842 );
6843 assert_eq!(
6844 required_acp_mode(&codex, ApprovalLevel::ReadOnly),
6845 Ok(Some(ModeId::new("read-only")))
6846 );
6847 assert_eq!(required_acp_mode(&codex, ApprovalLevel::Unmanaged), Ok(None));
6848
6849 let kimi = AgentId::new("kimi").unwrap();
6861 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::FullAuto), Ok(None));
6862 assert_eq!(
6863 acp_approval_level_args(&kimi, ApprovalLevel::FullAuto),
6864 vec!["--auto".to_owned()],
6865 "kimi's FullAuto must reach the process through argv, since it has no ACP mode"
6866 );
6867 for level in [ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
6868 assert!(
6869 required_acp_mode(&kimi, level).is_err(),
6870 "kimi at {level:?} has neither a sourced ACP mode id nor vendor flags, so it must refuse"
6871 );
6872 }
6873 assert_eq!(required_acp_mode(&kimi, ApprovalLevel::Unmanaged), Ok(None));
6874 assert!(
6875 acp_approval_level_args(&kimi, ApprovalLevel::Unmanaged).is_empty(),
6876 "Unmanaged imposes nothing, so it must add no argv flags either"
6877 );
6878
6879 let grok = AgentId::new("grok").unwrap();
6886 assert_eq!(required_acp_mode(&grok, ApprovalLevel::FullAuto), Ok(None));
6887 assert_eq!(
6888 acp_approval_level_args(&grok, ApprovalLevel::FullAuto),
6889 vec!["--always-approve".to_owned()],
6890 );
6891 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Moderate), Ok(None));
6892 assert_eq!(
6893 acp_approval_level_args(&grok, ApprovalLevel::Moderate),
6894 vec!["--permission-mode".to_owned(), "auto".to_owned()],
6895 );
6896 assert!(
6897 required_acp_mode(&grok, ApprovalLevel::ReadOnly).is_err(),
6898 "grok at ReadOnly is Unsupported outright, so it must refuse"
6899 );
6900 assert_eq!(required_acp_mode(&grok, ApprovalLevel::Unmanaged), Ok(None));
6901 }
6902
6903 #[test]
6914 fn required_acp_mode_never_silently_permits_auto_except_for_unmanaged() {
6915 for id in ["claude", "codex", "grok", "kimi"] {
6916 let agent = AgentId::new(id).unwrap();
6917 for level in [ApprovalLevel::FullAuto, ApprovalLevel::Moderate, ApprovalLevel::ReadOnly] {
6918 match required_acp_mode(&agent, level) {
6919 Ok(Some(mode_id)) => assert_ne!(
6920 mode_id.as_str(),
6921 "auto",
6922 "{id} at {level:?} must never silently resolve the vendor's own default 'auto'"
6923 ),
6924 Ok(None) => assert!(
6925 !acp_approval_level_args(&agent, level).is_empty(),
6926 "{id} at {level:?} resolved Ok(None) while carrying no vendor flags -- \
6927 that leaves the session at the agent's own default. Only Unmanaged, or a \
6928 level argv actually applies, may resolve to no mode"
6929 ),
6930 Err(_) => {} }
6932 }
6933 assert_eq!(
6934 required_acp_mode(&agent, ApprovalLevel::Unmanaged),
6935 Ok(None),
6936 "{id}: Unmanaged is the one level allowed to apply nothing"
6937 );
6938 }
6939 }
6940
6941 #[test]
6942 fn approval_level_not_offered_message_refuses_by_name_and_lists_what_was_offered() {
6943 let offered = vec![session_mode("bypassPermissions"), session_mode("default")];
6944 let mode_id = ModeId::new("plan");
6945 let message = approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered)
6946 .expect("'plan' was not among the offered modes");
6947 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
6948 assert!(message.contains("bypassPermissions"));
6949 assert!(message.contains("default"));
6950 assert!(message.contains("ReadOnly"));
6951 }
6952
6953 #[test]
6954 fn approval_level_not_offered_message_is_none_when_the_agent_announced_it() {
6955 let offered = vec![session_mode("plan")];
6956 let mode_id = ModeId::new("plan");
6957 assert_eq!(
6958 approval_level_not_offered_message(ApprovalLevel::ReadOnly, &mode_id, &offered),
6959 None
6960 );
6961 }
6962
6963 #[test]
6964 fn approval_level_not_offered_message_handles_an_agent_that_announces_no_modes_at_all() {
6965 let mode_id = ModeId::new("bypassPermissions");
6966 let message = approval_level_not_offered_message(ApprovalLevel::FullAuto, &mode_id, &[])
6967 .expect("an empty mode catalog never offers anything");
6968 assert!(message.contains("ApprovalLevelNotOfferedByAgent"));
6969 assert!(message.contains("offered: []"));
6970 }
6971
6972 use super::{NativeEffectShell, NativeSessionKey, OwnedProviderSession};
6989 use gate4agent_catalog::{AgentRegistry as FixtureAgentRegistry, AgentSpec as FixtureAgentSpec};
6990 use gate4agent_types::ControlObservation;
6991 use std::collections::VecDeque;
6992
6993 fn fixture_pipe_key() -> NativeSessionKey {
6994 NativeSessionKey {
6995 instance_id: gate4agent_types::AgentInstanceId(9_001),
6996 generation: gate4agent_types::SessionGeneration(1),
6997 }
6998 }
6999
7000 fn fixture_pipe_source() -> gate4agent_types::ProviderSource {
7001 gate4agent_types::ProviderSource {
7002 family: AdapterFamily::Pipe,
7003 binding: gate4agent_types::AdapterBinding::new(
7004 gate4agent_types::AdapterId::new("fixture").unwrap(),
7005 "1",
7006 gate4agent_types::AdapterVerification::SyntheticFixture,
7007 )
7008 .unwrap(),
7009 }
7010 }
7011
7012 #[cfg(windows)]
7013 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7014 gate4agent_types::LaunchSpec {
7015 by_platform: Vec::new(),
7016 program: "powershell.exe".to_owned(),
7017 fixed_args: vec![
7018 "-NoProfile".to_owned(),
7019 "-NonInteractive".to_owned(),
7020 "-Command".to_owned(),
7021 "[Console]::In.ReadToEnd() | Out-Null; exit 0".to_owned(),
7022 ],
7023 }
7024 }
7025
7026 #[cfg(not(windows))]
7027 fn fixture_graceful_exit_launch() -> gate4agent_types::LaunchSpec {
7028 gate4agent_types::LaunchSpec {
7029 by_platform: Vec::new(),
7030 program: "sh".to_owned(),
7031 fixed_args: vec!["-c".to_owned(), "cat >/dev/null; exit 0".to_owned()],
7032 }
7033 }
7034
7035 #[cfg(windows)]
7036 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7037 gate4agent_types::LaunchSpec {
7038 by_platform: Vec::new(),
7039 program: "powershell.exe".to_owned(),
7040 fixed_args: vec![
7041 "-NoProfile".to_owned(),
7042 "-NonInteractive".to_owned(),
7043 "-Command".to_owned(),
7044 "Start-Sleep -Seconds 30".to_owned(),
7045 ],
7046 }
7047 }
7048
7049 #[cfg(not(windows))]
7050 fn fixture_ignore_stdin_launch() -> gate4agent_types::LaunchSpec {
7051 gate4agent_types::LaunchSpec {
7052 by_platform: Vec::new(),
7053 program: "sh".to_owned(),
7054 fixed_args: vec!["-c".to_owned(), "sleep 30".to_owned()],
7055 }
7056 }
7057
7058 async fn spawn_fixture_pipe_shell(
7059 launch: gate4agent_types::LaunchSpec,
7060 ) -> (NativeEffectShell, NativeSessionKey) {
7061 let session = gate4agent::PipeSession::spawn_with_launch(
7062 gate4agent::core::types::SessionConfig::default(),
7063 "prompt",
7064 &launch,
7065 gate4agent_types::PipePromptDelivery::StdinClose,
7066 )
7067 .await
7068 .expect("fixture pipe process must spawn");
7069 let events = session.subscribe();
7070 let key = fixture_pipe_key();
7071 let mut shell = NativeEffectShell::new(
7072 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7073 .expect("empty fixture catalog"),
7074 );
7075 shell.pipe_sessions.insert(
7076 key,
7077 OwnedProviderSession {
7078 source: fixture_pipe_source(),
7079 session,
7080 events,
7081 pending_events: VecDeque::new(),
7082 pending_provider_events: VecDeque::new(),
7083 next_provider_sequence: 1,
7084 observed_exit_code: None,
7085 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7086 },
7087 );
7088 (shell, key)
7089 }
7090
7091 #[tokio::test]
7092 async fn stop_native_pipe_session_reports_the_real_exit_code_when_not_forced() {
7093 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_graceful_exit_launch()).await;
7094
7095 match shell.stop_native(key, false).await {
7096 ControlObservation::StopCompleted {
7097 forced, exit_code, ..
7098 } => {
7099 assert!(!forced, "a process that exits on its own must not be forced");
7100 assert_eq!(exit_code, Some(0));
7101 }
7102 other => panic!("expected StopCompleted, got {other:?}"),
7103 }
7104 }
7105
7106 #[tokio::test]
7107 async fn stop_native_pipe_session_force_true_kills_immediately_without_waiting() {
7108 let (mut shell, key) = spawn_fixture_pipe_shell(fixture_ignore_stdin_launch()).await;
7109
7110 let start = std::time::Instant::now();
7111 match shell.stop_native(key, true).await {
7112 ControlObservation::StopCompleted { forced, .. } => {
7113 assert!(forced, "force=true must always report forced");
7114 }
7115 other => panic!("expected StopCompleted, got {other:?}"),
7116 }
7117 assert!(
7118 start.elapsed()
7119 < std::time::Duration::from_secs(gate4agent::pipe::PIPE_GRACEFUL_STOP_BOUND_SECS),
7120 "force=true must not wait out the graceful bound"
7121 );
7122 }
7123
7124 #[cfg(windows)]
7140 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7141 gate4agent_types::LaunchSpec {
7142 by_platform: Vec::new(),
7143 program: "powershell.exe".to_owned(),
7144 fixed_args: vec![
7145 "-NoLogo".to_owned(),
7146 "-NoProfile".to_owned(),
7147 "-NonInteractive".to_owned(),
7148 "-ExecutionPolicy".to_owned(),
7149 "Bypass".to_owned(),
7150 "-Command".to_owned(),
7151 ACP_HANDSHAKE_SCRIPT.to_owned(),
7152 ],
7153 }
7154 }
7155
7156 #[cfg(not(windows))]
7157 fn acp_fixture_launch() -> gate4agent_types::LaunchSpec {
7158 gate4agent_types::LaunchSpec {
7159 by_platform: Vec::new(),
7160 program: "python3".to_owned(),
7161 fixed_args: vec!["-u".to_owned(), "-c".to_owned(), ACP_HANDSHAKE_SCRIPT.to_owned()],
7162 }
7163 }
7164
7165 #[cfg(windows)]
7166 const ACP_HANDSHAKE_SCRIPT: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7167function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7168$initialize = [Console]::ReadLine() | ConvertFrom-Json
7169Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7170$newSession = [Console]::ReadLine() | ConvertFrom-Json
7171Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{sessionId='fixture-acp-session'}}
7172while ($true) {
7173 $line = [Console]::ReadLine()
7174 if ($null -eq $line) { exit 0 }
7175}"#;
7176 #[cfg(not(windows))]
7177 const ACP_HANDSHAKE_SCRIPT: &str = r#"import json,sys
7178def read_message():
7179 line=sys.stdin.readline()
7180 if not line: return None
7181 return json.loads(line)
7182def write_message(message):
7183 print(json.dumps(message),flush=True)
7184
7185initialize=read_message()
7186write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7187new_session=read_message()
7188write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{'sessionId':'fixture-acp-session'}})
7189while True:
7190 msg=read_message()
7191 if msg is None:
7192 sys.exit(0)"#;
7193
7194 fn fixture_acp_key() -> NativeSessionKey {
7195 NativeSessionKey {
7196 instance_id: gate4agent_types::AgentInstanceId(9_002),
7197 generation: gate4agent_types::SessionGeneration(1),
7198 }
7199 }
7200
7201 fn fixture_acp_source() -> gate4agent_types::ProviderSource {
7202 gate4agent_types::ProviderSource {
7203 family: AdapterFamily::Acp,
7204 binding: gate4agent_types::AdapterBinding::new(
7205 gate4agent_types::AdapterId::new("fixture").unwrap(),
7206 "1",
7207 gate4agent_types::AdapterVerification::SyntheticFixture,
7208 )
7209 .unwrap(),
7210 }
7211 }
7212
7213 async fn spawn_fixture_acp_shell() -> (NativeEffectShell, NativeSessionKey) {
7214 let session = gate4agent::acp::AcpSession::spawn_with_launch(
7215 gate4agent::CliTool::ClaudeCode,
7216 &std::env::current_dir().expect("cwd"),
7217 gate4agent::acp::AcpSessionOptions::default(),
7218 &acp_fixture_launch(),
7219 )
7220 .await
7221 .expect("fixture ACP handshake must succeed");
7222 let events = session.subscribe();
7223 let key = fixture_acp_key();
7224 let mut shell = NativeEffectShell::new(
7225 FixtureAgentRegistry::new(std::iter::empty::<FixtureAgentSpec>())
7226 .expect("empty fixture catalog"),
7227 );
7228 shell.acp_sessions.insert(
7229 key,
7230 OwnedProviderSession {
7231 source: fixture_acp_source(),
7232 session,
7233 events,
7234 pending_events: VecDeque::new(),
7235 pending_provider_events: VecDeque::new(),
7236 next_provider_sequence: 1,
7237 observed_exit_code: None,
7238 runtime_policy: gate4agent_types::ProviderRuntimePolicy::none(),
7239 },
7240 );
7241 (shell, key)
7242 }
7243
7244 #[tokio::test]
7245 async fn stop_native_acp_session_reports_the_real_exit_code_when_not_forced() {
7246 let (mut shell, key) = spawn_fixture_acp_shell().await;
7247
7248 match shell.stop_native(key, false).await {
7249 ControlObservation::StopCompleted {
7250 forced, exit_code, ..
7251 } => {
7252 assert!(!forced, "a process that exits on its own must not be forced");
7253 assert_eq!(exit_code, Some(0));
7254 }
7255 other => panic!("expected StopCompleted, got {other:?}"),
7256 }
7257 }
7258
7259 #[cfg(windows)]
7277 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7278 gate4agent_types::LaunchSpec {
7279 by_platform: Vec::new(),
7280 program: "powershell.exe".to_owned(),
7281 fixed_args: vec![
7282 "-NoLogo".to_owned(),
7283 "-NoProfile".to_owned(),
7284 "-NonInteractive".to_owned(),
7285 "-ExecutionPolicy".to_owned(),
7286 "Bypass".to_owned(),
7287 "-Command".to_owned(),
7288 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7289 ],
7290 }
7291 }
7292
7293 #[cfg(not(windows))]
7294 fn acp_fixture_launch_no_session_id() -> gate4agent_types::LaunchSpec {
7295 gate4agent_types::LaunchSpec {
7296 by_platform: Vec::new(),
7297 program: "python3".to_owned(),
7298 fixed_args: vec![
7299 "-u".to_owned(),
7300 "-c".to_owned(),
7301 ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID.to_owned(),
7302 ],
7303 }
7304 }
7305
7306 #[cfg(windows)]
7307 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"[Console]::OutputEncoding=[Text.Encoding]::UTF8
7308function Write-JsonLine($value) { [Console]::WriteLine(($value | ConvertTo-Json -Compress -Depth 12)) }
7309$initialize = [Console]::ReadLine() | ConvertFrom-Json
7310Write-JsonLine @{jsonrpc='2.0';id=$initialize.id;result=@{}}
7311$newSession = [Console]::ReadLine() | ConvertFrom-Json
7312Write-JsonLine @{jsonrpc='2.0';id=$newSession.id;result=@{}}
7313while ($true) {
7314 $line = [Console]::ReadLine()
7315 if ($null -eq $line) { exit 0 }
7316}"#;
7317 #[cfg(not(windows))]
7318 const ACP_HANDSHAKE_SCRIPT_NO_SESSION_ID: &str = r#"import json,sys
7319def read_message():
7320 line=sys.stdin.readline()
7321 if not line: return None
7322 return json.loads(line)
7323def write_message(message):
7324 print(json.dumps(message),flush=True)
7325
7326initialize=read_message()
7327write_message({'jsonrpc':'2.0','id':initialize.get('id'),'result':{}})
7328new_session=read_message()
7329write_message({'jsonrpc':'2.0','id':new_session.get('id'),'result':{}})
7330while True:
7331 msg=read_message()
7332 if msg is None:
7333 sys.exit(0)"#;
7334
7335 fn fixture_acp_spawn_agent_id() -> AgentId {
7336 AgentId::new("claude").expect("builtin catalog names 'claude'")
7337 }
7338
7339 fn fixture_acp_spawn_agent_spec(launch: gate4agent_types::LaunchSpec) -> FixtureAgentSpec {
7345 let mut spec = gate4agent_catalog::builtin_registry()
7346 .get(&fixture_acp_spawn_agent_id())
7347 .cloned()
7348 .expect("builtin catalog must declare claude");
7349 spec.capabilities
7350 .transports
7351 .acp
7352 .as_mut()
7353 .expect("claude must declare ACP capability")
7354 .launch_override = Some(launch);
7355 spec
7356 }
7357
7358 fn fixture_acp_spawn_key() -> NativeSessionKey {
7359 NativeSessionKey {
7360 instance_id: gate4agent_types::AgentInstanceId(9_101),
7361 generation: gate4agent_types::SessionGeneration(1),
7362 }
7363 }
7364
7365 async fn spawn_native_acp_fixture(
7371 launch: gate4agent_types::LaunchSpec,
7372 provider_session_identity: bool,
7373 ) -> (NativeEffectShell, NativeSessionKey, ControlObservation) {
7374 let mut policy = ProviderRuntimePolicy::none();
7375 policy.provider_session_identity = provider_session_identity;
7376 let key = fixture_acp_spawn_key();
7377 let mut shell = NativeEffectShell::new(
7378 FixtureAgentRegistry::new([fixture_acp_spawn_agent_spec(launch)])
7379 .expect("single-agent fixture catalog"),
7380 );
7381 let envelope = gate4agent_types::EffectEnvelope {
7382 operation_id: gate4agent_types::OperationId(1),
7383 instance_id: key.instance_id,
7384 generation: key.generation,
7385 effect: gate4agent_types::ControlEffect::Spawn {
7386 agent_id: fixture_acp_spawn_agent_id(),
7387 transport: TransportKind::Acp,
7388 runtime_policy: policy,
7389 request: gate4agent_types::StartRequest {
7390 working_directory: std::env::current_dir()
7391 .expect("cwd")
7392 .to_string_lossy()
7393 .into_owned(),
7394 terminal_size: gate4agent_types::TerminalSize {
7395 rows: 24,
7396 columns: 80,
7397 },
7398 initial_prompt: None,
7399 session_options: None,
7400 approval_level: ApprovalLevel::Unmanaged,
7401 },
7402 },
7403 };
7404 let observation = shell.execute(envelope).await.observation;
7405 (shell, key, observation)
7406 }
7407
7408 #[tokio::test]
7409 async fn acp_spawn_with_a_real_sessionid_emits_session_identity_observed_after_session_start() {
7410 let (mut shell, key, spawned) =
7411 spawn_native_acp_fixture(acp_fixture_launch(), true).await;
7412 match spawned {
7413 ControlObservation::Spawned { .. } => {}
7414 other => panic!("expected Spawned, got {other:?}"),
7415 }
7416
7417 let mut provider_events = shell
7418 .collect_provider_events()
7419 .into_iter()
7420 .filter_map(|envelope| match envelope.observation {
7421 ControlObservation::ProviderEvent { event, .. } => Some(event),
7422 _ => None,
7423 });
7424
7425 match provider_events.next() {
7426 Some(ProviderEvent::SessionStarted { .. }) => {}
7427 other => panic!("expected SessionStarted first, got {other:?}"),
7428 }
7429 match provider_events.next() {
7430 Some(ProviderEvent::SessionIdentityObserved { identity }) => {
7431 assert_eq!(identity.key, gate4agent_types::ProviderSessionKey::SessionId);
7432 assert_eq!(identity.id, "fixture-acp-session");
7433 assert!(identity.transcript_path.is_none());
7434 }
7435 other => panic!("expected SessionIdentityObserved second, got {other:?}"),
7436 }
7437 assert!(
7438 provider_events.next().is_none(),
7439 "expected exactly one SessionIdentityObserved and nothing after it"
7440 );
7441
7442 let _ = shell.stop_native(key, true).await;
7443 }
7444
7445 #[tokio::test]
7446 async fn acp_spawn_with_no_sessionid_emits_no_session_identity_observed() {
7447 let (mut shell, key, spawned) =
7448 spawn_native_acp_fixture(acp_fixture_launch_no_session_id(), true).await;
7449 match spawned {
7450 ControlObservation::Spawned { .. } => {}
7451 other => panic!("expected Spawned, got {other:?}"),
7452 }
7453
7454 let provider_events: Vec<_> = shell
7455 .collect_provider_events()
7456 .into_iter()
7457 .filter_map(|envelope| match envelope.observation {
7458 ControlObservation::ProviderEvent { event, .. } => Some(event),
7459 _ => None,
7460 })
7461 .collect();
7462
7463 assert!(
7464 provider_events
7465 .iter()
7466 .any(|event| matches!(event, ProviderEvent::SessionStarted { .. })),
7467 "expected SessionStarted even when the agent reported no sessionId, got {provider_events:?}"
7468 );
7469 assert!(
7470 !provider_events
7471 .iter()
7472 .any(|event| matches!(event, ProviderEvent::SessionIdentityObserved { .. })),
7473 "an agent that violates ACP's sessionId MUST must not be granted an identity: \
7474 got {provider_events:?}"
7475 );
7476
7477 let _ = shell.stop_native(key, true).await;
7478 }
7479}