Skip to main content

gate4agent_kernel/
lib.rs

1//! Synchronous host kernel for gate4agent engines.
2
3use gate4agent_catalog::{
4    builtin_registry, resolve_capability_probe_for, resolve_one_shot_plan,
5    resolve_session_option_launch_for, AgentRegistry,
6};
7use gate4agent_engine::Gate4AgentEngine;
8use gate4agent_tool_engine::{ToolEngine, ToolEngineError};
9use gate4agent_tool_protocol::{
10    CapabilityCompletionBatch, CapabilityObservationDisposition, CapabilityProviderDescriptor,
11    CapabilityRequestKey, ObservationIgnoredReason, PolicyDecision, ProviderBindingId,
12    ProviderBoundCapabilityEffectEnvelope, ProviderBoundCapabilityRequest,
13    ProviderRuntimeBindingSnapshot, ProviderRuntimeCommand, ProviderRuntimeEnvelope,
14    ProviderRuntimeSnapshot, ToolAuthorityEnvelope, ToolAuthorityOutcome, ToolEngineSnapshot,
15    ToolInstanceState, ToolProviderId, ToolValidationError,
16};
17use gate4agent_types::{
18    AdapterBinding, AdapterFamily, AgentId, AgentInstanceId, CommandEnvelope, CommandId,
19    ControlCommand, ControlError, ControlEvent, ControlHealth, ControlSnapshot, EffectEnvelope,
20    InputAction, ObservationEnvelope, PipeProtocol, ProviderSource, SessionStatus, TransportKind,
21};
22use std::collections::{BTreeMap, BTreeSet};
23use std::fmt;
24use std::sync::Arc;
25use thiserror::Error;
26
27/// Trusted in-process ingress for the single-writer backend reducer.
28///
29/// Network and IPC shells must authenticate and bind connection-owned
30/// identities before constructing these values. This enum is not itself a
31/// transport authorization boundary.
32#[derive(Clone, Debug, Eq, PartialEq)]
33pub enum BackendIngress {
34    Control(CommandEnvelope),
35    ToolRequest(ProviderBoundCapabilityRequest),
36    ToolAuthority(ToolAuthorityEnvelope),
37    ToolProvider(ProviderRuntimeEnvelope),
38}
39
40#[derive(Clone, Debug, Eq, PartialEq)]
41pub struct ToolRequestOutcome {
42    pub request_key: CapabilityRequestKey,
43    pub accepted_sequence: Option<u64>,
44    pub result: Result<PolicyDecision, KernelToolError>,
45}
46
47#[derive(Clone, Debug, Eq, PartialEq)]
48pub struct ToolAuthorityCommandOutcome {
49    pub sequence: u64,
50    pub result: Result<ToolAuthorityOutcome, KernelToolError>,
51}
52
53#[derive(Clone, Debug, Eq, PartialEq)]
54pub enum BackendIngressOutcome {
55    Control(CommandOutcome),
56    ToolRequest(ToolRequestOutcome),
57    ToolAuthority(ToolAuthorityCommandOutcome),
58    ToolProvider(ProviderRuntimeCommandOutcome),
59}
60
61#[derive(Clone, Debug, Eq, PartialEq)]
62pub struct ProviderRuntimeCommandOutcome {
63    pub sequence: u64,
64    pub binding_id: ProviderBindingId,
65    pub provider_id: ToolProviderId,
66    pub result: Result<ProviderRuntimeTransition, KernelProviderError>,
67}
68
69#[derive(Clone, Debug, Eq, PartialEq)]
70pub enum ProviderRuntimeTransition {
71    Attached,
72    Detached {
73        closed_request_count: usize,
74    },
75    ObservationApplied {
76        operation_id: gate4agent_tool_protocol::ToolOperationId,
77        request_key: CapabilityRequestKey,
78    },
79    ObservationIgnored {
80        operation_id: gate4agent_tool_protocol::ToolOperationId,
81        request_key: CapabilityRequestKey,
82        reason: ObservationIgnoredReason,
83    },
84}
85
86#[derive(Clone, Debug, Eq, Error, PartialEq)]
87pub enum KernelToolError {
88    #[error(transparent)]
89    Engine(#[from] ToolEngineError),
90    #[error(transparent)]
91    Validation(#[from] ToolValidationError),
92    #[error("tool provider '{provider_id}' has no active runtime binding")]
93    ProviderUnavailable { provider_id: ToolProviderId },
94    #[error(
95        "tool request targets provider '{provider_id}' binding {requested:?}, current binding is {current:?}"
96    )]
97    ProviderBindingMismatch {
98        provider_id: ToolProviderId,
99        current: ProviderBindingId,
100        requested: Option<ProviderBindingId>,
101    },
102    #[error("tool lane is blocked by a control/tool integration failure")]
103    IntegrationBlocked,
104}
105
106#[derive(Clone, Debug, Eq, Error, PartialEq)]
107pub enum KernelProviderError {
108    #[error(transparent)]
109    Validation(#[from] gate4agent_tool_protocol::ToolValidationError),
110    #[error("tool provider runtime sequence is exhausted")]
111    SequenceExhausted,
112    #[error("tool provider runtime sequence regressed from {current} to {requested}")]
113    SequenceRegressed { current: u64, requested: u64 },
114    #[error("tool provider '{provider_id}' is not registered")]
115    UnknownProvider { provider_id: ToolProviderId },
116    #[error("attach binding {binding_id:?} must equal provider runtime sequence {sequence}")]
117    InvalidAttachBinding {
118        sequence: u64,
119        binding_id: ProviderBindingId,
120    },
121    #[error("tool provider '{provider_id}' is already attached as binding {binding_id:?}")]
122    AlreadyAttached {
123        provider_id: ToolProviderId,
124        binding_id: ProviderBindingId,
125    },
126    #[error("tool provider '{provider_id}' has no active runtime binding")]
127    NotAttached { provider_id: ToolProviderId },
128    #[error("tool provider '{provider_id}' is attached as {current:?}, not {requested:?}")]
129    BindingMismatch {
130        provider_id: ToolProviderId,
131        current: ProviderBindingId,
132        requested: ProviderBindingId,
133    },
134    #[error(transparent)]
135    Engine(#[from] ToolEngineError),
136    #[error("tool provider lane is blocked by a control/tool integration failure")]
137    IntegrationBlocked,
138}
139
140#[derive(Clone, Debug, Eq, Error, PartialEq)]
141pub enum KernelIntegrationError {
142    #[error("kernel logical tick exhausted at {current_tick}")]
143    LogicalTickExhausted { current_tick: u64 },
144    #[error("kernel snapshot revision exhausted at {current_revision}")]
145    BackendRevisionExhausted { current_revision: u64 },
146    #[error("control engine entered terminal counter exhaustion: {health:?}")]
147    ControlHealthExhausted { health: ControlHealth },
148    #[error("control observation for {instance_id:?} failed: {source}")]
149    ControlObservation {
150        instance_id: AgentInstanceId,
151        #[source]
152        source: ControlError,
153    },
154    #[error("tool clock advance failed: {source}")]
155    ToolClock {
156        #[source]
157        source: ToolEngineError,
158    },
159    #[error("tool instance sync failed for {instance_id:?}: {source}")]
160    ToolInstanceSync {
161        instance_id: AgentInstanceId,
162        #[source]
163        source: ToolEngineError,
164    },
165    #[error(
166        "tool effect {operation_id:?} targets provider '{provider_id}' without an active runtime binding"
167    )]
168    ToolEffectProviderUnbound {
169        operation_id: gate4agent_tool_protocol::ToolOperationId,
170        provider_id: ToolProviderId,
171    },
172}
173
174#[derive(Clone, Debug, Eq, PartialEq)]
175pub struct BackendSnapshot {
176    pub revision: u64,
177    pub logical_tick: u64,
178    pub control: Arc<ControlSnapshot>,
179    pub tools: Arc<ToolEngineSnapshot>,
180    pub provider_runtime: ProviderRuntimeSnapshot,
181}
182
183impl Default for BackendSnapshot {
184    fn default() -> Self {
185        Self {
186            revision: 0,
187            logical_tick: 0,
188            control: Arc::new(ControlSnapshot {
189                revision: 0,
190                health: ControlHealth::default(),
191                sessions: Vec::new(),
192            }),
193            tools: Arc::new(ToolEngine::new().snapshot()),
194            provider_runtime: ProviderRuntimeSnapshot {
195                last_sequence: 0,
196                sequence_exhausted: false,
197                bindings: Vec::new(),
198            },
199        }
200    }
201}
202
203#[derive(Clone, Debug, Eq, PartialEq)]
204pub struct CommandOutcome {
205    pub command_id: CommandId,
206    pub result: Result<(), KernelCommandError>,
207}
208
209#[derive(Clone, Debug, Eq, Error, PartialEq)]
210pub enum KernelCommandError {
211    #[error("kernel control plane is blocked: {reason}")]
212    IntegrationBlocked { reason: KernelIntegrationError },
213    #[error("agent '{agent_id}' is not present in the kernel catalog")]
214    UnknownAgent { agent_id: AgentId },
215    #[error("agent '{agent_id}' does not declare capability '{capability}'")]
216    UnsupportedCapability {
217        agent_id: AgentId,
218        capability: &'static str,
219    },
220    #[error("agent '{agent_id}' does not support transport {transport:?}")]
221    UnsupportedTransport {
222        agent_id: AgentId,
223        transport: TransportKind,
224    },
225    #[error(
226        "agent '{agent_id}' does not declare {family:?} provider source '{adapter_id}' at revision '{revision}'"
227    )]
228    InvalidProviderSource {
229        agent_id: AgentId,
230        family: AdapterFamily,
231        adapter_id: String,
232        revision: String,
233    },
234    #[error("agent '{agent_id}' session options are invalid: {message}")]
235    InvalidSessionOptions { agent_id: AgentId, message: String },
236    #[error("agent '{agent_id}' capability probe is invalid: {message}")]
237    InvalidCapabilityProbe { agent_id: AgentId, message: String },
238    #[error(transparent)]
239    Control(#[from] ControlError),
240}
241
242impl KernelCommandError {
243    /// True for exactly the `UnsupportedTransport` variant. Exists so a
244    /// caller several layers up the stack -- `gate4agent-node`'s spawn-
245    /// dispatch waiter, specifically, which cannot and should not depend on
246    /// this crate directly (see this crate's own `Forbidden` list) -- can
247    /// classify one specific, already-well-known kernel rejection by
248    /// calling this inherent method on the value it already has (via
249    /// `gate4agent-runtime-native`'s `CommandOutcome` re-export), without
250    /// naming `KernelCommandError`'s own type path or matching its full
251    /// variant set.
252    pub fn is_unsupported_transport(&self) -> bool {
253        matches!(self, Self::UnsupportedTransport { .. })
254    }
255}
256
257#[derive(Clone, Debug, Eq, PartialEq)]
258pub struct KernelStep {
259    pub command_outcomes: Vec<CommandOutcome>,
260    pub effects: Vec<EffectEnvelope>,
261    pub snapshot: ControlSnapshot,
262    pub events: Vec<ControlEvent>,
263    pub ingress_outcomes: Vec<BackendIngressOutcome>,
264    pub tool_effects: Vec<ProviderBoundCapabilityEffectEnvelope>,
265    pub tool_completions: CapabilityCompletionBatch,
266    pub backend_snapshot: BackendSnapshot,
267    pub integration_errors: Vec<KernelIntegrationError>,
268}
269
270/// Owns the provider catalog and the single session-state writer.
271///
272/// Phase order is fixed: clock advance, ordered ingress, control observations,
273/// tool observations, effect/completion drains, atomic snapshot, then ordered
274/// event drain. No phase awaits or performs external work. The kernel is
275/// intentionally not cloneable: cloning would fork provider binding and
276/// sequence authority while preserving otherwise valid runtime identities.
277pub struct Gate4AgentKernel {
278    catalog: AgentRegistry,
279    engine: Gate4AgentEngine,
280    tool_engine: ToolEngine,
281    provider_bindings: BTreeMap<ToolProviderId, ProviderBindingId>,
282    last_provider_sequence: u64,
283    provider_sequence_exhausted: bool,
284    logical_tick: u64,
285    backend_revision: u64,
286}
287
288impl fmt::Debug for Gate4AgentKernel {
289    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
290        formatter
291            .debug_struct("Gate4AgentKernel")
292            .field("catalog", &self.catalog)
293            .field("engine", &self.engine)
294            .field("tools", &self.tool_engine.snapshot())
295            .field("provider_runtime", &self.provider_runtime_snapshot())
296            .field("logical_tick", &self.logical_tick)
297            .field("backend_revision", &self.backend_revision)
298            .finish()
299    }
300}
301
302impl Gate4AgentKernel {
303    pub fn new(catalog: AgentRegistry) -> Self {
304        Self {
305            catalog,
306            engine: Gate4AgentEngine::new(),
307            tool_engine: ToolEngine::new(),
308            provider_bindings: BTreeMap::new(),
309            last_provider_sequence: 0,
310            provider_sequence_exhausted: false,
311            logical_tick: 0,
312            backend_revision: 0,
313        }
314    }
315
316    pub fn with_tool_providers(
317        catalog: AgentRegistry,
318        providers: impl IntoIterator<Item = CapabilityProviderDescriptor>,
319    ) -> Result<Self, ToolEngineError> {
320        let mut kernel = Self::new(catalog);
321        for provider in providers {
322            kernel.tool_engine.register_provider(provider)?;
323        }
324        Ok(kernel)
325    }
326
327    pub fn with_builtin_catalog() -> Self {
328        Self::new(builtin_registry().clone())
329    }
330
331    pub fn step(
332        &mut self,
333        commands: impl IntoIterator<Item = CommandEnvelope>,
334        observations: impl IntoIterator<Item = ObservationEnvelope>,
335    ) -> KernelStep {
336        self.step_control_plane(
337            commands.into_iter().map(BackendIngress::Control),
338            observations,
339        )
340    }
341
342    /// Reduces one backend tick without performing external work.
343    ///
344    /// The phase order is fixed: advance the kernel-owned logical clock;
345    /// reduce ordered control/tool ingress; reduce control observations while
346    /// synchronizing the affected tool instance after every observation;
347    /// reduce provider-bound tool observations; then drain effects,
348    /// completions, snapshots, and events. A tool integration failure blocks
349    /// tool ingress and effect release for the rest of the tick.
350    pub fn step_control_plane(
351        &mut self,
352        ingress: impl IntoIterator<Item = BackendIngress>,
353        control_observations: impl IntoIterator<Item = ObservationEnvelope>,
354    ) -> KernelStep {
355        let ingress = ingress.into_iter().collect::<Vec<_>>();
356        let control_observations = control_observations.into_iter().collect::<Vec<_>>();
357
358        if let Err(error) = self.advance_backend_clock() {
359            return self.blocked_step(ingress, error);
360        }
361
362        let mut command_outcomes = Vec::new();
363        let mut ingress_outcomes = Vec::new();
364        let mut integration_errors = Vec::new();
365        let mut control_lane_open = true;
366        let mut tool_lane_open = true;
367        self.block_on_control_health(
368            &mut control_lane_open,
369            &mut tool_lane_open,
370            &mut integration_errors,
371        );
372        if control_lane_open {
373            self.reconcile_or_block(&mut tool_lane_open, &mut integration_errors);
374        }
375
376        for item in ingress {
377            match item {
378                BackendIngress::Control(command) => {
379                    let command_id = command.id;
380                    let instance_id = command.command.instance_id();
381                    let attempted = control_lane_open;
382                    let result = if attempted {
383                        self.apply_validated_command(command)
384                    } else {
385                        Err(KernelCommandError::IntegrationBlocked {
386                            reason: self
387                                .control_health_error()
388                                .expect("closed control lane has terminal health"),
389                        })
390                    };
391                    if attempted {
392                        if let Err(error) = &result {
393                            self.engine.record_command_rejection(
394                                command_id,
395                                instance_id,
396                                error.to_string(),
397                            );
398                        }
399                    }
400                    let outcome = CommandOutcome { command_id, result };
401                    command_outcomes.push(outcome.clone());
402                    ingress_outcomes.push(BackendIngressOutcome::Control(outcome));
403                    if attempted {
404                        self.sync_or_block(
405                            instance_id,
406                            &mut tool_lane_open,
407                            &mut integration_errors,
408                        );
409                        self.block_on_control_health(
410                            &mut control_lane_open,
411                            &mut tool_lane_open,
412                            &mut integration_errors,
413                        );
414                    }
415                }
416                BackendIngress::ToolRequest(bound_request) => {
417                    let request_key = bound_request.key();
418                    let provider_id = bound_request.request.request.provider_id.clone();
419                    let result = if !tool_lane_open {
420                        Err(KernelToolError::IntegrationBlocked)
421                    } else if let Err(error) = bound_request.validate_provider_binding() {
422                        Err(KernelToolError::Validation(error))
423                    } else if self.tool_engine.provider_exists(&provider_id) {
424                        match self.provider_bindings.get(&provider_id).copied() {
425                            None => Err(KernelToolError::ProviderUnavailable { provider_id }),
426                            Some(current) if bound_request.provider_binding_id != Some(current) => {
427                                Err(KernelToolError::ProviderBindingMismatch {
428                                    provider_id,
429                                    current,
430                                    requested: bound_request.provider_binding_id,
431                                })
432                            }
433                            Some(_) => self
434                                .tool_engine
435                                .request(bound_request.request)
436                                .map_err(Into::into),
437                        }
438                    } else {
439                        self.tool_engine
440                            .request(bound_request.request)
441                            .map_err(Into::into)
442                    };
443                    let accepted_sequence = result.as_ref().ok().and_then(|_| {
444                        self.tool_engine
445                            .request_snapshot(&request_key)
446                            .map(|snapshot| snapshot.accepted_sequence)
447                    });
448                    ingress_outcomes.push(BackendIngressOutcome::ToolRequest(ToolRequestOutcome {
449                        request_key,
450                        accepted_sequence,
451                        result,
452                    }));
453                }
454                BackendIngress::ToolAuthority(authority) => {
455                    let sequence = authority.sequence;
456                    let result = if tool_lane_open {
457                        self.tool_engine
458                            .apply_authority(authority)
459                            .map_err(Into::into)
460                    } else {
461                        Err(KernelToolError::IntegrationBlocked)
462                    };
463                    ingress_outcomes.push(BackendIngressOutcome::ToolAuthority(
464                        ToolAuthorityCommandOutcome { sequence, result },
465                    ));
466                }
467                BackendIngress::ToolProvider(envelope) => {
468                    let outcome = self.apply_provider_runtime(envelope, tool_lane_open);
469                    ingress_outcomes.push(BackendIngressOutcome::ToolProvider(outcome));
470                }
471            }
472        }
473
474        for observation in control_observations {
475            let instance_id = observation.instance_id;
476            match self.engine.try_apply_observation(observation) {
477                Ok(()) => {
478                    self.sync_or_block(instance_id, &mut tool_lane_open, &mut integration_errors)
479                }
480                Err(source) => {
481                    control_lane_open = false;
482                    tool_lane_open = false;
483                    integration_errors.push(KernelIntegrationError::ControlObservation {
484                        instance_id,
485                        source,
486                    });
487                }
488            }
489            self.block_on_control_health(
490                &mut control_lane_open,
491                &mut tool_lane_open,
492                &mut integration_errors,
493            );
494        }
495
496        let effects = self.engine.drain_effects();
497        let tool_effects = if tool_lane_open {
498            match self.drain_bound_tool_effects() {
499                Ok(effects) => effects,
500                Err(error) => {
501                    integration_errors.push(error);
502                    Vec::new()
503                }
504            }
505        } else {
506            Vec::new()
507        };
508        let tool_completions = self.tool_engine.drain_completions();
509        let backend_snapshot = self.backend_snapshot();
510        let snapshot = (*backend_snapshot.control).clone();
511        let events = self.engine.drain_events();
512
513        KernelStep {
514            command_outcomes,
515            effects,
516            snapshot,
517            events,
518            ingress_outcomes,
519            tool_effects,
520            tool_completions,
521            backend_snapshot,
522            integration_errors,
523        }
524    }
525
526    pub fn snapshot(&self) -> ControlSnapshot {
527        self.engine.snapshot()
528    }
529
530    pub fn tool_snapshot(&self) -> ToolEngineSnapshot {
531        self.tool_engine.snapshot()
532    }
533
534    pub fn backend_snapshot(&self) -> BackendSnapshot {
535        BackendSnapshot {
536            revision: self.backend_revision,
537            logical_tick: self.logical_tick,
538            control: Arc::new(self.engine.snapshot()),
539            tools: Arc::new(self.tool_engine.snapshot()),
540            provider_runtime: self.provider_runtime_snapshot(),
541        }
542    }
543
544    pub fn catalog(&self) -> &AgentRegistry {
545        &self.catalog
546    }
547
548    fn provider_runtime_snapshot(&self) -> ProviderRuntimeSnapshot {
549        ProviderRuntimeSnapshot {
550            last_sequence: self.last_provider_sequence,
551            sequence_exhausted: self.provider_sequence_exhausted,
552            bindings: self
553                .provider_bindings
554                .iter()
555                .map(|(provider_id, binding_id)| ProviderRuntimeBindingSnapshot {
556                    binding_id: *binding_id,
557                    provider_id: provider_id.clone(),
558                })
559                .collect(),
560        }
561    }
562
563    fn apply_provider_runtime(
564        &mut self,
565        envelope: ProviderRuntimeEnvelope,
566        tool_lane_open: bool,
567    ) -> ProviderRuntimeCommandOutcome {
568        let sequence = envelope.sequence;
569        let (binding_id, provider_id) = provider_runtime_subject(&envelope.command);
570        let mut result = self.reduce_provider_runtime(envelope, tool_lane_open);
571        if self.provider_sequence_exhausted {
572            if let Err(error) = self.retire_exhausted_provider_bindings() {
573                result = Err(KernelProviderError::Engine(error));
574            }
575        }
576        ProviderRuntimeCommandOutcome {
577            sequence,
578            binding_id,
579            provider_id,
580            result,
581        }
582    }
583
584    fn retire_exhausted_provider_bindings(&mut self) -> Result<(), ToolEngineError> {
585        let provider_ids = self.provider_bindings.keys().cloned().collect::<Vec<_>>();
586        for provider_id in provider_ids {
587            self.tool_engine.detach_provider_runtime(&provider_id)?;
588            self.provider_bindings.remove(&provider_id);
589        }
590        Ok(())
591    }
592
593    fn reduce_provider_runtime(
594        &mut self,
595        envelope: ProviderRuntimeEnvelope,
596        tool_lane_open: bool,
597    ) -> Result<ProviderRuntimeTransition, KernelProviderError> {
598        envelope.validate()?;
599        if self.provider_sequence_exhausted {
600            return Err(KernelProviderError::SequenceExhausted);
601        }
602        if envelope.sequence <= self.last_provider_sequence {
603            return Err(KernelProviderError::SequenceRegressed {
604                current: self.last_provider_sequence,
605                requested: envelope.sequence,
606            });
607        }
608
609        self.last_provider_sequence = envelope.sequence;
610        if envelope.sequence == u64::MAX {
611            self.provider_sequence_exhausted = true;
612        }
613        if !tool_lane_open {
614            return Err(KernelProviderError::IntegrationBlocked);
615        }
616
617        match envelope.command {
618            ProviderRuntimeCommand::Attach {
619                binding_id,
620                provider_id,
621            } => {
622                if binding_id.0 != envelope.sequence {
623                    return Err(KernelProviderError::InvalidAttachBinding {
624                        sequence: envelope.sequence,
625                        binding_id,
626                    });
627                }
628                if !self.tool_engine.provider_exists(&provider_id) {
629                    return Err(KernelProviderError::UnknownProvider { provider_id });
630                }
631                if let Some(current) = self.provider_bindings.get(&provider_id).copied() {
632                    return Err(KernelProviderError::AlreadyAttached {
633                        provider_id,
634                        binding_id: current,
635                    });
636                }
637                self.provider_bindings.insert(provider_id, binding_id);
638                Ok(ProviderRuntimeTransition::Attached)
639            }
640            ProviderRuntimeCommand::Detach {
641                binding_id,
642                provider_id,
643            } => {
644                if !self.tool_engine.provider_exists(&provider_id) {
645                    return Err(KernelProviderError::UnknownProvider { provider_id });
646                }
647                self.require_provider_binding(&provider_id, binding_id)?;
648                let closed_request_count =
649                    self.tool_engine.detach_provider_runtime(&provider_id)?;
650                self.provider_bindings.remove(&provider_id);
651                Ok(ProviderRuntimeTransition::Detached {
652                    closed_request_count,
653                })
654            }
655            ProviderRuntimeCommand::Observe {
656                binding_id,
657                observation,
658            } => {
659                let provider_id = observation.provider_id.clone();
660                if !self.tool_engine.provider_exists(&provider_id) {
661                    return Err(KernelProviderError::UnknownProvider { provider_id });
662                }
663                self.require_provider_binding(&provider_id, binding_id)?;
664                let operation_id = observation.operation_id;
665                let request_key = observation.request_key.clone();
666                match self.tool_engine.apply_observation(observation)? {
667                    CapabilityObservationDisposition::Applied => {
668                        Ok(ProviderRuntimeTransition::ObservationApplied {
669                            operation_id,
670                            request_key,
671                        })
672                    }
673                    CapabilityObservationDisposition::Ignored { reason } => {
674                        Ok(ProviderRuntimeTransition::ObservationIgnored {
675                            operation_id,
676                            request_key,
677                            reason,
678                        })
679                    }
680                }
681            }
682        }
683    }
684
685    fn require_provider_binding(
686        &self,
687        provider_id: &ToolProviderId,
688        requested: ProviderBindingId,
689    ) -> Result<(), KernelProviderError> {
690        let Some(current) = self.provider_bindings.get(provider_id).copied() else {
691            return Err(KernelProviderError::NotAttached {
692                provider_id: provider_id.clone(),
693            });
694        };
695        if current != requested {
696            return Err(KernelProviderError::BindingMismatch {
697                provider_id: provider_id.clone(),
698                current,
699                requested,
700            });
701        }
702        Ok(())
703    }
704
705    fn drain_bound_tool_effects(
706        &mut self,
707    ) -> Result<Vec<ProviderBoundCapabilityEffectEnvelope>, KernelIntegrationError> {
708        let effects = self.tool_engine.drain_effects();
709        let mut bound = Vec::with_capacity(effects.len());
710        for effect in effects {
711            let Some(binding_id) = self.provider_bindings.get(&effect.provider_id).copied() else {
712                return Err(KernelIntegrationError::ToolEffectProviderUnbound {
713                    operation_id: effect.operation_id,
714                    provider_id: effect.provider_id,
715                });
716            };
717            bound.push(ProviderBoundCapabilityEffectEnvelope { binding_id, effect });
718        }
719        Ok(bound)
720    }
721
722    fn advance_backend_clock(&mut self) -> Result<(), KernelIntegrationError> {
723        let next_tick = self.logical_tick.checked_add(1).ok_or(
724            KernelIntegrationError::LogicalTickExhausted {
725                current_tick: self.logical_tick,
726            },
727        )?;
728        let next_revision = self.backend_revision.checked_add(1).ok_or(
729            KernelIntegrationError::BackendRevisionExhausted {
730                current_revision: self.backend_revision,
731            },
732        )?;
733        self.tool_engine
734            .advance_time(next_tick)
735            .map_err(|source| KernelIntegrationError::ToolClock { source })?;
736        self.logical_tick = next_tick;
737        self.backend_revision = next_revision;
738        Ok(())
739    }
740
741    fn sync_or_block(
742        &mut self,
743        instance_id: AgentInstanceId,
744        tool_lane_open: &mut bool,
745        integration_errors: &mut Vec<KernelIntegrationError>,
746    ) {
747        if let Err(error) = self.sync_control_instance(instance_id) {
748            *tool_lane_open = false;
749            integration_errors.push(error);
750        }
751    }
752
753    fn control_health_error(&self) -> Option<KernelIntegrationError> {
754        terminal_control_health_error(self.engine.health())
755    }
756
757    fn block_on_control_health(
758        &self,
759        control_lane_open: &mut bool,
760        tool_lane_open: &mut bool,
761        integration_errors: &mut Vec<KernelIntegrationError>,
762    ) {
763        block_lanes_on_control_health(
764            self.engine.health(),
765            control_lane_open,
766            tool_lane_open,
767            integration_errors,
768        );
769    }
770
771    fn reconcile_or_block(
772        &mut self,
773        tool_lane_open: &mut bool,
774        integration_errors: &mut Vec<KernelIntegrationError>,
775    ) {
776        let control_instance_ids = self.engine.session_instance_ids().collect::<BTreeSet<_>>();
777        for instance_id in &control_instance_ids {
778            self.sync_or_block(*instance_id, tool_lane_open, integration_errors);
779        }
780        let tool_instance_ids = self.tool_engine.instance_ids().collect::<Vec<_>>();
781        for instance_id in tool_instance_ids {
782            if !control_instance_ids.contains(&instance_id) {
783                self.sync_or_block(instance_id, tool_lane_open, integration_errors);
784            }
785        }
786    }
787
788    fn sync_control_instance(
789        &mut self,
790        instance_id: AgentInstanceId,
791    ) -> Result<(), KernelIntegrationError> {
792        let Some(session) = self.engine.session_snapshot(instance_id).cloned() else {
793            self.tool_engine
794                .remove_instance(instance_id)
795                .map_err(|source| KernelIntegrationError::ToolInstanceSync {
796                    instance_id,
797                    source,
798                })?;
799            return Ok(());
800        };
801
802        self.tool_engine
803            .set_generation(instance_id, session.generation)
804            .map_err(|source| KernelIntegrationError::ToolInstanceSync {
805                instance_id,
806                source,
807            })?;
808        let state = if session.status == SessionStatus::Running {
809            ToolInstanceState::Active
810        } else {
811            ToolInstanceState::Inactive
812        };
813        self.tool_engine
814            .set_instance_state(instance_id, session.generation, state)
815            .map_err(|source| KernelIntegrationError::ToolInstanceSync {
816                instance_id,
817                source,
818            })
819    }
820
821    fn blocked_step(
822        &self,
823        ingress: Vec<BackendIngress>,
824        reason: KernelIntegrationError,
825    ) -> KernelStep {
826        let mut command_outcomes = Vec::new();
827        let mut ingress_outcomes = Vec::new();
828        for item in ingress {
829            match item {
830                BackendIngress::Control(command) => {
831                    let outcome = CommandOutcome {
832                        command_id: command.id,
833                        result: Err(KernelCommandError::IntegrationBlocked {
834                            reason: reason.clone(),
835                        }),
836                    };
837                    command_outcomes.push(outcome.clone());
838                    ingress_outcomes.push(BackendIngressOutcome::Control(outcome));
839                }
840                BackendIngress::ToolRequest(request) => {
841                    ingress_outcomes.push(BackendIngressOutcome::ToolRequest(ToolRequestOutcome {
842                        request_key: request.key(),
843                        accepted_sequence: None,
844                        result: Err(KernelToolError::IntegrationBlocked),
845                    }));
846                }
847                BackendIngress::ToolAuthority(authority) => {
848                    ingress_outcomes.push(BackendIngressOutcome::ToolAuthority(
849                        ToolAuthorityCommandOutcome {
850                            sequence: authority.sequence,
851                            result: Err(KernelToolError::IntegrationBlocked),
852                        },
853                    ));
854                }
855                BackendIngress::ToolProvider(envelope) => {
856                    let (binding_id, provider_id) = provider_runtime_subject(&envelope.command);
857                    ingress_outcomes.push(BackendIngressOutcome::ToolProvider(
858                        ProviderRuntimeCommandOutcome {
859                            sequence: envelope.sequence,
860                            binding_id,
861                            provider_id,
862                            result: Err(KernelProviderError::IntegrationBlocked),
863                        },
864                    ));
865                }
866            }
867        }
868        let backend_snapshot = self.backend_snapshot();
869        let snapshot = (*backend_snapshot.control).clone();
870        let tool_completions = CapabilityCompletionBatch {
871            completions: Vec::new(),
872            dropped_since_last_drain: 0,
873            total_dropped: backend_snapshot.tools.dropped_completions,
874            next_sequence: backend_snapshot.tools.next_completion_sequence,
875            sequence_exhausted: backend_snapshot.tools.completion_sequence_exhausted,
876        };
877
878        KernelStep {
879            command_outcomes,
880            effects: Vec::new(),
881            snapshot,
882            events: Vec::new(),
883            ingress_outcomes,
884            tool_effects: Vec::new(),
885            tool_completions,
886            backend_snapshot,
887            integration_errors: vec![reason],
888        }
889    }
890
891    fn apply_validated_command(
892        &mut self,
893        mut command: CommandEnvelope,
894    ) -> Result<(), KernelCommandError> {
895        if let ControlCommand::Register {
896            agent_id,
897            transport,
898            ..
899        } = &command.command
900        {
901            let Some(spec) = self.catalog.get(agent_id) else {
902                return Err(KernelCommandError::UnknownAgent {
903                    agent_id: agent_id.clone(),
904                });
905            };
906            let supported = match transport {
907                TransportKind::Pty => spec.capabilities.transports.pty,
908                TransportKind::Pipe => spec.capabilities.transports.pipe.is_some(),
909                TransportKind::Acp => spec.capabilities.transports.acp.is_some(),
910            };
911            if !supported {
912                return Err(KernelCommandError::UnsupportedTransport {
913                    agent_id: agent_id.clone(),
914                    transport: *transport,
915                });
916            }
917        }
918        if let ControlCommand::SendInput {
919            instance_id,
920            action: InputAction::AgentCommand(_),
921        } = &command.command
922        {
923            if let Some(session) = self.engine.session_snapshot(*instance_id) {
924                let supports_agent_commands = self
925                    .catalog
926                    .get(&session.agent_id)
927                    .is_some_and(|spec| spec.capabilities.agent_commands.is_some());
928                if !supports_agent_commands {
929                    return Err(KernelCommandError::UnsupportedCapability {
930                        agent_id: session.agent_id.clone(),
931                        capability: "agent-commands",
932                    });
933                }
934            }
935        }
936        if let ControlCommand::DiscoverHistory { instance_id, .. }
937        | ControlCommand::LoadHistory { instance_id, .. } = &command.command
938        {
939            if let Some(session) = self.engine.session_snapshot(*instance_id) {
940                let supports_history = self
941                    .catalog
942                    .get(&session.agent_id)
943                    .is_some_and(|spec| spec.capabilities.adapters.history.is_some());
944                if !supports_history {
945                    return Err(KernelCommandError::UnsupportedCapability {
946                        agent_id: session.agent_id.clone(),
947                        capability: "history",
948                    });
949                }
950            }
951        }
952        if let ControlCommand::ProbeCapabilities { instance_id, .. } = &command.command {
953            if let Some(session) = self.engine.session_snapshot(*instance_id) {
954                let spec = self
955                    .catalog
956                    .get(&session.agent_id)
957                    .expect("registered agent must remain in kernel catalog");
958                if spec.capabilities.adapters.capability_probe.is_none() {
959                    return Err(KernelCommandError::UnsupportedCapability {
960                        agent_id: session.agent_id.clone(),
961                        capability: "capability-probe",
962                    });
963                }
964                resolve_capability_probe_for(spec).map_err(|error| {
965                    KernelCommandError::InvalidCapabilityProbe {
966                        agent_id: session.agent_id.clone(),
967                        message: error.to_string(),
968                    }
969                })?;
970            }
971        }
972        if let ControlCommand::Resume { instance_id, .. } = &command.command {
973            if let Some(session) = self.engine.session_snapshot(*instance_id) {
974                let supports_resume = self
975                    .catalog
976                    .get(&session.agent_id)
977                    .is_some_and(|spec| spec.capabilities.adapters.resume.is_some());
978                if !supports_resume
979                    || !matches!(session.transport, TransportKind::Pty | TransportKind::Pipe)
980                {
981                    return Err(KernelCommandError::UnsupportedCapability {
982                        agent_id: session.agent_id.clone(),
983                        capability: "resume",
984                    });
985                }
986            }
987        }
988        if let ControlCommand::Start {
989            instance_id,
990            request,
991            ..
992        } = &mut command.command
993        {
994            if let Some(session) = self.engine.session_snapshot(*instance_id) {
995                let spec = self
996                    .catalog
997                    .get(&session.agent_id)
998                    .expect("registered agent must remain in kernel catalog");
999                let one_shot = spec
1000                    .capabilities
1001                    .transports
1002                    .pipe
1003                    .as_ref()
1004                    .filter(|transport| transport.protocol == PipeProtocol::OneShotText);
1005                if session.transport == TransportKind::Pipe && one_shot.is_some() {
1006                    let prompt = request.initial_prompt.as_deref().unwrap_or_default();
1007                    let binding = spec
1008                        .capabilities
1009                        .adapters
1010                        .one_shot
1011                        .as_ref()
1012                        .expect("validated one-shot transport binding");
1013                    let resolved = resolve_one_shot_plan(
1014                        &binding.id,
1015                        &spec.launch,
1016                        prompt,
1017                        request.session_options.as_ref(),
1018                    )
1019                    .map_err(|error| {
1020                        KernelCommandError::InvalidSessionOptions {
1021                            agent_id: session.agent_id.clone(),
1022                            message: error.to_string(),
1023                        }
1024                    })?;
1025                    request.session_options = Some(resolved.applied);
1026                } else if let Some(session_options) = &request.session_options {
1027                    if session.transport != TransportKind::Pty
1028                        || spec.capabilities.adapters.session_options.is_none()
1029                    {
1030                        return Err(KernelCommandError::UnsupportedCapability {
1031                            agent_id: session.agent_id.clone(),
1032                            capability: "pty-session-options",
1033                        });
1034                    }
1035                    let resolved = resolve_session_option_launch_for(spec, session_options, &[])
1036                        .map_err(|error| KernelCommandError::InvalidSessionOptions {
1037                            agent_id: session.agent_id.clone(),
1038                            message: error.to_string(),
1039                        })?;
1040                    request.session_options = resolved.applied;
1041                }
1042            }
1043        }
1044        if let ControlCommand::IngestProvider {
1045            instance_id,
1046            source,
1047            ..
1048        } = &command.command
1049        {
1050            if let Some(session) = self.engine.session_snapshot(*instance_id) {
1051                let spec = self
1052                    .catalog
1053                    .get(&session.agent_id)
1054                    .expect("registered agent must remain in kernel catalog");
1055                if declared_provider_binding(spec, source) != Some(&source.binding) {
1056                    return Err(KernelCommandError::InvalidProviderSource {
1057                        agent_id: session.agent_id.clone(),
1058                        family: source.family,
1059                        adapter_id: source.binding.id.to_string(),
1060                        revision: source.binding.revision.clone(),
1061                    });
1062                }
1063            }
1064        }
1065        self.engine.apply_command(command).map_err(Into::into)
1066    }
1067}
1068
1069fn provider_runtime_subject(
1070    command: &ProviderRuntimeCommand,
1071) -> (ProviderBindingId, ToolProviderId) {
1072    match command {
1073        ProviderRuntimeCommand::Attach {
1074            binding_id,
1075            provider_id,
1076        }
1077        | ProviderRuntimeCommand::Detach {
1078            binding_id,
1079            provider_id,
1080        } => (*binding_id, provider_id.clone()),
1081        ProviderRuntimeCommand::Observe {
1082            binding_id,
1083            observation,
1084        } => (*binding_id, observation.provider_id.clone()),
1085    }
1086}
1087
1088fn terminal_control_health_error(health: ControlHealth) -> Option<KernelIntegrationError> {
1089    (health.operation_id_exhausted
1090        || health.event_sequence_exhausted
1091        || health.revision_exhausted
1092        || health.provider_sequence_exhausted_sessions > 0)
1093        .then_some(KernelIntegrationError::ControlHealthExhausted { health })
1094}
1095
1096fn block_lanes_on_control_health(
1097    health: ControlHealth,
1098    control_lane_open: &mut bool,
1099    tool_lane_open: &mut bool,
1100    integration_errors: &mut Vec<KernelIntegrationError>,
1101) {
1102    let Some(error) = terminal_control_health_error(health) else {
1103        return;
1104    };
1105    *control_lane_open = false;
1106    *tool_lane_open = false;
1107    if !integration_errors.contains(&error) {
1108        integration_errors.push(error);
1109    }
1110}
1111
1112fn declared_provider_binding<'a>(
1113    spec: &'a gate4agent_catalog::AgentSpec,
1114    source: &ProviderSource,
1115) -> Option<&'a AdapterBinding> {
1116    match source.family {
1117        AdapterFamily::PtySemantic => spec.capabilities.transports.pty_adapter.as_ref(),
1118        AdapterFamily::Pipe => {
1119            let transport_binding = spec
1120                .capabilities
1121                .transports
1122                .pipe
1123                .as_ref()
1124                .map(|transport| &transport.adapter);
1125            transport_binding
1126                .filter(|binding| *binding == &source.binding)
1127                .or_else(|| {
1128                    spec.capabilities
1129                        .adapters
1130                        .pty_sidecar
1131                        .as_ref()
1132                        .filter(|binding| *binding == &source.binding)
1133                })
1134        }
1135        AdapterFamily::Acp => spec
1136            .capabilities
1137            .transports
1138            .acp
1139            .as_ref()
1140            .map(|transport| &transport.adapter),
1141        AdapterFamily::OneShot => spec.capabilities.adapters.one_shot.as_ref(),
1142        AdapterFamily::Hook => spec.capabilities.adapters.hook.as_ref(),
1143        AdapterFamily::History
1144        | AdapterFamily::Resume
1145        | AdapterFamily::SessionOptions
1146        | AdapterFamily::CapabilityProbe
1147        | AdapterFamily::ManagedHook => None,
1148    }
1149}
1150
1151impl Default for Gate4AgentKernel {
1152    fn default() -> Self {
1153        Self::with_builtin_catalog()
1154    }
1155}
1156
1157#[cfg(test)]
1158mod tests {
1159    use super::*;
1160    use gate4agent_tool_protocol::{
1161        CancellationDisposition, CapabilityClass, CapabilityDescriptor, CapabilityObservation,
1162        CapabilityObservationEnvelope, CapabilityOwner, CapabilityRequestId,
1163        CapabilityRequestInput, CapabilityResult, CapabilityResultDelivery,
1164        CapabilityResultMetadata, CapabilityTerminalOutcome, ConsumerBoundCapabilityRequest,
1165        ConsumerId, GrantMode, PolicyDenial, PolicyGrant, PolicyKey, ResourceScopeId, ToolActorId,
1166        ToolAuthorityCommand, ToolCapabilityId, ToolProviderId,
1167    };
1168    use gate4agent_types::{
1169        AgentInstanceId, ApprovalLevel, CapabilityProbeRequest, ControlObservation, HistoryQuery,
1170        ObservationEnvelope, ProviderActivity, ProviderEvent, ProviderRuntimePolicy,
1171        ProviderSource, ResumeLaunchRequest, ResumeTarget, SessionGeneration,
1172        SessionOptionSelection, SessionStatus, StartRequest, TerminalSize, TransportKind,
1173    };
1174
1175    fn instance() -> AgentInstanceId {
1176        AgentInstanceId(11)
1177    }
1178
1179    fn verified_runtime_policy() -> ProviderRuntimePolicy {
1180        ProviderRuntimePolicy::new(true, true, true, true, true, true).unwrap()
1181    }
1182
1183    fn command(id: u64, command: ControlCommand) -> CommandEnvelope {
1184        CommandEnvelope {
1185            id: CommandId(id),
1186            command,
1187        }
1188    }
1189
1190    fn register(id: u64, agent: &str) -> CommandEnvelope {
1191        command(
1192            id,
1193            ControlCommand::Register {
1194                instance_id: instance(),
1195                agent_id: AgentId::new(agent).unwrap(),
1196                transport: TransportKind::Pty,
1197            },
1198        )
1199    }
1200
1201    fn tool_consumer() -> ConsumerId {
1202        ConsumerId::new("kernel-test-consumer").unwrap()
1203    }
1204
1205    fn tool_actor() -> ToolActorId {
1206        ToolActorId::new("kernel-test-actor").unwrap()
1207    }
1208
1209    fn tool_provider_id() -> ToolProviderId {
1210        ToolProviderId::new("kernel-browser-provider").unwrap()
1211    }
1212
1213    fn tool_capability_id() -> ToolCapabilityId {
1214        ToolCapabilityId::new("browser.snapshot").unwrap()
1215    }
1216
1217    fn tool_resource_scope() -> ResourceScopeId {
1218        ResourceScopeId::new("active-page").unwrap()
1219    }
1220
1221    /// `cursor-fixture`, `amp-fixture`, `no-resume-fixture`, and
1222    /// `pty-sidecar-fixture` are not catalog ids. `cursor` and `amp` are
1223    /// reference rows now, so these fixtures keep separate ids. Kernel
1224    /// adapter-family gating
1225    /// tests need provider capability shapes the four-member fleet does not
1226    /// naturally offer on its own -- e.g. a Pipe transport still resolving
1227    /// through the legacy `OneShotText` one-shot path (every fleet member's
1228    /// own Pipe transport is `StructuredJsonl`), a provider missing its
1229    /// History adapter, a provider with no Resume adapter, or a bare PTY
1230    /// sidecar binding -- so this clones a real fleet spec (`codex`, which
1231    /// carries PTY, History, and Resume) as the base and gives it a fixture
1232    /// identity, leaving every adapter binding it inherits pointed at a
1233    /// real, globally-registered implementation.
1234    fn legacy_fixture(id: &str) -> gate4agent_types::AgentSpec {
1235        let mut spec = builtin_registry().get_by_id("codex").unwrap().clone();
1236        spec.id = AgentId::new(id).unwrap();
1237        spec.detection.command = id.to_owned();
1238        spec.detection.aliases = Vec::new();
1239        spec.launch.program = id.to_owned();
1240        spec.expected_processes = vec![gate4agent_types::ProcessMatcher::Exact {
1241            name: id.to_owned(),
1242        }];
1243        spec
1244    }
1245
1246    /// `cursor`, standing in as the one legacy fixture that is both
1247    /// one-shot by Pipe and carries a session-option adapter -- bound to
1248    /// `claude`'s real one-shot implementation, the same resolver the
1249    /// kernel itself calls.
1250    fn legacy_one_shot_fixture_catalog() -> AgentRegistry {
1251        let claude = builtin_registry().get_by_id("claude").unwrap();
1252        let one_shot = claude.capabilities.adapters.one_shot.clone().unwrap();
1253        let session_options = claude.capabilities.adapters.session_options.clone();
1254        let mut cursor = legacy_fixture("cursor-fixture");
1255        cursor.capabilities.adapters.one_shot = Some(one_shot.clone());
1256        cursor.capabilities.adapters.session_options = session_options;
1257        cursor.capabilities.transports.pipe = Some(gate4agent_types::PipeTransportSpec {
1258            adapter: one_shot,
1259            protocol: PipeProtocol::OneShotText,
1260            launch_override: None,
1261            prompt_delivery: gate4agent_types::PipePromptDelivery::None,
1262        });
1263        AgentRegistry::new(builtin_registry().iter().cloned().chain([cursor])).unwrap()
1264    }
1265
1266    /// `pty-sidecar-fixture`, carrying a PTY sidecar binding reusing
1267    /// `claude`'s real, globally-registered Pipe binding -- the kernel's
1268    /// ingress gate only compares bindings for exact equality, so which
1269    /// real family member it is borrowed from is not load-bearing.
1270    fn legacy_pty_sidecar_fixture_catalog() -> AgentRegistry {
1271        let sidecar = builtin_registry()
1272            .get_by_id("claude")
1273            .unwrap()
1274            .capabilities
1275            .transports
1276            .pipe
1277            .clone()
1278            .unwrap()
1279            .adapter;
1280        let mut sidecar_fixture = legacy_fixture("pty-sidecar-fixture");
1281        // Cleared, not just left inherited from the `codex` skeleton: the
1282        // ingress-exactness assertion below reuses `codex`'s own Pipe
1283        // binding as the "foreign" one, and `declared_provider_binding`
1284        // accepts a Pipe-family source matching EITHER the sidecar binding
1285        // or the transport's own adapter, so leaving this set would let the
1286        // "foreign" binding match right back through it.
1287        sidecar_fixture.capabilities.transports.pipe = None;
1288        sidecar_fixture.capabilities.adapters.pty_sidecar = Some(sidecar);
1289        AgentRegistry::new(builtin_registry().iter().cloned().chain([sidecar_fixture])).unwrap()
1290    }
1291
1292    /// `amp`, carrying no History adapter.
1293    fn legacy_no_history_fixture_catalog() -> AgentRegistry {
1294        let mut amp = legacy_fixture("amp-fixture");
1295        amp.capabilities.adapters.history = None;
1296        AgentRegistry::new(builtin_registry().iter().cloned().chain([amp])).unwrap()
1297    }
1298
1299    /// `no-resume-fixture`, carrying every adapter family except Resume.
1300    fn legacy_no_resume_fixture_catalog() -> AgentRegistry {
1301        let mut no_resume_fixture = legacy_fixture("no-resume-fixture");
1302        no_resume_fixture.capabilities.adapters.resume = None;
1303        AgentRegistry::new(builtin_registry().iter().cloned().chain([no_resume_fixture])).unwrap()
1304    }
1305
1306    fn tool_provider() -> CapabilityProviderDescriptor {
1307        CapabilityProviderDescriptor {
1308            id: tool_provider_id(),
1309            owner: CapabilityOwner::Gate,
1310            capabilities: vec![CapabilityDescriptor::new(
1311                tool_capability_id(),
1312                CapabilityClass::Browser,
1313                "Return active page metadata",
1314            )
1315            .unwrap()],
1316        }
1317    }
1318
1319    fn other_tool_provider_id() -> ToolProviderId {
1320        ToolProviderId::new("kernel-browser-provider-secondary").unwrap()
1321    }
1322
1323    fn other_tool_provider() -> CapabilityProviderDescriptor {
1324        CapabilityProviderDescriptor {
1325            id: other_tool_provider_id(),
1326            owner: CapabilityOwner::Gate,
1327            capabilities: vec![CapabilityDescriptor::new(
1328                ToolCapabilityId::new("browser.snapshot.secondary").unwrap(),
1329                CapabilityClass::Browser,
1330                "Return secondary page metadata",
1331            )
1332            .unwrap()],
1333        }
1334    }
1335
1336    fn tool_request(
1337        local_id: u64,
1338        generation: SessionGeneration,
1339    ) -> ConsumerBoundCapabilityRequest {
1340        ConsumerBoundCapabilityRequest::new(
1341            tool_consumer(),
1342            tool_actor(),
1343            CapabilityRequestInput {
1344                local_id: CapabilityRequestId(local_id),
1345                instance_id: instance(),
1346                generation,
1347                provider_id: tool_provider_id(),
1348                capability_id: tool_capability_id(),
1349                resource_scope_id: tool_resource_scope(),
1350                approval_summary: "Read active page metadata".to_owned(),
1351                deadline_tick: 100,
1352                payload: br#"{"scope":"active-page"}"#.to_vec(),
1353            },
1354        )
1355    }
1356
1357    fn provider_bound_tool_request(
1358        binding_id: Option<ProviderBindingId>,
1359        request: ConsumerBoundCapabilityRequest,
1360    ) -> ProviderBoundCapabilityRequest {
1361        ProviderBoundCapabilityRequest::new(binding_id, request)
1362    }
1363
1364    fn tool_policy_grant(generation: SessionGeneration) -> PolicyGrant {
1365        PolicyGrant {
1366            key: PolicyKey {
1367                consumer_id: tool_consumer(),
1368                actor_id: tool_actor(),
1369                instance_id: instance(),
1370                generation,
1371                provider_id: tool_provider_id(),
1372                capability_id: tool_capability_id(),
1373                resource_scope_id: tool_resource_scope(),
1374            },
1375            mode: GrantMode::Allow,
1376        }
1377    }
1378
1379    fn tool_grant(generation: SessionGeneration, sequence: u64) -> ToolAuthorityEnvelope {
1380        ToolAuthorityEnvelope {
1381            sequence,
1382            command: ToolAuthorityCommand::SetGrant {
1383                grant: tool_policy_grant(generation),
1384            },
1385        }
1386    }
1387
1388    fn provider_runtime(sequence: u64, command: ProviderRuntimeCommand) -> BackendIngress {
1389        BackendIngress::ToolProvider(ProviderRuntimeEnvelope {
1390            sequence,
1391            command,
1392        })
1393    }
1394
1395    fn attach_tool_provider(kernel: &mut Gate4AgentKernel, sequence: u64) -> ProviderBindingId {
1396        let binding_id = ProviderBindingId(sequence);
1397        let step = kernel.step_control_plane(
1398            [provider_runtime(
1399                sequence,
1400                ProviderRuntimeCommand::Attach {
1401                    binding_id,
1402                    provider_id: tool_provider_id(),
1403                },
1404            )],
1405            [],
1406        );
1407        assert!(matches!(
1408            &step.ingress_outcomes[0],
1409            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
1410                result: Ok(ProviderRuntimeTransition::Attached),
1411                ..
1412            })
1413        ));
1414        binding_id
1415    }
1416
1417    fn successful_observation(
1418        effect: &ProviderBoundCapabilityEffectEnvelope,
1419    ) -> CapabilityObservationEnvelope {
1420        CapabilityObservationEnvelope {
1421            operation_id: effect.effect.operation_id,
1422            request_key: effect.effect.request_key.clone(),
1423            instance_id: effect.effect.instance_id,
1424            generation: effect.effect.generation,
1425            provider_id: effect.effect.provider_id.clone(),
1426            observation: CapabilityObservation::Succeeded {
1427                result: CapabilityResult {
1428                    metadata: CapabilityResultMetadata {
1429                        byte_len: 2,
1430                        media_type: Some("application/json".to_owned()),
1431                        truncated: false,
1432                        redacted_summary: Some("provider result".to_owned()),
1433                    },
1434                    delivery: CapabilityResultDelivery::Inline {
1435                        bytes: b"{}".to_vec(),
1436                    },
1437                },
1438            },
1439        }
1440    }
1441
1442    fn start_running(kernel: &mut Gate4AgentKernel) -> SessionGeneration {
1443        let starting = kernel.step(
1444            [
1445                register(1, "claude"),
1446                command(
1447                    2,
1448                    ControlCommand::Start {
1449                        instance_id: instance(),
1450                        runtime_policy: verified_runtime_policy(),
1451                        request: StartRequest {
1452                            working_directory: ".".to_owned(),
1453                            terminal_size: TerminalSize {
1454                                rows: 24,
1455                                columns: 80,
1456                            },
1457                            initial_prompt: None,
1458                            session_options: None,
1459                            approval_level: ApprovalLevel::default(),
1460                        },
1461                    },
1462                ),
1463            ],
1464            [],
1465        );
1466        let spawn = starting.effects[0].clone();
1467        let running = kernel.step(
1468            [],
1469            [ObservationEnvelope {
1470                operation_id: Some(spawn.operation_id),
1471                instance_id: spawn.instance_id,
1472                generation: spawn.generation,
1473                observation: ControlObservation::Spawned {
1474                    process_id: Some(123),
1475                },
1476            }],
1477        );
1478        assert!(running.integration_errors.is_empty());
1479        assert_eq!(running.snapshot.sessions[0].status, SessionStatus::Running);
1480        running.snapshot.sessions[0].generation
1481    }
1482
1483    #[test]
1484    fn unknown_provider_is_rejected_before_engine_mutation() {
1485        let mut kernel = Gate4AgentKernel::default();
1486        let step = kernel.step([register(1, "unknown-agent")], []);
1487
1488        assert!(matches!(
1489            step.command_outcomes[0].result,
1490            Err(KernelCommandError::UnknownAgent { .. })
1491        ));
1492        assert!(step.snapshot.sessions.is_empty());
1493        assert!(step.effects.is_empty());
1494        assert!(matches!(
1495            step.events[0].event,
1496            gate4agent_types::ControlEventKind::CommandRejected { .. }
1497        ));
1498    }
1499
1500    #[test]
1501    fn session_options_require_a_declared_pty_catalog_and_cross_the_effect_boundary() {
1502        let mut kernel = Gate4AgentKernel::default();
1503        kernel.step([register(1, "claude")], []);
1504        // `fastMode` is deliberately absent: unlike `cursor`'s (composed
1505        // into the model string), claude's has no `launch` application at
1506        // all, so it never reaches `applied` regardless of what is
1507        // selected -- only `effort` (a `--effort` flag) fully round-trips.
1508        let selection = SessionOptionSelection::new("opus").with_value("effort", "high");
1509        let accepted = kernel.step(
1510            [command(
1511                2,
1512                ControlCommand::Start {
1513                    instance_id: instance(),
1514                    runtime_policy: verified_runtime_policy(),
1515                    request: StartRequest {
1516                        working_directory: ".".to_owned(),
1517                        terminal_size: TerminalSize {
1518                            rows: 24,
1519                            columns: 80,
1520                        },
1521                        initial_prompt: None,
1522                        session_options: Some(selection.clone()),
1523                        approval_level: ApprovalLevel::default(),
1524                    },
1525                },
1526            )],
1527            [],
1528        );
1529        assert_eq!(accepted.command_outcomes[0].result, Ok(()));
1530        assert!(matches!(
1531            &accepted.effects[0].effect,
1532            gate4agent_types::ControlEffect::Spawn { request, .. }
1533                if request.session_options.as_ref() == Some(&selection)
1534        ));
1535
1536        let mut unsupported = Gate4AgentKernel::default();
1537        unsupported.step([register(1, "kimi")], []);
1538        let rejected = unsupported.step(
1539            [command(
1540                2,
1541                ControlCommand::Start {
1542                    instance_id: instance(),
1543                    runtime_policy: verified_runtime_policy(),
1544                    request: StartRequest {
1545                        working_directory: ".".to_owned(),
1546                        terminal_size: TerminalSize {
1547                            rows: 24,
1548                            columns: 80,
1549                        },
1550                        initial_prompt: None,
1551                        session_options: Some(SessionOptionSelection::new("opus")),
1552                        approval_level: ApprovalLevel::default(),
1553                    },
1554                },
1555            )],
1556            [],
1557        );
1558        assert!(matches!(
1559            rejected.command_outcomes[0].result,
1560            Err(KernelCommandError::UnsupportedCapability {
1561                capability: "pty-session-options",
1562                ..
1563            })
1564        ));
1565        assert!(rejected.effects.is_empty());
1566
1567        let mut expanded = Gate4AgentKernel::default();
1568        expanded.step([register(1, "claude")], []);
1569        let started = expanded.step(
1570            [command(
1571                2,
1572                ControlCommand::Start {
1573                    instance_id: instance(),
1574                    runtime_policy: verified_runtime_policy(),
1575                    request: StartRequest {
1576                        working_directory: ".".to_owned(),
1577                        terminal_size: TerminalSize {
1578                            rows: 24,
1579                            columns: 80,
1580                        },
1581                        initial_prompt: None,
1582                        session_options: Some(SessionOptionSelection::new("opus")),
1583                        approval_level: ApprovalLevel::default(),
1584                    },
1585                },
1586            )],
1587            [],
1588        );
1589        let expected = SessionOptionSelection::new("opus").with_value("effort", "high");
1590        assert_eq!(
1591            started.snapshot.sessions[0].session_options.as_ref(),
1592            Some(&expected)
1593        );
1594        assert!(matches!(
1595            &started.effects[0].effect,
1596            gate4agent_types::ControlEffect::Spawn { request, .. }
1597                if request.session_options.as_ref() == Some(&expected)
1598        ));
1599
1600        let mut pipe = Gate4AgentKernel::default();
1601        pipe.step(
1602            [command(
1603                1,
1604                ControlCommand::Register {
1605                    instance_id: instance(),
1606                    agent_id: AgentId::new("codex").unwrap(),
1607                    transport: TransportKind::Pipe,
1608                },
1609            )],
1610            [],
1611        );
1612        let rejected = pipe.step(
1613            [command(
1614                2,
1615                ControlCommand::Start {
1616                    instance_id: instance(),
1617                    runtime_policy: verified_runtime_policy(),
1618                    request: StartRequest {
1619                        working_directory: ".".to_owned(),
1620                        terminal_size: TerminalSize {
1621                            rows: 24,
1622                            columns: 80,
1623                        },
1624                        initial_prompt: Some("hello".to_owned()),
1625                        session_options: Some(SessionOptionSelection::new("gpt-5.5")),
1626                        approval_level: ApprovalLevel::default(),
1627                    },
1628                },
1629            )],
1630            [],
1631        );
1632        assert!(matches!(
1633            rejected.command_outcomes[0].result,
1634            Err(KernelCommandError::UnsupportedCapability {
1635                capability: "pty-session-options",
1636                ..
1637            })
1638        ));
1639    }
1640
1641    /// The one-shot pipe path fills in a provider's own session-option
1642    /// defaults when a `Start` names none, and the same resolved selection
1643    /// reaches the spawn effect.
1644    ///
1645    /// Subject is `cursor`, and it has to be: this used to drive the case
1646    /// with `claude`, which stopped being a one-shot provider when its pipe
1647    /// transport became `StructuredJsonl` (pinned, green, in
1648    /// `gate4agent-catalog`'s own builtin test). The kernel's one-shot
1649    /// branch is gated on `PipeProtocol::OneShotText`, so with `claude` it
1650    /// simply never ran and the test asserted defaults against a path it
1651    /// was no longer on -- red ever since, which is how a test stops being
1652    /// read. `cursor` is the one provider that is both one-shot by pipe and
1653    /// carries a session-option adapter, so it is the only subject that
1654    /// exercises what this test is named for.
1655    ///
1656    /// The expectation is derived from `resolve_one_shot_plan`, the same
1657    /// resolver the kernel calls, rather than frozen as a literal model
1658    /// name. A frozen literal is what rotted the previous version: the
1659    /// defaults belong to the catalog and move with it, while what this
1660    /// test is actually about -- that the kernel APPLIES them instead of
1661    /// leaving `session_options` at `None` -- does not.
1662    #[test]
1663    fn one_shot_pipe_defaults_and_validates_options_before_effect_creation() {
1664        let mut cursor = Gate4AgentKernel::new(legacy_one_shot_fixture_catalog());
1665        cursor.step(
1666            [command(
1667                1,
1668                ControlCommand::Register {
1669                    instance_id: instance(),
1670                    agent_id: AgentId::new("cursor-fixture").unwrap(),
1671                    transport: TransportKind::Pipe,
1672                },
1673            )],
1674            [],
1675        );
1676        let started = cursor.step(
1677            [command(
1678                2,
1679                ControlCommand::Start {
1680                    instance_id: instance(),
1681                    runtime_policy: verified_runtime_policy(),
1682                    request: StartRequest {
1683                        working_directory: ".".to_owned(),
1684                        terminal_size: TerminalSize {
1685                            rows: 24,
1686                            columns: 80,
1687                        },
1688                        initial_prompt: Some("summarize".to_owned()),
1689                        session_options: None,
1690                        approval_level: ApprovalLevel::default(),
1691                    },
1692                },
1693            )],
1694            [],
1695        );
1696        let spec = cursor
1697            .catalog()
1698            .get_by_id("cursor-fixture")
1699            .expect("cursor is a legacy fixture provider");
1700        let binding = spec
1701            .capabilities
1702            .adapters
1703            .one_shot
1704            .as_ref()
1705            .expect("cursor declares a one-shot adapter");
1706        let expected = resolve_one_shot_plan(&binding.id, &spec.launch, "summarize", None)
1707            .expect("cursor resolves its own defaults")
1708            .applied;
1709        // Stated on its own: the defect this guards against is the kernel
1710        // leaving the field untouched, and `assert_eq!` against a resolved
1711        // value would report that as a mismatch rather than as the absence
1712        // it is.
1713        assert!(started.snapshot.sessions[0].session_options.is_some());
1714        assert_eq!(
1715            started.snapshot.sessions[0].session_options.as_ref(),
1716            Some(&expected)
1717        );
1718        assert!(matches!(
1719            &started.effects[0].effect,
1720            gate4agent_types::ControlEffect::Spawn {
1721                transport: TransportKind::Pipe,
1722                request,
1723                ..
1724            } if request.session_options.as_ref() == Some(&expected)
1725        ));
1726
1727        let mut amp = Gate4AgentKernel::new(legacy_one_shot_fixture_catalog());
1728        amp.step(
1729            [command(
1730                3,
1731                ControlCommand::Register {
1732                    instance_id: instance(),
1733                    agent_id: AgentId::new("cursor-fixture").unwrap(),
1734                    transport: TransportKind::Pipe,
1735                },
1736            )],
1737            [],
1738        );
1739        let rejected = amp.step(
1740            [command(
1741                4,
1742                ControlCommand::Start {
1743                    instance_id: instance(),
1744                    runtime_policy: verified_runtime_policy(),
1745                    request: StartRequest {
1746                        working_directory: ".".to_owned(),
1747                        terminal_size: TerminalSize {
1748                            rows: 24,
1749                            columns: 80,
1750                        },
1751                        initial_prompt: Some("summarize".to_owned()),
1752                        session_options: Some(SessionOptionSelection::new("unknown-model")),
1753                        approval_level: ApprovalLevel::default(),
1754                    },
1755                },
1756            )],
1757            [],
1758        );
1759        assert!(matches!(
1760            rejected.command_outcomes[0].result,
1761            Err(KernelCommandError::InvalidSessionOptions { .. })
1762        ));
1763        assert!(rejected.effects.is_empty());
1764
1765        // `codex` drove this half until its pipe transport became
1766        // `StructuredJsonl` too, which routes it away from the one-shot
1767        // prompt validation the half exists to check.
1768        let mut missing_prompt = Gate4AgentKernel::new(legacy_one_shot_fixture_catalog());
1769        missing_prompt.step(
1770            [command(
1771                5,
1772                ControlCommand::Register {
1773                    instance_id: instance(),
1774                    agent_id: AgentId::new("cursor-fixture").unwrap(),
1775                    transport: TransportKind::Pipe,
1776                },
1777            )],
1778            [],
1779        );
1780        let rejected = missing_prompt.step(
1781            [command(
1782                6,
1783                ControlCommand::Start {
1784                    instance_id: instance(),
1785                    runtime_policy: verified_runtime_policy(),
1786                    request: StartRequest {
1787                        working_directory: ".".to_owned(),
1788                        terminal_size: TerminalSize {
1789                            rows: 24,
1790                            columns: 80,
1791                        },
1792                        initial_prompt: None,
1793                        session_options: None,
1794                        approval_level: ApprovalLevel::default(),
1795                    },
1796                },
1797            )],
1798            [],
1799        );
1800        assert!(matches!(
1801            rejected.command_outcomes[0].result,
1802            Err(KernelCommandError::InvalidSessionOptions { .. })
1803        ));
1804        assert!(rejected.effects.is_empty());
1805    }
1806
1807    /// Capability-probe existed to serve `cursor`'s `--list-models`, and
1808    /// `cursor` is not part of the fleet: no fleet provider declares this
1809    /// adapter, so the kernel rejects it before creating an effect for all
1810    /// four; and a provider that DOES declare a capability-probe binding
1811    /// still fails closed at resolution -- the binding is only valid
1812    /// against a consumer-extended registry (built locally, standing in for
1813    /// what the wider reference catalog used to provide), never the
1814    /// process-global one the kernel resolves against.
1815    #[test]
1816    fn capability_probe_is_unsupported_fleet_wide_and_fails_closed_on_an_unavailable_binding() {
1817        for id in ["claude", "codex", "grok", "kimi"] {
1818            let mut kernel = Gate4AgentKernel::default();
1819            kernel.step([register(1, id)], []);
1820            let rejected = kernel.step(
1821                [command(
1822                    2,
1823                    ControlCommand::ProbeCapabilities {
1824                        instance_id: instance(),
1825                        request: CapabilityProbeRequest {
1826                            working_directory: ".".to_owned(),
1827                        },
1828                    },
1829                )],
1830                [],
1831            );
1832            assert!(
1833                matches!(
1834                    rejected.command_outcomes[0].result,
1835                    Err(KernelCommandError::UnsupportedCapability {
1836                        capability: "capability-probe",
1837                        ..
1838                    })
1839                ),
1840                "{id}"
1841            );
1842            assert!(rejected.effects.is_empty(), "{id}");
1843        }
1844
1845        let probe_binding = gate4agent_types::AdapterBinding::new(
1846            gate4agent_types::AdapterId::new("cursor").unwrap(),
1847            "cursor-capability-probe/v1",
1848            gate4agent_types::AdapterVerification::Reference,
1849        )
1850        .unwrap();
1851        let local_adapters = gate4agent_catalog::AdapterRegistry::new(
1852            gate4agent_catalog::builtin_adapter_registry()
1853                .iter()
1854                .cloned()
1855                .chain([gate4agent_catalog::AdapterDescriptor {
1856                    family: AdapterFamily::CapabilityProbe,
1857                    binding: probe_binding.clone(),
1858                    agents: vec![AgentId::new("cursor-fixture").unwrap()],
1859                }]),
1860        )
1861        .unwrap();
1862        let mut cursor = legacy_fixture("cursor-fixture");
1863        cursor.capabilities.adapters.capability_probe = Some(probe_binding);
1864        let catalog = AgentRegistry::new_with_adapters(
1865            builtin_registry().iter().cloned().chain([cursor]),
1866            &local_adapters,
1867        )
1868        .unwrap();
1869        let mut kernel = Gate4AgentKernel::new(catalog);
1870        kernel.step([register(1, "cursor-fixture")], []);
1871        let rejected = kernel.step(
1872            [command(
1873                2,
1874                ControlCommand::ProbeCapabilities {
1875                    instance_id: instance(),
1876                    request: CapabilityProbeRequest {
1877                        working_directory: ".".to_owned(),
1878                    },
1879                },
1880            )],
1881            [],
1882        );
1883        assert!(matches!(
1884            rejected.command_outcomes[0].result,
1885            Err(KernelCommandError::InvalidCapabilityProbe { .. })
1886        ));
1887        assert!(rejected.effects.is_empty());
1888    }
1889
1890    #[test]
1891    fn external_provider_ingress_requires_the_declared_family_binding() {
1892        let mut kernel = Gate4AgentKernel::default();
1893        kernel.step([register(1, "grok")], []);
1894        let started = kernel.step(
1895            [command(
1896                2,
1897                ControlCommand::Start {
1898                    instance_id: instance(),
1899                    runtime_policy: verified_runtime_policy(),
1900                    request: StartRequest {
1901                        working_directory: ".".to_owned(),
1902                        terminal_size: TerminalSize {
1903                            rows: 24,
1904                            columns: 80,
1905                        },
1906                        initial_prompt: None,
1907                        session_options: None,
1908                        approval_level: ApprovalLevel::default(),
1909                    },
1910                },
1911            )],
1912            [],
1913        );
1914        let generation = started.snapshot.sessions[0].generation;
1915        // `AdapterFamily::Hook` is retired (owner ruling 2026-09-25) and
1916        // `declared_provider_binding` never resolves a binding for it
1917        // anymore. `Acp` is the only ingress-checked family grok declares
1918        // (it has no PtySemantic/Pipe/OneShot adapter), and it exercises the
1919        // same declared-binding validation this test is about.
1920        let grok_acp = kernel
1921            .catalog()
1922            .get_by_id("grok")
1923            .unwrap()
1924            .capabilities
1925            .transports
1926            .acp
1927            .clone()
1928            .unwrap()
1929            .adapter;
1930        let accepted = kernel.step(
1931            [command(
1932                3,
1933                ControlCommand::IngestProvider {
1934                    instance_id: instance(),
1935                    generation,
1936                    source: ProviderSource {
1937                        family: AdapterFamily::Acp,
1938                        binding: grok_acp,
1939                    },
1940                    source_sequence: 1,
1941                    events: vec![ProviderEvent::TurnStarted {
1942                        prompt: Some("ground external".to_owned()),
1943                    }],
1944                },
1945            )],
1946            [],
1947        );
1948        assert_eq!(accepted.command_outcomes[0].result, Ok(()));
1949        assert_eq!(
1950            accepted.snapshot.sessions[0].provider.activity,
1951            ProviderActivity::Working
1952        );
1953
1954        let kimi_acp = kernel
1955            .catalog()
1956            .get_by_id("kimi")
1957            .unwrap()
1958            .capabilities
1959            .transports
1960            .acp
1961            .clone()
1962            .unwrap()
1963            .adapter;
1964        let rejected = kernel.step(
1965            [command(
1966                4,
1967                ControlCommand::IngestProvider {
1968                    instance_id: instance(),
1969                    generation,
1970                    source: ProviderSource {
1971                        family: AdapterFamily::Acp,
1972                        binding: kimi_acp,
1973                    },
1974                    source_sequence: 2,
1975                    events: vec![ProviderEvent::Ready],
1976                },
1977            )],
1978            [],
1979        );
1980        assert!(matches!(
1981            rejected.command_outcomes[0].result,
1982            Err(KernelCommandError::InvalidProviderSource { .. })
1983        ));
1984    }
1985
1986    #[test]
1987    fn pipe_provider_ingress_accepts_exact_pty_sidecar_binding_only() {
1988        let mut kernel = Gate4AgentKernel::new(legacy_pty_sidecar_fixture_catalog());
1989        kernel.step([register(1, "pty-sidecar-fixture")], []);
1990        let started = kernel.step(
1991            [command(
1992                2,
1993                ControlCommand::Start {
1994                    instance_id: instance(),
1995                    runtime_policy: verified_runtime_policy(),
1996                    request: StartRequest {
1997                        working_directory: ".".to_owned(),
1998                        terminal_size: TerminalSize {
1999                            rows: 24,
2000                            columns: 80,
2001                        },
2002                        initial_prompt: None,
2003                        session_options: None,
2004                        approval_level: ApprovalLevel::default(),
2005                    },
2006                },
2007            )],
2008            [],
2009        );
2010        let generation = started.snapshot.sessions[0].generation;
2011        let sidecar = kernel
2012            .catalog()
2013            .get_by_id("pty-sidecar-fixture")
2014            .unwrap()
2015            .capabilities
2016            .adapters
2017            .pty_sidecar
2018            .clone()
2019            .unwrap();
2020        let accepted = kernel.step(
2021            [command(
2022                3,
2023                ControlCommand::IngestProvider {
2024                    instance_id: instance(),
2025                    generation,
2026                    source: ProviderSource {
2027                        family: AdapterFamily::Pipe,
2028                        binding: sidecar,
2029                    },
2030                    source_sequence: 1,
2031                    events: vec![ProviderEvent::Ready],
2032                },
2033            )],
2034            [],
2035        );
2036        assert_eq!(accepted.command_outcomes[0].result, Ok(()));
2037
2038        let foreign_pipe = kernel
2039            .catalog()
2040            .get_by_id("codex")
2041            .unwrap()
2042            .capabilities
2043            .transports
2044            .pipe
2045            .as_ref()
2046            .unwrap()
2047            .adapter
2048            .clone();
2049        let rejected = kernel.step(
2050            [command(
2051                4,
2052                ControlCommand::IngestProvider {
2053                    instance_id: instance(),
2054                    generation,
2055                    source: ProviderSource {
2056                        family: AdapterFamily::Pipe,
2057                        binding: foreign_pipe,
2058                    },
2059                    source_sequence: 2,
2060                    events: vec![ProviderEvent::Ready],
2061                },
2062            )],
2063            [],
2064        );
2065        assert!(matches!(
2066            rejected.command_outcomes[0].result,
2067            Err(KernelCommandError::InvalidProviderSource { .. })
2068        ));
2069    }
2070
2071    #[test]
2072    fn unsupported_provider_transport_is_rejected_before_registration() {
2073        let mut kernel = Gate4AgentKernel::default();
2074        let outcome = kernel.step(
2075            [command(
2076                1,
2077                ControlCommand::Register {
2078                    instance_id: instance(),
2079                    agent_id: AgentId::new("grok").unwrap(),
2080                    transport: TransportKind::Pipe,
2081                },
2082            )],
2083            [],
2084        );
2085        assert!(matches!(
2086            &outcome.command_outcomes[0].result,
2087            Err(KernelCommandError::UnsupportedTransport {
2088                transport: TransportKind::Pipe,
2089                ..
2090            })
2091        ));
2092        assert!(outcome.snapshot.sessions.is_empty());
2093    }
2094
2095    #[test]
2096    fn history_commands_require_a_declared_adapter_before_effect_creation() {
2097        let mut supported = Gate4AgentKernel::default();
2098        supported.step([register(1, "grok")], []);
2099        let accepted = supported.step(
2100            [command(
2101                2,
2102                ControlCommand::DiscoverHistory {
2103                    instance_id: instance(),
2104                    query: HistoryQuery {
2105                        working_directory: None,
2106                        limit: 8,
2107                    },
2108                },
2109            )],
2110            [],
2111        );
2112        assert_eq!(accepted.command_outcomes[0].result, Ok(()));
2113        assert!(matches!(
2114            accepted.effects[0].effect,
2115            gate4agent_types::ControlEffect::DiscoverHistory { .. }
2116        ));
2117
2118        // Subject is a legacy `amp` fixture with no history adapter. Every
2119        // fleet member now declares one (pinned in `gate4agent-adapters`'
2120        // own registry test), so this shape does not occur naturally in the
2121        // fleet anymore and needs a constructed fixture to stay exercised at
2122        // all.
2123        let mut unsupported = Gate4AgentKernel::new(legacy_no_history_fixture_catalog());
2124        unsupported.step([register(1, "amp-fixture")], []);
2125        let rejected = unsupported.step(
2126            [command(
2127                2,
2128                ControlCommand::DiscoverHistory {
2129                    instance_id: instance(),
2130                    query: HistoryQuery {
2131                        working_directory: None,
2132                        limit: 8,
2133                    },
2134                },
2135            )],
2136            [],
2137        );
2138        assert!(matches!(
2139            rejected.command_outcomes[0].result,
2140            Err(KernelCommandError::UnsupportedCapability {
2141                capability: "history",
2142                ..
2143            })
2144        ));
2145        assert!(rejected.effects.is_empty());
2146    }
2147
2148    #[test]
2149    fn resume_requires_a_declared_adapter_and_supported_transport_before_engine_mutation() {
2150        let resume = |initial_prompt| {
2151            command(
2152                2,
2153                ControlCommand::Resume {
2154                    instance_id: instance(),
2155                    target: ResumeTarget::CurrentProvider,
2156                    runtime_policy: verified_runtime_policy(),
2157                    request: ResumeLaunchRequest {
2158                        working_directory: ".".to_owned(),
2159                        terminal_size: TerminalSize {
2160                            rows: 24,
2161                            columns: 80,
2162                        },
2163                        initial_prompt,
2164                    },
2165                },
2166            )
2167        };
2168
2169        let mut unsupported = Gate4AgentKernel::new(legacy_no_resume_fixture_catalog());
2170        unsupported.step([register(1, "no-resume-fixture")], []);
2171        let rejected = unsupported.step([resume(None)], []);
2172        assert!(matches!(
2173            rejected.command_outcomes[0].result,
2174            Err(KernelCommandError::UnsupportedCapability {
2175                capability: "resume",
2176                ..
2177            })
2178        ));
2179        assert!(rejected.effects.is_empty());
2180
2181        let mut wrong_transport = Gate4AgentKernel::default();
2182        wrong_transport.step(
2183            [command(
2184                1,
2185                ControlCommand::Register {
2186                    instance_id: instance(),
2187                    agent_id: AgentId::new("codex").unwrap(),
2188                    transport: TransportKind::Pipe,
2189                },
2190            )],
2191            [],
2192        );
2193        let rejected = wrong_transport.step([resume(Some("continue".to_owned()))], []);
2194        assert!(matches!(
2195            rejected.command_outcomes[0].result,
2196            Err(KernelCommandError::Control(
2197                ControlError::MissingProviderSession
2198            ))
2199        ));
2200        assert!(rejected.effects.is_empty());
2201    }
2202
2203    #[test]
2204    fn undeclared_agent_commands_are_rejected_before_effect_creation() {
2205        let mut kernel = Gate4AgentKernel::default();
2206        let started = kernel.step(
2207            [
2208                register(1, "grok"),
2209                command(
2210                    2,
2211                    ControlCommand::Start {
2212                        instance_id: instance(),
2213                        runtime_policy: verified_runtime_policy(),
2214                        request: StartRequest {
2215                            working_directory: ".".to_owned(),
2216                            terminal_size: TerminalSize {
2217                                rows: 24,
2218                                columns: 80,
2219                            },
2220                            initial_prompt: None,
2221                            session_options: None,
2222                            approval_level: ApprovalLevel::default(),
2223                        },
2224                    },
2225                ),
2226            ],
2227            [],
2228        );
2229        let spawn = started.effects[0].clone();
2230        kernel.step(
2231            [],
2232            [ObservationEnvelope {
2233                operation_id: Some(spawn.operation_id),
2234                instance_id: spawn.instance_id,
2235                generation: spawn.generation,
2236                observation: ControlObservation::Spawned {
2237                    process_id: Some(123),
2238                },
2239            }],
2240        );
2241
2242        let rejected = kernel.step(
2243            [command(
2244                3,
2245                ControlCommand::SendInput {
2246                    instance_id: instance(),
2247                    action: InputAction::AgentCommand(gate4agent_types::AgentCommand {
2248                        agent_id: AgentId::new("grok").unwrap(),
2249                        name: "help".to_owned(),
2250                        arguments: Vec::new(),
2251                    }),
2252                },
2253            )],
2254            [],
2255        );
2256        assert!(matches!(
2257            rejected.command_outcomes[0].result,
2258            Err(KernelCommandError::UnsupportedCapability {
2259                capability: "agent-commands",
2260                ..
2261            })
2262        ));
2263        assert!(rejected.effects.is_empty());
2264    }
2265
2266    #[test]
2267    fn command_phase_precedes_observation_phase() {
2268        let mut kernel = Gate4AgentKernel::default();
2269        let first = kernel.step(
2270            [
2271                register(1, "claude"),
2272                command(
2273                    2,
2274                    ControlCommand::Start {
2275                        instance_id: instance(),
2276                        runtime_policy: verified_runtime_policy(),
2277                        request: StartRequest {
2278                            working_directory: ".".to_owned(),
2279                            terminal_size: TerminalSize {
2280                                rows: 24,
2281                                columns: 80,
2282                            },
2283                            initial_prompt: None,
2284                            session_options: None,
2285                            approval_level: ApprovalLevel::default(),
2286                        },
2287                    },
2288                ),
2289            ],
2290            [],
2291        );
2292        let spawn = first.effects[0].clone();
2293        let running = kernel.step(
2294            [],
2295            [ObservationEnvelope {
2296                operation_id: Some(spawn.operation_id),
2297                instance_id: spawn.instance_id,
2298                generation: spawn.generation,
2299                observation: ControlObservation::Spawned {
2300                    process_id: Some(123),
2301                },
2302            }],
2303        );
2304        assert_eq!(running.snapshot.sessions[0].status, SessionStatus::Running);
2305
2306        let raced = kernel.step(
2307            [command(
2308                3,
2309                ControlCommand::Stop {
2310                    instance_id: instance(),
2311                    force: false,
2312                },
2313            )],
2314            [ObservationEnvelope {
2315                operation_id: None,
2316                instance_id: instance(),
2317                generation: spawn.generation,
2318                observation: ControlObservation::ProcessExited {
2319                    exit_code: Some(0),
2320                    final_terminal: None,
2321                },
2322            }],
2323        );
2324
2325        assert!(raced.command_outcomes[0].result.is_ok());
2326        assert!(raced.effects.is_empty());
2327        assert_eq!(
2328            raced.snapshot.sessions[0].status,
2329            SessionStatus::Exited { exit_code: Some(0) }
2330        );
2331    }
2332
2333    #[test]
2334    fn identical_batches_produce_identical_step() {
2335        fn run() -> KernelStep {
2336            let mut kernel = Gate4AgentKernel::default();
2337            kernel.step(
2338                [
2339                    register(1, "claude"),
2340                    command(
2341                        2,
2342                        ControlCommand::Start {
2343                            instance_id: instance(),
2344                            runtime_policy: verified_runtime_policy(),
2345                            request: StartRequest {
2346                                working_directory: ".".to_owned(),
2347                                terminal_size: TerminalSize {
2348                                    rows: 24,
2349                                    columns: 80,
2350                                },
2351                                initial_prompt: None,
2352                                session_options: None,
2353                                approval_level: ApprovalLevel::default(),
2354                            },
2355                        },
2356                    ),
2357                ],
2358                [],
2359            )
2360        }
2361
2362        assert_eq!(run(), run());
2363    }
2364
2365    #[test]
2366    fn non_running_control_sessions_are_inactive_in_the_tool_engine() {
2367        let mut kernel =
2368            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2369                .unwrap();
2370        let registered = kernel.step([register(1, "claude")], []);
2371        assert_eq!(
2372            registered.backend_snapshot.tools.instance_states,
2373            vec![(instance(), ToolInstanceState::Inactive)]
2374        );
2375
2376        let starting = kernel.step(
2377            [command(
2378                2,
2379                ControlCommand::Start {
2380                    instance_id: instance(),
2381                    runtime_policy: verified_runtime_policy(),
2382                    request: StartRequest {
2383                        working_directory: ".".to_owned(),
2384                        terminal_size: TerminalSize {
2385                            rows: 24,
2386                            columns: 80,
2387                        },
2388                        initial_prompt: None,
2389                        session_options: None,
2390                        approval_level: ApprovalLevel::default(),
2391                    },
2392                },
2393            )],
2394            [],
2395        );
2396        assert_eq!(
2397            starting.backend_snapshot.tools.instance_states,
2398            vec![(instance(), ToolInstanceState::Inactive)]
2399        );
2400    }
2401
2402    #[test]
2403    fn tool_ingress_precedes_control_observation_activation() {
2404        let mut kernel =
2405            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2406                .unwrap();
2407        attach_tool_provider(&mut kernel, 1);
2408        let starting = kernel.step(
2409            [
2410                register(1, "claude"),
2411                command(
2412                    2,
2413                    ControlCommand::Start {
2414                        instance_id: instance(),
2415                        runtime_policy: verified_runtime_policy(),
2416                        request: StartRequest {
2417                            working_directory: ".".to_owned(),
2418                            terminal_size: TerminalSize {
2419                                rows: 24,
2420                                columns: 80,
2421                            },
2422                            initial_prompt: None,
2423                            session_options: None,
2424                            approval_level: ApprovalLevel::default(),
2425                        },
2426                    },
2427                ),
2428            ],
2429            [],
2430        );
2431        let spawn = starting.effects[0].clone();
2432        let step = kernel.step_control_plane(
2433            [BackendIngress::ToolRequest(provider_bound_tool_request(
2434                Some(ProviderBindingId(1)),
2435                tool_request(1, spawn.generation),
2436            ))],
2437            [ObservationEnvelope {
2438                operation_id: Some(spawn.operation_id),
2439                instance_id: spawn.instance_id,
2440                generation: spawn.generation,
2441                observation: ControlObservation::Spawned {
2442                    process_id: Some(123),
2443                },
2444            }],
2445        );
2446
2447        let BackendIngressOutcome::ToolRequest(outcome) = &step.ingress_outcomes[0] else {
2448            panic!("expected tool request outcome");
2449        };
2450        assert_eq!(
2451            outcome.result,
2452            Ok(PolicyDecision::Deny(PolicyDenial::InactiveInstance))
2453        );
2454        assert!(outcome.accepted_sequence.is_some());
2455        assert_eq!(
2456            step.backend_snapshot.tools.instance_states,
2457            vec![(instance(), ToolInstanceState::Active)]
2458        );
2459        assert!(step.tool_effects.is_empty());
2460        assert!(matches!(
2461            step.tool_completions.completions[0].outcome,
2462            CapabilityTerminalOutcome::PolicyDenied {
2463                reason: PolicyDenial::InactiveInstance
2464            }
2465        ));
2466    }
2467
2468    #[test]
2469    fn ordered_authority_and_request_outcomes_are_exactly_correlated() {
2470        let mut kernel =
2471            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2472                .unwrap();
2473        attach_tool_provider(&mut kernel, 1);
2474        let generation = start_running(&mut kernel);
2475        let request = tool_request(7, generation);
2476        let request_key = request.key();
2477        let step = kernel.step_control_plane(
2478            [
2479                BackendIngress::ToolAuthority(tool_grant(generation, 1)),
2480                BackendIngress::ToolRequest(provider_bound_tool_request(
2481                    Some(ProviderBindingId(1)),
2482                    request,
2483                )),
2484            ],
2485            [],
2486        );
2487
2488        assert!(matches!(
2489            &step.ingress_outcomes[0],
2490            BackendIngressOutcome::ToolAuthority(ToolAuthorityCommandOutcome {
2491                sequence: 1,
2492                result: Ok(ToolAuthorityOutcome::GrantSet),
2493            })
2494        ));
2495        let BackendIngressOutcome::ToolRequest(outcome) = &step.ingress_outcomes[1] else {
2496            panic!("expected tool request outcome");
2497        };
2498        assert_eq!(outcome.request_key, request_key);
2499        assert!(outcome.accepted_sequence.is_some());
2500        assert_eq!(outcome.result, Ok(PolicyDecision::Allow));
2501        assert_eq!(step.tool_effects.len(), 1);
2502        assert_eq!(step.tool_effects[0].effect.request_key, request_key);
2503
2504        let regressed = kernel.step_control_plane(
2505            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2506            [],
2507        );
2508        assert!(matches!(
2509            &regressed.ingress_outcomes[0],
2510            BackendIngressOutcome::ToolAuthority(ToolAuthorityCommandOutcome {
2511                sequence: 1,
2512                result: Err(KernelToolError::Engine(
2513                    ToolEngineError::AuthoritySequenceRegressed {
2514                        current: 1,
2515                        requested: 1,
2516                    }
2517                )),
2518            })
2519        ));
2520    }
2521
2522    #[test]
2523    fn stop_fences_queued_tool_work_then_remove_register_advances_generation() {
2524        let mut kernel =
2525            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2526                .unwrap();
2527        attach_tool_provider(&mut kernel, 1);
2528        let generation = start_running(&mut kernel);
2529        let granted = kernel.step_control_plane(
2530            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2531            [],
2532        );
2533        assert!(granted.integration_errors.is_empty());
2534        let request = tool_request(9, generation);
2535        let request_key = request.key();
2536
2537        let stopped = kernel.step_control_plane(
2538            [
2539                BackendIngress::ToolRequest(provider_bound_tool_request(
2540                    Some(ProviderBindingId(1)),
2541                    request,
2542                )),
2543                BackendIngress::Control(command(
2544                    3,
2545                    ControlCommand::Stop {
2546                        instance_id: instance(),
2547                        force: false,
2548                    },
2549                )),
2550            ],
2551            [],
2552        );
2553
2554        assert!(stopped.integration_errors.is_empty());
2555        assert!(stopped.tool_effects.is_empty());
2556        let completion = &stopped.tool_completions.completions[0];
2557        assert_eq!(completion.request_key, request_key);
2558        assert!(matches!(
2559            completion.outcome,
2560            CapabilityTerminalOutcome::InstanceClosed { .. }
2561        ));
2562
2563        let exited = kernel.step(
2564            [],
2565            [ObservationEnvelope {
2566                operation_id: None,
2567                instance_id: instance(),
2568                generation,
2569                observation: ControlObservation::ProcessExited {
2570                    exit_code: Some(0),
2571                    final_terminal: None,
2572                },
2573            }],
2574        );
2575        assert_eq!(
2576            exited.snapshot.sessions[0].status,
2577            SessionStatus::Exited { exit_code: Some(0) }
2578        );
2579
2580        let step = kernel.step_control_plane(
2581            [
2582                BackendIngress::Control(command(
2583                    4,
2584                    ControlCommand::Remove {
2585                        instance_id: instance(),
2586                    },
2587                )),
2588                BackendIngress::Control(register(5, "claude")),
2589            ],
2590            [],
2591        );
2592        assert!(step.integration_errors.is_empty());
2593        assert_eq!(step.snapshot.sessions.len(), 1);
2594        assert_eq!(step.snapshot.sessions[0].generation, SessionGeneration(2));
2595        assert_eq!(
2596            step.backend_snapshot.tools.generations,
2597            vec![(instance(), SessionGeneration(2))]
2598        );
2599        assert_eq!(
2600            step.backend_snapshot.tools.instance_states,
2601            vec![(instance(), ToolInstanceState::Inactive)]
2602        );
2603    }
2604
2605    #[test]
2606    fn kernel_without_bootstrap_providers_denies_tool_requests() {
2607        let mut kernel = Gate4AgentKernel::default();
2608        let generation = start_running(&mut kernel);
2609        let step = kernel.step_control_plane(
2610            [BackendIngress::ToolRequest(provider_bound_tool_request(
2611                None,
2612                tool_request(1, generation),
2613            ))],
2614            [],
2615        );
2616        let BackendIngressOutcome::ToolRequest(outcome) = &step.ingress_outcomes[0] else {
2617            panic!("expected tool request outcome");
2618        };
2619        assert_eq!(
2620            outcome.result,
2621            Ok(PolicyDecision::Deny(PolicyDenial::UnknownProvider))
2622        );
2623        assert!(step.tool_effects.is_empty());
2624        assert!(step.backend_snapshot.tools.providers.is_empty());
2625    }
2626
2627    #[test]
2628    fn reconciliation_failure_never_releases_retained_tool_effects() {
2629        let mut kernel =
2630            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2631                .unwrap();
2632        attach_tool_provider(&mut kernel, 1);
2633        start_running(&mut kernel);
2634        let divergent_generation = SessionGeneration(99);
2635        kernel
2636            .tool_engine
2637            .set_generation(instance(), divergent_generation)
2638            .unwrap();
2639        kernel
2640            .tool_engine
2641            .set_instance_state(instance(), divergent_generation, ToolInstanceState::Active)
2642            .unwrap();
2643        kernel
2644            .tool_engine
2645            .apply_authority(tool_grant(divergent_generation, 1))
2646            .unwrap();
2647        assert_eq!(
2648            kernel
2649                .tool_engine
2650                .request(tool_request(99, divergent_generation))
2651                .unwrap(),
2652            PolicyDecision::Allow
2653        );
2654
2655        let first = kernel.step_control_plane([], []);
2656        assert!(matches!(
2657            first.integration_errors[0],
2658            KernelIntegrationError::ToolInstanceSync {
2659                source: ToolEngineError::GenerationRegressed { .. },
2660                ..
2661            }
2662        ));
2663        assert!(first.tool_effects.is_empty());
2664
2665        let second = kernel.step_control_plane([], []);
2666        assert!(matches!(
2667            second.integration_errors[0],
2668            KernelIntegrationError::ToolInstanceSync {
2669                source: ToolEngineError::GenerationRegressed { .. },
2670                ..
2671            }
2672        ));
2673        assert!(second.tool_effects.is_empty());
2674    }
2675
2676    #[test]
2677    fn known_unbound_provider_is_rejected_before_canonical_acceptance() {
2678        let mut kernel =
2679            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2680                .unwrap();
2681        let generation = start_running(&mut kernel);
2682        let granted = kernel.step_control_plane(
2683            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2684            [],
2685        );
2686        assert!(granted.integration_errors.is_empty());
2687
2688        let step = kernel.step_control_plane(
2689            [BackendIngress::ToolRequest(provider_bound_tool_request(
2690                None,
2691                tool_request(1, generation),
2692            ))],
2693            [],
2694        );
2695        let BackendIngressOutcome::ToolRequest(outcome) = &step.ingress_outcomes[0] else {
2696            panic!("expected tool request outcome");
2697        };
2698        assert_eq!(outcome.accepted_sequence, None);
2699        assert!(matches!(
2700            &outcome.result,
2701            Err(KernelToolError::ProviderUnavailable { provider_id })
2702                if provider_id == &tool_provider_id()
2703        ));
2704        assert!(step.backend_snapshot.tools.requests.is_empty());
2705        assert!(step.tool_effects.is_empty());
2706        assert!(step.tool_completions.completions.is_empty());
2707    }
2708
2709    #[test]
2710    fn attached_provider_round_trip_binds_effect_and_observation() {
2711        let mut kernel =
2712            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2713                .unwrap();
2714        let binding_id = attach_tool_provider(&mut kernel, 1);
2715        let generation = start_running(&mut kernel);
2716        kernel.step_control_plane(
2717            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2718            [],
2719        );
2720
2721        let requested = kernel.step_control_plane(
2722            [BackendIngress::ToolRequest(provider_bound_tool_request(
2723                Some(binding_id),
2724                tool_request(1, generation),
2725            ))],
2726            [],
2727        );
2728        assert_eq!(requested.tool_effects.len(), 1);
2729        let effect = requested.tool_effects[0].clone();
2730        assert_eq!(effect.binding_id, binding_id);
2731        effect.validate().unwrap();
2732
2733        let completed = kernel.step_control_plane(
2734            [provider_runtime(
2735                2,
2736                ProviderRuntimeCommand::Observe {
2737                    binding_id,
2738                    observation: successful_observation(&effect),
2739                },
2740            )],
2741            [],
2742        );
2743        assert!(matches!(
2744            &completed.ingress_outcomes[0],
2745            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2746                sequence: 2,
2747                binding_id: observed_binding,
2748                provider_id,
2749                result: Ok(ProviderRuntimeTransition::ObservationApplied { operation_id, request_key }),
2750            }) if *observed_binding == binding_id
2751                && provider_id == &tool_provider_id()
2752                && *operation_id == effect.effect.operation_id
2753                && request_key == &effect.effect.request_key
2754        ));
2755        assert!(matches!(
2756            completed.tool_completions.completions[0].outcome,
2757            CapabilityTerminalOutcome::Succeeded { .. }
2758        ));
2759        assert_eq!(completed.backend_snapshot.provider_runtime.last_sequence, 2);
2760        assert_eq!(
2761            completed.backend_snapshot.provider_runtime.bindings,
2762            vec![ProviderRuntimeBindingSnapshot {
2763                binding_id,
2764                provider_id: tool_provider_id(),
2765            }]
2766        );
2767    }
2768
2769    #[test]
2770    fn provider_observation_cannot_cross_another_active_binding() {
2771        let mut kernel = Gate4AgentKernel::with_tool_providers(
2772            builtin_registry().clone(),
2773            [tool_provider(), other_tool_provider()],
2774        )
2775        .unwrap();
2776        let first_binding = attach_tool_provider(&mut kernel, 1);
2777        let second_binding = ProviderBindingId(2);
2778        let second_attach = kernel.step_control_plane(
2779            [provider_runtime(
2780                2,
2781                ProviderRuntimeCommand::Attach {
2782                    binding_id: second_binding,
2783                    provider_id: other_tool_provider_id(),
2784                },
2785            )],
2786            [],
2787        );
2788        assert!(matches!(
2789            &second_attach.ingress_outcomes[0],
2790            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2791                result: Ok(ProviderRuntimeTransition::Attached),
2792                ..
2793            })
2794        ));
2795
2796        let generation = start_running(&mut kernel);
2797        kernel.step_control_plane(
2798            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2799            [],
2800        );
2801        let requested = kernel.step_control_plane(
2802            [BackendIngress::ToolRequest(provider_bound_tool_request(
2803                Some(first_binding),
2804                tool_request(1, generation),
2805            ))],
2806            [],
2807        );
2808        let effect = requested.tool_effects[0].clone();
2809
2810        let rejected = kernel.step_control_plane(
2811            [provider_runtime(
2812                3,
2813                ProviderRuntimeCommand::Observe {
2814                    binding_id: second_binding,
2815                    observation: successful_observation(&effect),
2816                },
2817            )],
2818            [],
2819        );
2820        assert!(matches!(
2821            &rejected.ingress_outcomes[0],
2822            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2823                result: Err(KernelProviderError::BindingMismatch {
2824                    current,
2825                    requested,
2826                    ..
2827                }),
2828                ..
2829            }) if *current == first_binding && *requested == second_binding
2830        ));
2831        assert!(rejected.tool_completions.completions.is_empty());
2832
2833        let accepted = kernel.step_control_plane(
2834            [provider_runtime(
2835                4,
2836                ProviderRuntimeCommand::Observe {
2837                    binding_id: first_binding,
2838                    observation: successful_observation(&effect),
2839                },
2840            )],
2841            [],
2842        );
2843        assert!(matches!(
2844            &accepted.ingress_outcomes[0],
2845            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2846                result: Ok(ProviderRuntimeTransition::ObservationApplied { .. }),
2847                ..
2848            })
2849        ));
2850    }
2851
2852    #[test]
2853    fn detach_fences_late_results_and_rebinds_without_reusing_identity() {
2854        let mut kernel =
2855            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2856                .unwrap();
2857        let first_binding = attach_tool_provider(&mut kernel, 1);
2858        let generation = start_running(&mut kernel);
2859        kernel.step_control_plane(
2860            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2861            [],
2862        );
2863        let requested = kernel.step_control_plane(
2864            [BackendIngress::ToolRequest(provider_bound_tool_request(
2865                Some(first_binding),
2866                tool_request(1, generation),
2867            ))],
2868            [],
2869        );
2870        let old_effect = requested.tool_effects[0].clone();
2871
2872        let detached = kernel.step_control_plane(
2873            [provider_runtime(
2874                2,
2875                ProviderRuntimeCommand::Detach {
2876                    binding_id: first_binding,
2877                    provider_id: tool_provider_id(),
2878                },
2879            )],
2880            [],
2881        );
2882        assert!(matches!(
2883            &detached.ingress_outcomes[0],
2884            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2885                result: Ok(ProviderRuntimeTransition::Detached {
2886                    closed_request_count: 1,
2887                }),
2888                ..
2889            })
2890        ));
2891        assert!(matches!(
2892            detached.tool_completions.completions[0].outcome,
2893            CapabilityTerminalOutcome::ProviderDetached { .. }
2894        ));
2895        assert!(detached
2896            .backend_snapshot
2897            .provider_runtime
2898            .bindings
2899            .is_empty());
2900        assert_eq!(detached.backend_snapshot.tools.grants.len(), 1);
2901
2902        let late = kernel.step_control_plane(
2903            [provider_runtime(
2904                3,
2905                ProviderRuntimeCommand::Observe {
2906                    binding_id: first_binding,
2907                    observation: successful_observation(&old_effect),
2908                },
2909            )],
2910            [],
2911        );
2912        assert!(matches!(
2913            &late.ingress_outcomes[0],
2914            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2915                result: Err(KernelProviderError::NotAttached { .. }),
2916                ..
2917            })
2918        ));
2919        assert!(late.tool_completions.completions.is_empty());
2920
2921        let rebound = attach_tool_provider(&mut kernel, 4);
2922        assert_ne!(rebound, first_binding);
2923        let old_binding_after_rebind = kernel.step_control_plane(
2924            [provider_runtime(
2925                5,
2926                ProviderRuntimeCommand::Observe {
2927                    binding_id: first_binding,
2928                    observation: successful_observation(&old_effect),
2929                },
2930            )],
2931            [],
2932        );
2933        assert!(matches!(
2934            &old_binding_after_rebind.ingress_outcomes[0],
2935            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2936                result: Err(KernelProviderError::BindingMismatch {
2937                    current,
2938                    requested,
2939                    ..
2940                }),
2941                ..
2942            }) if *current == rebound && *requested == first_binding
2943        ));
2944
2945        let next = kernel.step_control_plane(
2946            [BackendIngress::ToolRequest(provider_bound_tool_request(
2947                Some(rebound),
2948                tool_request(2, generation),
2949            ))],
2950            [],
2951        );
2952        assert_eq!(next.tool_effects[0].binding_id, rebound);
2953        let completed = kernel.step_control_plane(
2954            [provider_runtime(
2955                6,
2956                ProviderRuntimeCommand::Observe {
2957                    binding_id: rebound,
2958                    observation: successful_observation(&next.tool_effects[0]),
2959                },
2960            )],
2961            [],
2962        );
2963        assert!(matches!(
2964            completed.tool_completions.completions[0].outcome,
2965            CapabilityTerminalOutcome::Succeeded { .. }
2966        ));
2967    }
2968
2969    #[test]
2970    fn provider_request_admission_rejects_stale_missing_and_zero_bindings_without_mutation() {
2971        let mut kernel =
2972            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
2973                .unwrap();
2974        let first_binding = attach_tool_provider(&mut kernel, 1);
2975        let detached = kernel.step_control_plane(
2976            [provider_runtime(
2977                2,
2978                ProviderRuntimeCommand::Detach {
2979                    binding_id: first_binding,
2980                    provider_id: tool_provider_id(),
2981                },
2982            )],
2983            [],
2984        );
2985        assert!(matches!(
2986            &detached.ingress_outcomes[0],
2987            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
2988                result: Ok(ProviderRuntimeTransition::Detached { .. }),
2989                ..
2990            })
2991        ));
2992        let rebound = attach_tool_provider(&mut kernel, 3);
2993        let generation = start_running(&mut kernel);
2994        kernel.step_control_plane(
2995            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
2996            [],
2997        );
2998
2999        let cases = [
3000            (Some(first_binding), 1_u64),
3001            (None, 2_u64),
3002            (Some(ProviderBindingId(0)), 3_u64),
3003        ];
3004        for (requested, local_id) in cases {
3005            let step = kernel.step_control_plane(
3006                [BackendIngress::ToolRequest(provider_bound_tool_request(
3007                    requested,
3008                    tool_request(local_id, generation),
3009                ))],
3010                [],
3011            );
3012            let BackendIngressOutcome::ToolRequest(outcome) = &step.ingress_outcomes[0] else {
3013                panic!("expected tool request outcome");
3014            };
3015            assert_eq!(outcome.accepted_sequence, None);
3016            if requested == Some(ProviderBindingId(0)) {
3017                assert!(matches!(
3018                    &outcome.result,
3019                    Err(KernelToolError::Validation(
3020                        ToolValidationError::ZeroIdentifier {
3021                            field: "provider binding id"
3022                        }
3023                    ))
3024                ));
3025            } else {
3026                assert!(matches!(
3027                    &outcome.result,
3028                    Err(KernelToolError::ProviderBindingMismatch {
3029                        current,
3030                        requested: rejected,
3031                        ..
3032                    }) if *current == rebound && *rejected == requested
3033                ));
3034            }
3035            assert!(step.backend_snapshot.tools.requests.is_empty());
3036            assert!(step.tool_effects.is_empty());
3037            assert!(step.tool_completions.completions.is_empty());
3038        }
3039    }
3040
3041    #[test]
3042    fn same_step_revoke_then_detach_never_releases_cancel_to_removed_binding() {
3043        let mut kernel =
3044            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
3045                .unwrap();
3046        let binding_id = attach_tool_provider(&mut kernel, 1);
3047        let generation = start_running(&mut kernel);
3048        kernel.step_control_plane(
3049            [BackendIngress::ToolAuthority(tool_grant(generation, 1))],
3050            [],
3051        );
3052        let requested = kernel.step_control_plane(
3053            [BackendIngress::ToolRequest(provider_bound_tool_request(
3054                Some(binding_id),
3055                tool_request(1, generation),
3056            ))],
3057            [],
3058        );
3059        assert_eq!(requested.tool_effects.len(), 1);
3060
3061        let reduced = kernel.step_control_plane(
3062            [
3063                BackendIngress::ToolAuthority(ToolAuthorityEnvelope {
3064                    sequence: 2,
3065                    command: ToolAuthorityCommand::RevokeGrant {
3066                        key: tool_policy_grant(generation).key,
3067                    },
3068                }),
3069                provider_runtime(
3070                    2,
3071                    ProviderRuntimeCommand::Detach {
3072                        binding_id,
3073                        provider_id: tool_provider_id(),
3074                    },
3075                ),
3076            ],
3077            [],
3078        );
3079
3080        assert!(reduced.integration_errors.is_empty());
3081        assert!(reduced.tool_effects.is_empty());
3082        assert!(reduced
3083            .backend_snapshot
3084            .provider_runtime
3085            .bindings
3086            .is_empty());
3087        assert!(matches!(
3088            reduced.tool_completions.completions[0].outcome,
3089            CapabilityTerminalOutcome::GrantRevoked {
3090                cancellation: CancellationDisposition::CancelQueuedUnconfirmed,
3091            }
3092        ));
3093        assert!(matches!(
3094            &reduced.ingress_outcomes[1],
3095            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3096                result: Ok(ProviderRuntimeTransition::Detached {
3097                    closed_request_count: 0,
3098                }),
3099                ..
3100            })
3101        ));
3102    }
3103
3104    #[test]
3105    fn provider_sequence_rejection_reuse_and_exhaustion_are_explicit() {
3106        let mut kernel =
3107            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
3108                .unwrap();
3109        let invalid = kernel.step_control_plane(
3110            [provider_runtime(
3111                1,
3112                ProviderRuntimeCommand::Attach {
3113                    binding_id: ProviderBindingId(9),
3114                    provider_id: tool_provider_id(),
3115                },
3116            )],
3117            [],
3118        );
3119        assert!(matches!(
3120            &invalid.ingress_outcomes[0],
3121            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3122                result: Err(KernelProviderError::InvalidAttachBinding { .. }),
3123                ..
3124            })
3125        ));
3126        assert_eq!(invalid.backend_snapshot.provider_runtime.last_sequence, 1);
3127
3128        let reused_sequence = kernel.step_control_plane(
3129            [provider_runtime(
3130                1,
3131                ProviderRuntimeCommand::Attach {
3132                    binding_id: ProviderBindingId(1),
3133                    provider_id: tool_provider_id(),
3134                },
3135            )],
3136            [],
3137        );
3138        assert!(matches!(
3139            &reused_sequence.ingress_outcomes[0],
3140            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3141                result: Err(KernelProviderError::SequenceRegressed {
3142                    current: 1,
3143                    requested: 1,
3144                }),
3145                ..
3146            })
3147        ));
3148
3149        let binding_id = attach_tool_provider(&mut kernel, 2);
3150        let duplicate_attach = kernel.step_control_plane(
3151            [provider_runtime(
3152                3,
3153                ProviderRuntimeCommand::Attach {
3154                    binding_id: ProviderBindingId(3),
3155                    provider_id: tool_provider_id(),
3156                },
3157            )],
3158            [],
3159        );
3160        assert!(matches!(
3161            &duplicate_attach.ingress_outcomes[0],
3162            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3163                result: Err(KernelProviderError::AlreadyAttached {
3164                    binding_id: current,
3165                    ..
3166                }),
3167                ..
3168            }) if *current == binding_id
3169        ));
3170        assert_eq!(
3171            duplicate_attach
3172                .backend_snapshot
3173                .provider_runtime
3174                .last_sequence,
3175            3
3176        );
3177
3178        kernel.step_control_plane(
3179            [provider_runtime(
3180                4,
3181                ProviderRuntimeCommand::Detach {
3182                    binding_id,
3183                    provider_id: tool_provider_id(),
3184                },
3185            )],
3186            [],
3187        );
3188        let reused_binding = kernel.step_control_plane(
3189            [provider_runtime(
3190                5,
3191                ProviderRuntimeCommand::Attach {
3192                    binding_id,
3193                    provider_id: tool_provider_id(),
3194                },
3195            )],
3196            [],
3197        );
3198        assert!(matches!(
3199            &reused_binding.ingress_outcomes[0],
3200            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3201                result: Err(KernelProviderError::InvalidAttachBinding { .. }),
3202                ..
3203            })
3204        ));
3205
3206        let exhausted_binding = attach_tool_provider(&mut kernel, 6);
3207        assert_eq!(exhausted_binding, ProviderBindingId(6));
3208        kernel.last_provider_sequence = u64::MAX - 1;
3209        kernel.provider_sequence_exhausted = false;
3210        let unknown_provider = ToolProviderId::new("kernel-unknown-provider").unwrap();
3211        let exhausted_on_rejection = kernel.step_control_plane(
3212            [provider_runtime(
3213                u64::MAX,
3214                ProviderRuntimeCommand::Attach {
3215                    binding_id: ProviderBindingId(u64::MAX),
3216                    provider_id: unknown_provider,
3217                },
3218            )],
3219            [],
3220        );
3221        assert!(matches!(
3222            &exhausted_on_rejection.ingress_outcomes[0],
3223            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3224                result: Err(KernelProviderError::UnknownProvider { .. }),
3225                ..
3226            })
3227        ));
3228        assert!(
3229            exhausted_on_rejection
3230                .backend_snapshot
3231                .provider_runtime
3232                .sequence_exhausted
3233        );
3234        assert_eq!(
3235            exhausted_on_rejection
3236                .backend_snapshot
3237                .provider_runtime
3238                .last_sequence,
3239            u64::MAX
3240        );
3241        assert!(exhausted_on_rejection
3242            .backend_snapshot
3243            .provider_runtime
3244            .bindings
3245            .is_empty());
3246
3247        let terminal = kernel.step_control_plane(
3248            [provider_runtime(
3249                u64::MAX,
3250                ProviderRuntimeCommand::Attach {
3251                    binding_id: ProviderBindingId(u64::MAX),
3252                    provider_id: tool_provider_id(),
3253                },
3254            )],
3255            [],
3256        );
3257        assert!(matches!(
3258            &terminal.ingress_outcomes[0],
3259            BackendIngressOutcome::ToolProvider(ProviderRuntimeCommandOutcome {
3260                result: Err(KernelProviderError::SequenceExhausted),
3261                ..
3262            })
3263        ));
3264    }
3265
3266    #[test]
3267    fn missing_effect_binding_is_reported_and_never_released() {
3268        let mut kernel =
3269            Gate4AgentKernel::with_tool_providers(builtin_registry().clone(), [tool_provider()])
3270                .unwrap();
3271        attach_tool_provider(&mut kernel, 1);
3272        let generation = start_running(&mut kernel);
3273        kernel
3274            .tool_engine
3275            .apply_authority(tool_grant(generation, 1))
3276            .unwrap();
3277        assert_eq!(
3278            kernel.tool_engine.request(tool_request(1, generation)),
3279            Ok(PolicyDecision::Allow)
3280        );
3281        kernel.provider_bindings.clear();
3282
3283        let step = kernel.step_control_plane([], []);
3284        assert!(matches!(
3285            &step.integration_errors[0],
3286            KernelIntegrationError::ToolEffectProviderUnbound {
3287                provider_id,
3288                ..
3289            } if provider_id == &tool_provider_id()
3290        ));
3291        assert!(step.tool_effects.is_empty());
3292    }
3293
3294    #[test]
3295    fn logical_tick_exhaustion_is_correlated_and_fail_closed() {
3296        let mut kernel = Gate4AgentKernel {
3297            logical_tick: u64::MAX,
3298            ..Gate4AgentKernel::default()
3299        };
3300        let step = kernel.step([register(1, "claude")], []);
3301
3302        assert_eq!(
3303            step.integration_errors,
3304            vec![KernelIntegrationError::LogicalTickExhausted {
3305                current_tick: u64::MAX,
3306            }]
3307        );
3308        assert!(matches!(
3309            step.command_outcomes[0].result,
3310            Err(KernelCommandError::IntegrationBlocked {
3311                reason: KernelIntegrationError::LogicalTickExhausted { .. }
3312            })
3313        ));
3314        assert!(step.snapshot.sessions.is_empty());
3315        assert!(step.effects.is_empty());
3316        assert!(step.tool_effects.is_empty());
3317        assert_eq!(step.backend_snapshot.logical_tick, u64::MAX);
3318    }
3319
3320    #[test]
3321    fn terminal_control_health_blocks_both_lanes_once() {
3322        let mut control_lane_open = true;
3323        let mut tool_lane_open = true;
3324        let mut errors = Vec::new();
3325        let healthy_capacity = ControlHealth {
3326            retained_instance_identities: 4_096,
3327            ..ControlHealth::default()
3328        };
3329
3330        block_lanes_on_control_health(
3331            healthy_capacity,
3332            &mut control_lane_open,
3333            &mut tool_lane_open,
3334            &mut errors,
3335        );
3336        assert!(control_lane_open);
3337        assert!(tool_lane_open);
3338        assert!(errors.is_empty());
3339
3340        let exhausted = ControlHealth {
3341            provider_sequence_exhausted_sessions: 1,
3342            ..healthy_capacity
3343        };
3344        block_lanes_on_control_health(
3345            exhausted,
3346            &mut control_lane_open,
3347            &mut tool_lane_open,
3348            &mut errors,
3349        );
3350        block_lanes_on_control_health(
3351            exhausted,
3352            &mut control_lane_open,
3353            &mut tool_lane_open,
3354            &mut errors,
3355        );
3356
3357        assert!(!control_lane_open);
3358        assert!(!tool_lane_open);
3359        assert_eq!(
3360            errors,
3361            vec![KernelIntegrationError::ControlHealthExhausted { health: exhausted }]
3362        );
3363    }
3364
3365    #[test]
3366    fn identical_unified_batches_produce_identical_steps() {
3367        fn run() -> KernelStep {
3368            let mut kernel = Gate4AgentKernel::with_tool_providers(
3369                builtin_registry().clone(),
3370                [tool_provider()],
3371            )
3372            .unwrap();
3373            attach_tool_provider(&mut kernel, 1);
3374            let generation = start_running(&mut kernel);
3375            kernel.step_control_plane(
3376                [
3377                    BackendIngress::ToolAuthority(tool_grant(generation, 1)),
3378                    BackendIngress::ToolRequest(provider_bound_tool_request(
3379                        Some(ProviderBindingId(1)),
3380                        tool_request(1, generation),
3381                    )),
3382                ],
3383                [],
3384            )
3385        }
3386
3387        assert_eq!(run(), run());
3388    }
3389}