1use 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#[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 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
270pub 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 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 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 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 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 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 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 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 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 #[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 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 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 #[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 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 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 ®ressed.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}