1use std::error::Error;
16use std::fmt;
17use std::pin::Pin;
18use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
19use std::sync::{Arc, Mutex as SyncMutex};
20use std::task::{Context, Poll};
21
22use crate::cancel::Token;
23#[cfg(test)]
24use tokio::sync::Semaphore;
25use tokio::sync::{Mutex, Notify, mpsc};
26
27use crate::audit;
28use crate::redact;
29use crate::transcript::item;
30use crate::value::lifecycle::{Coord, Outcome};
31use crate::value::tool_call::ToolCall;
32
33#[derive(Clone, Copy, Debug, Eq, PartialEq)]
76#[non_exhaustive]
77pub enum Kind {
78 TextDelta,
80 Text,
82 ThinkingDelta,
84 Thinking,
86 TurnStart,
88 TurnEnd,
90 StepStart,
92 StepEnd,
94 GenerationEnd,
96 ToolCall,
98 ToolResult,
100 Error,
102 Audit,
104 Stop,
106 InputAdmitted,
120 InputRejected,
130}
131
132#[derive(Clone, Copy, Debug, Eq, PartialEq)]
140#[non_exhaustive]
141pub enum InputOrigin {
142 Start,
151 Mailbox,
155 Continuation,
158}
159
160#[derive(Clone, Debug)]
168pub struct AdmittedInput {
169 origin: InputOrigin,
170 items: Vec<item::Item>,
171}
172
173impl AdmittedInput {
174 #[must_use]
176 pub const fn origin(&self) -> InputOrigin {
177 self.origin
178 }
179
180 #[must_use]
182 pub fn items(&self) -> &[item::Item] {
183 &self.items
184 }
185}
186
187#[derive(Clone, Copy, Debug, Eq, PartialEq)]
189#[non_exhaustive]
190pub enum DecisionPoint {
191 ToolCall,
193 ToolResult,
195 AfterToolCommit,
197}
198
199#[derive(Clone, Debug, Eq, PartialEq)]
201pub struct StopCode(String);
202
203impl StopCode {
204 pub fn new(code: String) -> Result<Self, ValidationError> {
213 if code.is_empty() {
214 return Err(ValidationError::EmptyStopCode);
215 }
216 Ok(Self(code))
217 }
218
219 #[must_use]
221 pub fn as_str(&self) -> &str {
222 &self.0
223 }
224}
225
226#[derive(Clone, Copy, Debug, Eq, PartialEq)]
228#[non_exhaustive]
229pub enum ValidationError {
230 EmptyAuditKind,
232 EmptyToolCallId,
234 EmptyToolName,
236 EmptyStopCode,
238 PayloadMismatch,
240 InvalidDecisionPoint,
242}
243
244impl fmt::Display for ValidationError {
245 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
246 formatter.write_str(match self {
247 Self::EmptyAuditKind => "event audit kind must be non-empty",
248 Self::EmptyToolCallId => "event tool-call identity must be non-empty",
249 Self::EmptyToolName => "event tool name must be non-empty",
250 Self::EmptyStopCode => "event stop code must be non-empty",
251 Self::PayloadMismatch => "event category and payload do not match",
252 Self::InvalidDecisionPoint => "event used an invalid decision point",
253 })
254 }
255}
256
257impl Error for ValidationError {}
258
259#[derive(Clone)]
260enum Payload {
261 Text(String),
262 Lifecycle(Option<Outcome>),
263 ToolCall(ToolCall),
264 ToolResult(item::ToolResult),
265 Audit(audit::Event),
266 Error(Arc<dyn Error + Send + Sync>),
267 Stop(StopCode),
268 Input(AdmittedInput),
269 Rejection(String),
270}
271
272impl fmt::Debug for Payload {
273 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
280 match self {
281 Self::Text(text) => formatter
282 .debug_tuple("Text")
283 .field(&redact::Bytes(text.len()))
284 .finish(),
285 Self::Lifecycle(outcome) => formatter.debug_tuple("Lifecycle").field(outcome).finish(),
286 Self::ToolCall(call) => formatter.debug_tuple("ToolCall").field(call).finish(),
287 Self::ToolResult(result) => formatter.debug_tuple("ToolResult").field(result).finish(),
288 Self::Audit(audit) => formatter.debug_tuple("Audit").field(audit).finish(),
289 Self::Error(error) => formatter
290 .debug_tuple("Error")
291 .field(&error.to_string())
292 .finish(),
293 Self::Stop(code) => formatter.debug_tuple("Stop").field(code).finish(),
294 Self::Input(input) => formatter.debug_tuple("Input").field(input).finish(),
297 Self::Rejection(reason) => formatter.debug_tuple("Rejection").field(reason).finish(),
298 }
299 }
300}
301
302#[derive(Clone, Debug)]
304pub struct Event {
305 kind: Kind,
306 coord: Option<Coord>,
307 item_id: Option<String>,
308 payload: Payload,
309}
310
311impl Event {
312 pub fn from_audit(audit: audit::Event) -> Result<Self, ValidationError> {
324 if audit.kind().is_empty() {
325 return Err(ValidationError::EmptyAuditKind);
326 }
327 Ok(Self {
328 kind: Kind::Audit,
329 coord: None,
330 item_id: None,
331 payload: Payload::Audit(audit),
332 })
333 }
334
335 #[must_use]
337 pub fn from_error(error: Arc<dyn Error + Send + Sync>) -> Self {
338 Self {
339 kind: Kind::Error,
340 coord: None,
341 item_id: None,
342 payload: Payload::Error(error),
343 }
344 }
345
346 #[must_use]
348 pub const fn kind(&self) -> Kind {
349 self.kind
350 }
351
352 #[must_use]
354 pub const fn coord(&self) -> Option<&Coord> {
355 self.coord.as_ref()
356 }
357
358 #[must_use]
387 pub fn item_id(&self) -> Option<&str> {
388 self.item_id.as_deref()
389 }
390
391 #[must_use]
393 pub fn text(&self) -> Option<&str> {
394 match &self.payload {
395 Payload::Text(text) => Some(text),
396 _ => None,
397 }
398 }
399
400 #[must_use]
402 pub const fn tool_call(&self) -> Option<&ToolCall> {
403 match &self.payload {
404 Payload::ToolCall(call) => Some(call),
405 _ => None,
406 }
407 }
408
409 #[must_use]
411 pub const fn tool_result(&self) -> Option<&item::ToolResult> {
412 match &self.payload {
413 Payload::ToolResult(result) => Some(result),
414 _ => None,
415 }
416 }
417
418 #[must_use]
423 pub const fn admitted_input(&self) -> Option<&AdmittedInput> {
424 match &self.payload {
425 Payload::Input(input) => Some(input),
426 _ => None,
427 }
428 }
429
430 #[must_use]
435 pub fn rejection_reason(&self) -> Option<&str> {
436 match &self.payload {
437 Payload::Rejection(reason) => Some(reason),
438 _ => None,
439 }
440 }
441
442 #[must_use]
444 pub const fn outcome(&self) -> Option<Outcome> {
445 match self.payload {
446 Payload::Lifecycle(outcome) => outcome,
447 _ => None,
448 }
449 }
450
451 #[must_use]
453 pub const fn as_audit(&self) -> Option<&audit::Event> {
454 match &self.payload {
455 Payload::Audit(audit) => Some(audit),
456 _ => None,
457 }
458 }
459
460 #[must_use]
462 pub fn as_error(&self) -> Option<&(dyn Error + Send + Sync)> {
463 match &self.payload {
464 Payload::Error(error) => Some(error.as_ref()),
465 _ => None,
466 }
467 }
468
469 #[must_use]
471 pub const fn stop_code(&self) -> Option<&StopCode> {
472 match &self.payload {
473 Payload::Stop(code) => Some(code),
474 _ => None,
475 }
476 }
477
478 const fn driver_text(kind: Kind, text: String, coord: Coord, item_id: Option<String>) -> Self {
479 Self {
480 kind,
481 coord: Some(coord),
482 item_id,
483 payload: Payload::Text(text),
484 }
485 }
486
487 const fn driver_lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Self {
488 Self {
489 kind,
490 coord: Some(coord),
491 item_id: None,
492 payload: Payload::Lifecycle(outcome),
493 }
494 }
495
496 const fn driver_tool_call(call: ToolCall, coord: Coord) -> Self {
497 Self {
498 kind: Kind::ToolCall,
499 coord: Some(coord),
500 item_id: None,
501 payload: Payload::ToolCall(call),
502 }
503 }
504
505 const fn driver_tool_result(result: item::ToolResult, coord: Coord) -> Self {
506 Self {
507 kind: Kind::ToolResult,
508 coord: Some(coord),
509 item_id: None,
510 payload: Payload::ToolResult(result),
511 }
512 }
513
514 const fn driver_stop(code: StopCode, coord: Coord) -> Self {
515 Self {
516 kind: Kind::Stop,
517 coord: Some(coord),
518 item_id: None,
519 payload: Payload::Stop(code),
520 }
521 }
522
523 const fn driver_input_admitted(
524 origin: InputOrigin,
525 items: Vec<item::Item>,
526 coord: Coord,
527 ) -> Self {
528 Self {
529 kind: Kind::InputAdmitted,
530 coord: Some(coord),
531 item_id: None,
532 payload: Payload::Input(AdmittedInput { origin, items }),
533 }
534 }
535
536 const fn driver_input_rejected(reason: String, coord: Coord) -> Self {
537 Self {
538 kind: Kind::InputRejected,
539 coord: Some(coord),
540 item_id: None,
541 payload: Payload::Rejection(reason),
542 }
543 }
544
545 fn validate(&self, decision_point: Option<DecisionPoint>) -> Result<(), ValidationError> {
546 if !payload_matches(self.kind, &self.payload) {
547 return Err(ValidationError::PayloadMismatch);
548 }
549 match &self.payload {
550 Payload::ToolCall(call) if call.id().as_str().is_empty() => {
551 Err(ValidationError::EmptyToolCallId)
552 }
553 Payload::ToolCall(call) if call.name().as_str().is_empty() => {
554 Err(ValidationError::EmptyToolName)
555 }
556 Payload::ToolResult(result) if result.call_id().as_str().is_empty() => {
557 Err(ValidationError::EmptyToolCallId)
558 }
559 Payload::ToolResult(result) if result.tool_name().as_str().is_empty() => {
560 Err(ValidationError::EmptyToolName)
561 }
562 Payload::Audit(audit) if audit.kind().is_empty() => {
563 Err(ValidationError::EmptyAuditKind)
564 }
565 Payload::Stop(code) if code.as_str().is_empty() => Err(ValidationError::EmptyStopCode),
566 _ if decision_point != expected_decision_point(self.kind, decision_point) => {
567 Err(ValidationError::InvalidDecisionPoint)
568 }
569 _ => Ok(()),
570 }
571 }
572}
573
574const fn payload_matches(kind: Kind, payload: &Payload) -> bool {
575 matches!(
576 (kind, payload),
577 (
578 Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking,
579 Payload::Text(_)
580 ) | (Kind::TurnStart | Kind::StepStart, Payload::Lifecycle(None))
581 | (
582 Kind::TurnEnd | Kind::StepEnd | Kind::GenerationEnd,
583 Payload::Lifecycle(Some(_))
584 )
585 | (Kind::ToolCall, Payload::ToolCall(_))
586 | (Kind::ToolResult, Payload::ToolResult(_))
587 | (Kind::Error, Payload::Error(_))
588 | (Kind::Audit, Payload::Audit(_))
589 | (Kind::Stop, Payload::Stop(_))
590 | (Kind::InputAdmitted, Payload::Input(_))
591 | (Kind::InputRejected, Payload::Rejection(_))
592 )
593}
594
595fn expected_decision_point(kind: Kind, requested: Option<DecisionPoint>) -> Option<DecisionPoint> {
596 match kind {
597 Kind::ToolCall => Some(DecisionPoint::ToolCall),
598 Kind::ToolResult => Some(DecisionPoint::ToolResult),
599 Kind::Audit | Kind::Error if requested == Some(DecisionPoint::AfterToolCommit) => requested,
600 _ => None,
601 }
602}
603
604#[derive(Clone, Copy, Debug, Eq, PartialEq)]
606#[non_exhaustive]
607pub enum DecisionError {
608 NotRequired,
610 AlreadyDecided,
612}
613
614impl fmt::Display for DecisionError {
615 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
616 formatter.write_str(match self {
617 Self::NotRequired => "event delivery does not require acceptance",
618 Self::AlreadyDecided => "event delivery was already decided",
619 })
620 }
621}
622
623impl Error for DecisionError {}
624
625const PENDING: u8 = 0;
626const ACCEPTED: u8 = 1;
627const REJECTED: u8 = 2;
628const CANCELED: u8 = 3;
629
630struct Decision {
631 value: AtomicU8,
632 changed: Notify,
633 cancel: Token,
635 nonfatal: Arc<NonfatalCause>,
641 #[cfg(test)]
642 after_pending_check: SyncMutex<Option<WaitBarriers>>,
643}
644
645#[cfg(test)]
646struct WaitBarriers {
647 checked: Arc<std::sync::Barrier>,
648 resume: Arc<std::sync::Barrier>,
649}
650
651impl Decision {
652 fn decide(&self, value: u8) -> Result<(), DecisionError> {
653 self.value
654 .compare_exchange(PENDING, value, Ordering::AcqRel, Ordering::Acquire)
655 .map(|_| self.changed.notify_waiters())
656 .map_err(|_| DecisionError::AlreadyDecided)
657 }
658
659 fn decide_consumer(&self, value: u8) -> Result<(), DecisionError> {
660 if self.cancel.is_cancelled() {
661 let _already_decided = self.decide(self.nonfatal.interrupted_decision());
662 Err(DecisionError::AlreadyDecided)
663 } else {
664 self.decide(value)
665 }
666 }
667
668 fn abandon(&self) -> Result<(), DecisionError> {
669 let value = if self.cancel.is_cancelled() {
670 self.nonfatal.interrupted_decision()
671 } else {
672 REJECTED
673 };
674 self.decide(value)
675 }
676
677 async fn wait(&self) -> StrongDecision {
678 loop {
679 let changed = self.changed.notified();
680 tokio::pin!(changed);
681 let _already_ready = changed.as_mut().enable();
682 match self.value.load(Ordering::Acquire) {
683 ACCEPTED => return StrongDecision::Accepted,
684 REJECTED => return StrongDecision::Rejected,
685 CANCELED => return StrongDecision::Cancelled,
686 _ => {
687 #[cfg(test)]
688 self.pause_after_pending_check();
689 tokio::select! {
690 biased;
691 () = self.cancel.cancelled() => {
692 let _already_decided =
693 self.decide(self.nonfatal.interrupted_decision());
694 }
695 () = &mut changed => {}
696 }
697 }
698 }
699 }
700 }
701
702 #[cfg(test)]
703 fn pause_after_pending_check(&self) {
704 let barriers = self
705 .after_pending_check
706 .lock()
707 .expect("event wait barrier lock poisoned")
708 .take();
709 if let Some(barriers) = barriers {
710 barriers.checked.wait();
711 barriers.resume.wait();
712 }
713 }
714}
715
716pub struct Delivery {
741 event: Event,
742 decision_point: Option<DecisionPoint>,
743 decision: Option<Arc<Decision>>,
744}
745
746impl fmt::Debug for Delivery {
747 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
754 formatter
755 .debug_struct("Delivery")
756 .field("event", &self.event)
757 .field("decision_point", &self.decision_point)
758 .field("decision", &redact::Presence(self.decision.is_some()))
759 .finish()
760 }
761}
762
763impl Delivery {
764 #[must_use]
766 pub const fn event(&self) -> &Event {
767 &self.event
768 }
769
770 #[must_use]
772 pub const fn decision_point(&self) -> Option<DecisionPoint> {
773 self.decision_point
774 }
775
776 pub fn accept(&self) -> Result<(), DecisionError> {
793 self.decision
794 .as_ref()
795 .ok_or(DecisionError::NotRequired)?
796 .decide_consumer(ACCEPTED)
797 }
798
799 pub fn reject(&self) -> Result<(), DecisionError> {
812 self.decision
813 .as_ref()
814 .ok_or(DecisionError::NotRequired)?
815 .decide_consumer(REJECTED)
816 }
817}
818
819impl Drop for Delivery {
820 fn drop(&mut self) {
821 if let Some(decision) = &self.decision {
822 let _already_decided = decision.abandon();
823 }
824 }
825}
826
827pub struct Stream {
857 receiver: mpsc::UnboundedReceiver<Delivery>,
858 control: Arc<Control>,
859}
860
861impl fmt::Debug for Stream {
862 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
868 formatter
869 .debug_struct("Stream")
870 .field("fatal", &self.control.fatal.load(Ordering::Relaxed))
871 .finish()
872 }
873}
874
875impl Stream {
876 pub async fn recv(&mut self) -> Option<Delivery> {
878 self.receiver.recv().await
879 }
880}
881
882impl futures_core::Stream for Stream {
883 type Item = Delivery;
884
885 fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
886 self.receiver.poll_recv(context)
887 }
888}
889
890impl Drop for Stream {
891 fn drop(&mut self) {
892 self.control.request_stop();
893 self.receiver.close();
894 }
895}
896
897#[derive(Clone, Copy, Debug, Eq, PartialEq)]
898pub(crate) enum DeliveryOutcome {
899 Delivered,
900 Accepted,
901 Rejected,
902}
903
904#[derive(Clone, Copy, Debug, Eq, PartialEq)]
908pub(crate) enum StrongDecision {
909 Accepted,
910 Rejected,
911 Cancelled,
912}
913
914impl From<StrongDecision> for DeliveryOutcome {
915 fn from(decision: StrongDecision) -> Self {
916 match decision {
917 StrongDecision::Accepted => Self::Accepted,
918 StrongDecision::Rejected | StrongDecision::Cancelled => Self::Rejected,
919 }
920 }
921}
922
923#[derive(Clone, Copy, Debug, Eq, PartialEq)]
924struct DeliveryResolution {
925 outward: DeliveryOutcome,
926 strong: Option<StrongDecision>,
927}
928
929impl DeliveryResolution {
930 const fn ordinary(outward: DeliveryOutcome) -> Self {
931 Self {
932 outward,
933 strong: None,
934 }
935 }
936
937 fn strong(decision: StrongDecision) -> Self {
938 Self {
939 outward: decision.into(),
940 strong: Some(decision),
941 }
942 }
943}
944
945#[derive(Clone, Copy, Debug, Eq, PartialEq)]
946pub(crate) enum TerminalIntent {
947 Running,
948 Stopped,
949 Cancelled,
950 Failed,
951}
952
953impl TerminalIntent {
954 #[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
955 pub(crate) const fn outcome(self) -> Option<Outcome> {
956 match self {
957 Self::Running => None,
958 Self::Stopped => Some(Outcome::Stopped),
959 Self::Cancelled => Some(Outcome::Cancelled),
960 Self::Failed => Some(Outcome::Failed),
961 }
962 }
963}
964
965const NONFATAL_NONE: u8 = 0;
967const NONFATAL_STOPPED: u8 = 1;
969const NONFATAL_CANCELED: u8 = 2;
971
972struct NonfatalCause {
985 parent: Token,
987 cause: SyncMutex<u8>,
988}
989
990impl NonfatalCause {
991 fn freeze(&self, normal_stop: bool) -> u8 {
1001 let mut cause = self
1002 .cause
1003 .lock()
1004 .expect("event nonfatal cause lock poisoned");
1005 if *cause == NONFATAL_NONE {
1006 if self.parent.is_cancelled() {
1007 *cause = NONFATAL_CANCELED;
1008 } else if normal_stop {
1009 *cause = NONFATAL_STOPPED;
1010 }
1011 }
1012 *cause
1013 }
1014
1015 #[cfg(test)]
1017 fn frozen(&self) -> u8 {
1018 *self
1019 .cause
1020 .lock()
1021 .expect("event nonfatal cause lock poisoned")
1022 }
1023
1024 fn interrupted_decision(&self) -> u8 {
1026 if self.freeze(false) == NONFATAL_CANCELED {
1027 CANCELED
1028 } else {
1029 REJECTED
1030 }
1031 }
1032}
1033
1034#[cfg(test)]
1035#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1036pub(crate) enum FreezePoint {
1037 Stop,
1038 Fatal,
1039}
1040
1041#[cfg(test)]
1042struct TestFreezePause {
1043 point: FreezePoint,
1044 reached: Arc<std::sync::Barrier>,
1045 resume: Arc<std::sync::Barrier>,
1046}
1047
1048#[cfg(test)]
1049struct TestFinalConfirmPause {
1050 reached: Semaphore,
1051 resume: Semaphore,
1052}
1053
1054#[cfg(test)]
1059struct TestEmitPause {
1060 reached: std::sync::mpsc::Sender<()>,
1061 resume: Semaphore,
1062}
1063
1064struct Control {
1065 nonfatal: Arc<NonfatalCause>,
1067 fatal: AtomicBool,
1068 fatal_event: SyncMutex<Option<ValidationError>>,
1069 stop_emitted: AtomicBool,
1070 pending: SyncMutex<Option<Arc<Decision>>>,
1071 cancel: Token,
1074 interruption: Token,
1075 #[cfg(test)]
1076 before_reject_pause: SyncMutex<Option<TestFreezePause>>,
1077 #[cfg(test)]
1078 after_final_confirm_pause: SyncMutex<Option<Arc<TestFinalConfirmPause>>>,
1079}
1080
1081struct PendingDecision<'a> {
1088 control: &'a Control,
1089 decision: Arc<Decision>,
1090}
1091
1092impl Drop for PendingDecision<'_> {
1093 fn drop(&mut self) {
1094 let _already_decided = self.decision.abandon();
1099 self.control.clear(&self.decision);
1100 }
1101}
1102
1103impl Control {
1104 fn intent(&self) -> TerminalIntent {
1105 if self.fatal.load(Ordering::Acquire) {
1108 return TerminalIntent::Failed;
1109 }
1110 match self.nonfatal.freeze(false) {
1113 NONFATAL_CANCELED => TerminalIntent::Cancelled,
1114 NONFATAL_STOPPED => TerminalIntent::Stopped,
1115 _ => TerminalIntent::Running,
1116 }
1117 }
1118
1119 fn strong_interruption(&self) -> Option<StrongDecision> {
1120 if self.fatal.load(Ordering::Acquire) {
1121 return Some(StrongDecision::Rejected);
1122 }
1123 match self.nonfatal.freeze(false) {
1124 NONFATAL_CANCELED => Some(StrongDecision::Cancelled),
1125 NONFATAL_STOPPED => Some(StrongDecision::Rejected),
1126 _ => None,
1127 }
1128 }
1129
1130 fn final_confirm_strong(&self, decision: StrongDecision) -> StrongDecision {
1138 if decision == StrongDecision::Accepted {
1139 self.strong_interruption().unwrap_or(decision)
1140 } else {
1141 decision
1142 }
1143 }
1144
1145 #[cfg(test)]
1146 fn pause_before_reject(&self, point: FreezePoint) {
1147 let pause = {
1148 let mut slot = self
1149 .before_reject_pause
1150 .lock()
1151 .expect("event freeze pause lock poisoned");
1152 if slot.as_ref().is_some_and(|pause| pause.point == point) {
1153 slot.take()
1154 } else {
1155 None
1156 }
1157 };
1158 if let Some(pause) = pause {
1159 pause.reached.wait();
1160 pause.resume.wait();
1161 }
1162 }
1163
1164 #[cfg(test)]
1165 async fn pause_after_final_confirm(&self) {
1166 let pause = self
1167 .after_final_confirm_pause
1168 .lock()
1169 .expect("event final-confirm pause lock poisoned")
1170 .take();
1171 if let Some(pause) = pause {
1172 pause.reached.add_permits(1);
1173 pause
1174 .resume
1175 .acquire()
1176 .await
1177 .expect("event final-confirm pause remains open")
1178 .forget();
1179 }
1180 }
1181
1182 fn interrupted(&self) -> bool {
1187 self.fatal.load(Ordering::Acquire) || self.nonfatal.freeze(false) != NONFATAL_NONE
1188 }
1189
1190 fn register(&self, decision: &Arc<Decision>) {
1191 let mut pending = self.pending.lock().expect("event pending lock poisoned");
1192 if self.interrupted() {
1193 let _already_decided = decision.decide(self.nonfatal.interrupted_decision());
1194 } else {
1195 *pending = Some(decision.clone());
1196 }
1197 }
1198
1199 fn clear(&self, decision: &Arc<Decision>) {
1200 let mut pending = self.pending.lock().expect("event pending lock poisoned");
1201 if pending
1202 .as_ref()
1203 .is_some_and(|current| Arc::ptr_eq(current, decision))
1204 {
1205 pending.take();
1206 }
1207 }
1208
1209 fn reject_pending(&self) {
1211 let decided = self.nonfatal.interrupted_decision();
1212 if let Some(decision) = self
1213 .pending
1214 .lock()
1215 .expect("event pending lock poisoned")
1216 .take()
1217 {
1218 let _already_decided = decision.decide(decided);
1219 }
1220 }
1221
1222 fn latch_stop(&self) {
1224 let _cause = self.nonfatal.freeze(true);
1225 #[cfg(test)]
1226 self.pause_before_reject(FreezePoint::Stop);
1227 self.reject_pending();
1228 self.interruption.cancel();
1229 }
1230
1231 fn request_stop(&self) {
1232 self.latch_stop();
1233 self.cancel.cancel();
1236 }
1237
1238 fn fail(&self, event_error: Option<ValidationError>) -> Option<ValidationError> {
1239 let first_event_error = {
1240 let mut fatal_event = self
1241 .fatal_event
1242 .lock()
1243 .expect("event fatal latch lock poisoned");
1244 if !self.fatal.load(Ordering::Acquire) {
1245 *fatal_event = event_error;
1246 self.fatal.store(true, Ordering::Release);
1247 }
1248 *fatal_event
1249 };
1250 #[cfg(test)]
1251 self.pause_before_reject(FreezePoint::Fatal);
1252 self.reject_pending();
1253 self.interruption.cancel();
1254 self.cancel.cancel();
1255 first_event_error
1256 }
1257}
1258
1259pub(crate) struct Producer {
1260 sender: mpsc::UnboundedSender<Delivery>,
1261 control: Arc<Control>,
1262 serial: Mutex<()>,
1263}
1264
1265impl Producer {
1266 pub(crate) async fn emit_text(
1267 &self,
1268 kind: Kind,
1269 text: String,
1270 coord: Coord,
1271 item_id: Option<String>,
1272 ) -> Result<DeliveryOutcome, ValidationError> {
1273 self.emit(Event::driver_text(kind, text, coord, item_id), None)
1274 .await
1275 }
1276
1277 pub(crate) async fn emit_lifecycle(
1278 &self,
1279 kind: Kind,
1280 outcome: Option<Outcome>,
1281 coord: Coord,
1282 ) -> Result<DeliveryOutcome, ValidationError> {
1283 self.emit(Event::driver_lifecycle(kind, outcome, coord), None)
1284 .await
1285 }
1286
1287 pub(crate) async fn emit_input_admitted(
1288 &self,
1289 origin: InputOrigin,
1290 items: Vec<item::Item>,
1291 coord: Coord,
1292 ) -> Result<DeliveryOutcome, ValidationError> {
1293 self.emit(Event::driver_input_admitted(origin, items, coord), None)
1294 .await
1295 }
1296
1297 pub(crate) async fn emit_input_rejected(
1298 &self,
1299 reason: String,
1300 coord: Coord,
1301 ) -> Result<DeliveryOutcome, ValidationError> {
1302 self.emit(Event::driver_input_rejected(reason, coord), None)
1303 .await
1304 }
1305
1306 pub(crate) async fn emit_tool_call(
1307 &self,
1308 call: ToolCall,
1309 coord: Coord,
1310 ) -> Result<StrongDecision, ValidationError> {
1311 self.emit_strong(
1312 Event::driver_tool_call(call, coord),
1313 DecisionPoint::ToolCall,
1314 )
1315 .await
1316 }
1317
1318 pub(crate) async fn emit_tool_result(
1319 &self,
1320 result: item::ToolResult,
1321 coord: Coord,
1322 ) -> Result<StrongDecision, ValidationError> {
1323 self.emit_strong(
1324 Event::driver_tool_result(result, coord),
1325 DecisionPoint::ToolResult,
1326 )
1327 .await
1328 }
1329
1330 pub(crate) async fn emit_extension(
1331 &self,
1332 mut event: Event,
1333 coord: Coord,
1334 ) -> Result<DeliveryOutcome, ValidationError> {
1335 event.coord = Some(coord);
1336 self.emit(event, None).await
1337 }
1338
1339 pub(crate) async fn emit_after_tool_commit(
1340 &self,
1341 mut event: Event,
1342 coord: Coord,
1343 ) -> Result<StrongDecision, ValidationError> {
1344 event.coord = Some(coord);
1345 self.emit_strong(event, DecisionPoint::AfterToolCommit)
1346 .await
1347 }
1348
1349 pub(crate) async fn emit(
1350 &self,
1351 event: Event,
1352 decision_point: Option<DecisionPoint>,
1353 ) -> Result<DeliveryOutcome, ValidationError> {
1354 if let Some(decision_point) = decision_point {
1355 return self
1356 .emit_strong(event, decision_point)
1357 .await
1358 .map(Into::into);
1359 }
1360 let _serial = self.serial.lock().await;
1361 if self.control.interrupted() {
1362 return Ok(DeliveryOutcome::Rejected);
1363 }
1364 self.emit_locked(event, None)
1365 .await
1366 .map(|resolution| resolution.outward)
1367 }
1368
1369 async fn emit_strong(
1370 &self,
1371 event: Event,
1372 decision_point: DecisionPoint,
1373 ) -> Result<StrongDecision, ValidationError> {
1374 let _serial = self.serial.lock().await;
1375 if let Some(decision) = self.control.strong_interruption() {
1376 return Ok(decision);
1377 }
1378 Ok(self
1379 .emit_locked(event, Some(decision_point))
1380 .await?
1381 .strong
1382 .expect("a strong decision point always has a decision"))
1383 }
1384
1385 async fn emit_locked(
1386 &self,
1387 event: Event,
1388 decision_point: Option<DecisionPoint>,
1389 ) -> Result<DeliveryResolution, ValidationError> {
1390 if let Err(error) = event.validate(decision_point) {
1391 let _first_event_error = self.control.fail(Some(error));
1392 return Err(error);
1393 }
1394 let decision = decision_point.map(|_| {
1395 Arc::new(Decision {
1396 value: AtomicU8::new(PENDING),
1397 changed: Notify::new(),
1398 cancel: self.control.cancel.clone(),
1399 nonfatal: Arc::clone(&self.control.nonfatal),
1400 #[cfg(test)]
1401 after_pending_check: SyncMutex::new(None),
1402 })
1403 });
1404 let _pending = decision.as_ref().map(|decision| {
1405 self.control.register(decision);
1406 PendingDecision {
1407 control: &self.control,
1408 decision: Arc::clone(decision),
1409 }
1410 });
1411 let delivery = Delivery {
1412 event,
1413 decision_point,
1414 decision: decision.clone(),
1415 };
1416 let delivered = !self.control.cancel.is_cancelled() && self.sender.send(delivery).is_ok();
1422 let outcome = if let Some(decision) = &decision {
1423 if !delivered {
1424 let _already_decided = decision.abandon();
1425 }
1426 let decision = self.control.final_confirm_strong(decision.wait().await);
1427 #[cfg(test)]
1428 self.control.pause_after_final_confirm().await;
1429 DeliveryResolution::strong(decision)
1430 } else {
1431 DeliveryResolution::ordinary(if delivered {
1432 DeliveryOutcome::Delivered
1433 } else {
1434 DeliveryOutcome::Rejected
1435 })
1436 };
1437 Ok(outcome)
1438 }
1439
1440 pub(crate) async fn emit_stop(
1441 &self,
1442 code: StopCode,
1443 coord: Coord,
1444 ) -> Result<DeliveryOutcome, ValidationError> {
1445 if self.control.stop_emitted.swap(true, Ordering::AcqRel) {
1446 return Ok(DeliveryOutcome::Rejected);
1447 }
1448 self.control.latch_stop();
1449 let _serial = self.serial.lock().await;
1450 if self.control.cancel.is_cancelled() {
1451 return Ok(DeliveryOutcome::Rejected);
1452 }
1453 self.emit_locked(Event::driver_stop(code, coord), None)
1454 .await
1455 .map(|resolution| resolution.outward)
1456 }
1457}
1458
1459#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1461#[non_exhaustive]
1462pub enum ToolEmitError {
1463 Closed,
1465 Rejected,
1467 Invalid(ValidationError),
1469}
1470
1471impl fmt::Display for ToolEmitError {
1472 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1473 match self {
1474 Self::Closed => formatter.write_str("tool invocation emit window is closed"),
1475 Self::Rejected => formatter.write_str("tool invocation event was not delivered"),
1476 Self::Invalid(error) => write!(formatter, "invalid tool invocation event: {error}"),
1477 }
1478 }
1479}
1480
1481impl Error for ToolEmitError {
1482 fn source(&self) -> Option<&(dyn Error + 'static)> {
1483 match self {
1484 Self::Invalid(error) => Some(error),
1485 Self::Closed | Self::Rejected => None,
1486 }
1487 }
1488}
1489
1490struct Outward {
1491 producer: Arc<Producer>,
1492 coord: Coord,
1493}
1494
1495enum EmitTarget {
1496 Closed,
1497 Open(Outward),
1498}
1499
1500struct EmitterState {
1501 target: EmitTarget,
1502 active: usize,
1503}
1504
1505struct ToolEmitterInner {
1506 state: SyncMutex<EmitterState>,
1507 idle: Notify,
1508 #[cfg(test)]
1514 pause: SyncMutex<Option<Arc<TestEmitPause>>>,
1515}
1516
1517impl ToolEmitterInner {
1518 #[cfg(test)]
1519 async fn pause(&self) {
1520 let pause = self
1521 .pause
1522 .lock()
1523 .expect("tool emitter pause lock poisoned")
1524 .take();
1525 if let Some(pause) = pause {
1526 let _observer_may_be_gone = pause.reached.send(());
1527 pause
1528 .resume
1529 .acquire()
1530 .await
1531 .expect("tool emitter pause remains open")
1532 .forget();
1533 }
1534 }
1535
1536 fn enter(&self) -> Option<(ActiveEmit<'_>, Arc<Producer>, Coord)> {
1537 let mut state = self.state.lock().expect("tool emitter lock poisoned");
1538 match &state.target {
1539 EmitTarget::Closed => None,
1540 EmitTarget::Open(outward) => {
1541 let producer = Arc::clone(&outward.producer);
1542 let coord = outward.coord.clone();
1543 state.active += 1;
1544 Some((ActiveEmit { inner: self }, producer, coord))
1545 }
1546 }
1547 }
1548
1549 fn leave(&self) {
1550 let mut state = self.state.lock().expect("tool emitter lock poisoned");
1551 state.active -= 1;
1552 if state.active == 0 {
1553 self.idle.notify_waiters();
1554 }
1555 }
1556
1557 fn close(&self) {
1558 self.state
1559 .lock()
1560 .expect("tool emitter lock poisoned")
1561 .target = EmitTarget::Closed;
1562 }
1563
1564 async fn drain(&self) {
1565 loop {
1566 let idle = self.idle.notified();
1567 tokio::pin!(idle);
1568 let _already_ready = idle.as_mut().enable();
1569 if self
1570 .state
1571 .lock()
1572 .expect("tool emitter lock poisoned")
1573 .active
1574 == 0
1575 {
1576 return;
1577 }
1578 idle.await;
1579 }
1580 }
1581}
1582
1583struct ActiveEmit<'a> {
1585 inner: &'a ToolEmitterInner,
1586}
1587
1588impl Drop for ActiveEmit<'_> {
1589 fn drop(&mut self) {
1590 self.inner.leave();
1591 }
1592}
1593
1594pub struct ToolEmitter {
1612 inner: Arc<ToolEmitterInner>,
1613}
1614
1615impl fmt::Debug for ToolEmitter {
1616 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1623 formatter.debug_struct("ToolEmitter").finish()
1624 }
1625}
1626
1627impl ToolEmitter {
1628 #[must_use]
1634 pub fn closed() -> Self {
1635 Self {
1636 inner: Arc::new(ToolEmitterInner {
1637 state: SyncMutex::new(EmitterState {
1638 target: EmitTarget::Closed,
1639 active: 0,
1640 }),
1641 idle: Notify::new(),
1642 #[cfg(test)]
1643 pause: SyncMutex::new(None),
1644 }),
1645 }
1646 }
1647
1648 pub async fn emit_audit(&self, audit: audit::Event) -> Result<(), ToolEmitError> {
1661 let event = Event::from_audit(audit).map_err(ToolEmitError::Invalid)?;
1662 self.emit_extension(event).await
1663 }
1664
1665 pub async fn emit_error(
1677 &self,
1678 error: Arc<dyn Error + Send + Sync>,
1679 ) -> Result<(), ToolEmitError> {
1680 self.emit_extension(Event::from_error(error)).await
1681 }
1682
1683 async fn emit_extension(&self, event: Event) -> Result<(), ToolEmitError> {
1684 let Some((_active, producer, coord)) = self.inner.enter() else {
1685 return Err(ToolEmitError::Closed);
1686 };
1687 #[cfg(test)]
1688 self.inner.pause().await;
1689 let outcome = producer.emit_extension(event, coord).await;
1690 if matches!(outcome, Ok(DeliveryOutcome::Delivered)) {
1694 Ok(())
1695 } else {
1696 Err(ToolEmitError::Rejected)
1697 }
1698 }
1699}
1700
1701pub(crate) struct ToolEmitterGate {
1703 inner: Arc<ToolEmitterInner>,
1704}
1705
1706impl ToolEmitterGate {
1707 pub(crate) async fn close_and_wait(self) {
1709 self.inner.close();
1710 self.inner.drain().await;
1711 }
1712}
1713
1714pub(crate) fn tool_emitter(
1716 producer: &Arc<Producer>,
1717 coord: Coord,
1718) -> (ToolEmitter, ToolEmitterGate) {
1719 let inner = Arc::new(ToolEmitterInner {
1720 state: SyncMutex::new(EmitterState {
1721 target: EmitTarget::Open(Outward {
1722 producer: Arc::clone(producer),
1723 coord,
1724 }),
1725 active: 0,
1726 }),
1727 idle: Notify::new(),
1728 #[cfg(test)]
1729 pause: SyncMutex::new(None),
1730 });
1731 (
1732 ToolEmitter {
1733 inner: Arc::clone(&inner),
1734 },
1735 ToolEmitterGate { inner },
1736 )
1737}
1738
1739pub(crate) struct EventSource {
1740 stream: Option<Stream>,
1741 control: Arc<Control>,
1742}
1743
1744#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1745pub(crate) struct StreamTakenError;
1746
1747impl EventSource {
1748 pub(crate) fn take_stream(&mut self) -> Result<Stream, StreamTakenError> {
1749 self.stream.take().ok_or(StreamTakenError)
1750 }
1751
1752 pub(crate) fn request_stop(&self) {
1753 self.control.request_stop();
1754 }
1755
1756 pub(crate) fn terminal_intent(&self) -> TerminalIntent {
1757 self.control.intent()
1758 }
1759
1760 pub(crate) async fn interruption(&self) {
1768 self.control.interruption.cancelled().await;
1769 }
1770
1771 pub(crate) fn latch_failure(&self) -> Option<ValidationError> {
1772 self.control.fail(None)
1773 }
1774
1775 #[cfg(test)]
1776 fn state(&self) -> (bool, bool, bool) {
1777 (
1778 self.control.nonfatal.frozen() == NONFATAL_STOPPED,
1779 self.control.fatal.load(Ordering::Acquire),
1780 self.control.cancel.is_cancelled(),
1781 )
1782 }
1783}
1784
1785pub(crate) fn channel(parent: &Token) -> (Arc<Producer>, EventSource) {
1795 let (sender, receiver) = mpsc::unbounded_channel();
1796 let nonfatal = Arc::new(NonfatalCause {
1797 parent: parent.clone(),
1798 cause: SyncMutex::new(NONFATAL_NONE),
1799 });
1800 let control = Arc::new(Control {
1801 nonfatal,
1802 fatal: AtomicBool::new(false),
1803 fatal_event: SyncMutex::new(None),
1804 stop_emitted: AtomicBool::new(false),
1805 pending: SyncMutex::new(None),
1806 cancel: parent.child_token(),
1807 interruption: Token::new(),
1808 #[cfg(test)]
1809 before_reject_pause: SyncMutex::new(None),
1810 #[cfg(test)]
1811 after_final_confirm_pause: SyncMutex::new(None),
1812 });
1813 let producer = Arc::new(Producer {
1814 sender,
1815 control: control.clone(),
1816 serial: Mutex::new(()),
1817 });
1818 let stream = Stream {
1819 receiver,
1820 control: control.clone(),
1821 };
1822 (
1823 producer,
1824 EventSource {
1825 stream: Some(stream),
1826 control,
1827 },
1828 )
1829}
1830
1831#[cfg(test)]
1832pub(crate) mod testing {
1833 use super::*;
1834
1835 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
1842 pub(crate) enum Emission {
1843 Content,
1845 Lifecycle,
1847 ToolCall,
1849 ToolResult,
1851 Extension,
1853 Stop,
1855 Input,
1858 }
1859
1860 pub(crate) const fn emission(kind: Kind) -> Emission {
1877 match kind {
1878 Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking => {
1879 Emission::Content
1880 }
1881 Kind::TurnStart
1882 | Kind::TurnEnd
1883 | Kind::StepStart
1884 | Kind::StepEnd
1885 | Kind::GenerationEnd => Emission::Lifecycle,
1886 Kind::ToolCall => Emission::ToolCall,
1887 Kind::ToolResult => Emission::ToolResult,
1888 Kind::Audit | Kind::Error => Emission::Extension,
1889 Kind::Stop => Emission::Stop,
1890 Kind::InputAdmitted | Kind::InputRejected => Emission::Input,
1891 }
1892 }
1893
1894 pub(crate) const ALL_KINDS: &[Kind] = &[
1896 Kind::TextDelta,
1897 Kind::Text,
1898 Kind::ThinkingDelta,
1899 Kind::Thinking,
1900 Kind::TurnStart,
1901 Kind::TurnEnd,
1902 Kind::StepStart,
1903 Kind::StepEnd,
1904 Kind::GenerationEnd,
1905 Kind::ToolCall,
1906 Kind::ToolResult,
1907 Kind::Error,
1908 Kind::Audit,
1909 Kind::Stop,
1910 Kind::InputAdmitted,
1911 Kind::InputRejected,
1912 ];
1913
1914 pub(crate) fn text(kind: Kind, text: &str, coord: Coord) -> Event {
1915 Event::driver_text(kind, text.into(), coord, None)
1916 }
1917
1918 pub(crate) fn lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Event {
1919 Event::driver_lifecycle(kind, outcome, coord)
1920 }
1921
1922 pub(crate) fn tool_call(call: ToolCall, coord: Coord) -> Event {
1923 Event::driver_tool_call(call, coord)
1924 }
1925
1926 pub(crate) fn tool_result(result: item::ToolResult, coord: Coord) -> Event {
1927 Event::driver_tool_result(result, coord)
1928 }
1929
1930 pub(crate) fn stop(code: StopCode, coord: Coord) -> Event {
1931 Event::driver_stop(code, coord)
1932 }
1933
1934 pub(crate) fn input_admitted(
1935 origin: InputOrigin,
1936 items: Vec<item::Item>,
1937 coord: Coord,
1938 ) -> Event {
1939 Event::driver_input_admitted(origin, items, coord)
1940 }
1941
1942 pub(crate) fn input_rejected(reason: String, coord: Coord) -> Event {
1943 Event::driver_input_rejected(reason, coord)
1944 }
1945
1946 pub(crate) fn forged(kind: Kind, event: Event) -> Event {
1947 Event { kind, ..event }
1948 }
1949
1950 pub(crate) fn invalid_audit(coord: Coord) -> Event {
1951 Event {
1952 kind: Kind::Audit,
1953 coord: Some(coord),
1954 item_id: None,
1955 payload: Payload::Audit(audit::Event::new(String::new(), None)),
1956 }
1957 }
1958
1959 pub(crate) fn invalid_stop(coord: Coord) -> Event {
1960 Event {
1961 kind: Kind::Stop,
1962 coord: Some(coord),
1963 item_id: None,
1964 payload: Payload::Stop(StopCode(String::new())),
1965 }
1966 }
1967
1968 pub(crate) fn control(source: &EventSource) -> (bool, bool, bool) {
1969 source.state()
1970 }
1971
1972 pub(crate) use super::FreezePoint;
1973
1974 #[derive(Clone)]
1975 pub(crate) struct InterruptionProbe(Arc<Control>);
1976
1977 impl InterruptionProbe {
1978 pub(crate) fn request_stop(&self) {
1979 self.0.request_stop();
1980 }
1981
1982 pub(crate) fn fail(&self) {
1983 let _first_event_error = self.0.fail(Some(ValidationError::PayloadMismatch));
1984 }
1985 }
1986
1987 pub(crate) fn interruption_probe(source: &EventSource) -> InterruptionProbe {
1988 InterruptionProbe(Arc::clone(&source.control))
1989 }
1990
1991 pub(crate) struct FreezePauseProbe {
1992 reached: Arc<std::sync::Barrier>,
1993 resume: Arc<std::sync::Barrier>,
1994 }
1995
1996 impl FreezePauseProbe {
1997 pub(crate) fn wait_until_frozen(&self) {
1998 self.reached.wait();
1999 }
2000
2001 pub(crate) fn resume_rejection(&self) {
2002 self.resume.wait();
2003 }
2004 }
2005
2006 pub(crate) fn pause_before_reject(
2007 source: &EventSource,
2008 point: FreezePoint,
2009 ) -> (InterruptionProbe, FreezePauseProbe) {
2010 let reached = Arc::new(std::sync::Barrier::new(2));
2011 let resume = Arc::new(std::sync::Barrier::new(2));
2012 *source
2013 .control
2014 .before_reject_pause
2015 .lock()
2016 .expect("event freeze pause lock poisoned") = Some(TestFreezePause {
2017 point,
2018 reached: Arc::clone(&reached),
2019 resume: Arc::clone(&resume),
2020 });
2021 (
2022 interruption_probe(source),
2023 FreezePauseProbe { reached, resume },
2024 )
2025 }
2026
2027 pub(crate) struct FinalConfirmPauseProbe(Arc<TestFinalConfirmPause>);
2028
2029 impl FinalConfirmPauseProbe {
2030 pub(crate) async fn wait_until_confirmed(&self) {
2031 self.0
2032 .reached
2033 .acquire()
2034 .await
2035 .expect("event final-confirm pause remains open")
2036 .forget();
2037 }
2038
2039 pub(crate) fn resume_return(&self) {
2040 self.0.resume.add_permits(1);
2041 }
2042 }
2043
2044 pub(crate) fn pause_after_final_confirm(source: &EventSource) -> FinalConfirmPauseProbe {
2045 let pause = Arc::new(TestFinalConfirmPause {
2046 reached: Semaphore::new(0),
2047 resume: Semaphore::new(0),
2048 });
2049 *source
2050 .control
2051 .after_final_confirm_pause
2052 .lock()
2053 .expect("event final-confirm pause lock poisoned") = Some(Arc::clone(&pause));
2054 FinalConfirmPauseProbe(pause)
2055 }
2056
2057 pub(crate) fn intent(source: &EventSource) -> TerminalIntent {
2058 source.terminal_intent()
2059 }
2060
2061 pub(crate) fn has_pending_strong_decision(source: &EventSource) -> bool {
2062 source
2063 .control
2064 .pending
2065 .lock()
2066 .expect("event pending lock poisoned")
2067 .is_some()
2068 }
2069
2070 pub(crate) fn stale_pending_guard_preserves_successor(source: &EventSource) -> (bool, bool) {
2071 let decision = || {
2072 Arc::new(Decision {
2073 value: AtomicU8::new(PENDING),
2074 changed: Notify::new(),
2075 cancel: source.control.cancel.clone(),
2076 nonfatal: Arc::clone(&source.control.nonfatal),
2077 after_pending_check: SyncMutex::new(None),
2078 })
2079 };
2080 let stale = decision();
2081 source.control.register(&stale);
2082 let stale_guard = PendingDecision {
2083 control: &source.control,
2084 decision: Arc::clone(&stale),
2085 };
2086 let successor = decision();
2087 source.control.register(&successor);
2088
2089 drop(stale_guard);
2090 let successor_preserved = source
2091 .control
2092 .pending
2093 .lock()
2094 .expect("event pending lock poisoned")
2095 .as_ref()
2096 .is_some_and(|pending| Arc::ptr_eq(pending, &successor));
2097 let stale_abandoned = stale.decide(ACCEPTED) == Err(DecisionError::AlreadyDecided);
2098 source.control.reject_pending();
2099 (successor_preserved, stale_abandoned)
2100 }
2101
2102 #[derive(Clone)]
2103 pub(crate) struct EmitterProbe(Arc<ToolEmitterInner>);
2104
2105 impl EmitterProbe {
2106 pub(crate) fn state(&self) -> (bool, usize) {
2107 let state = self.0.state.lock().expect("tool emitter lock poisoned");
2108 (matches!(state.target, EmitTarget::Closed), state.active)
2109 }
2110 }
2111
2112 pub(crate) fn emitter_probe(emitter: &ToolEmitter) -> EmitterProbe {
2113 EmitterProbe(Arc::clone(&emitter.inner))
2114 }
2115
2116 #[derive(Clone)]
2118 pub(crate) struct EmitPauseProbe(Arc<TestEmitPause>);
2119
2120 impl EmitPauseProbe {
2121 pub(crate) fn new(reached: std::sync::mpsc::Sender<()>) -> Self {
2123 Self(Arc::new(TestEmitPause {
2124 reached,
2125 resume: Semaphore::new(0),
2126 }))
2127 }
2128
2129 pub(crate) fn arm(&self, emitter: &ToolEmitter) {
2131 *emitter
2132 .inner
2133 .pause
2134 .lock()
2135 .expect("tool emitter pause lock poisoned") = Some(Arc::clone(&self.0));
2136 }
2137
2138 pub(crate) fn resume(&self) {
2139 self.0.resume.add_permits(1);
2140 }
2141 }
2142
2143 pub(crate) fn cancel_lane(source: &EventSource) {
2150 source.control.cancel.cancel();
2151 }
2152
2153 pub(crate) fn fail(source: &EventSource) {
2154 let _first_event_error = source.control.fail(Some(ValidationError::PayloadMismatch));
2155 }
2156
2157 #[derive(Clone)]
2158 pub(crate) struct DecisionProbe(Arc<Decision>);
2159
2160 impl DecisionProbe {
2161 pub(crate) fn plain(cancel: Token) -> Self {
2162 let nonfatal = Arc::new(NonfatalCause {
2163 parent: cancel.clone(),
2164 cause: SyncMutex::new(NONFATAL_NONE),
2165 });
2166 Self(Arc::new(Decision {
2167 value: AtomicU8::new(PENDING),
2168 changed: Notify::new(),
2169 cancel,
2170 nonfatal,
2171 after_pending_check: SyncMutex::new(None),
2172 }))
2173 }
2174
2175 pub(crate) fn paused_after_pending_check(
2176 cancel: Token,
2177 ) -> (Self, Arc<std::sync::Barrier>, Arc<std::sync::Barrier>) {
2178 let checked = Arc::new(std::sync::Barrier::new(2));
2179 let resume = Arc::new(std::sync::Barrier::new(2));
2180 let nonfatal = Arc::new(NonfatalCause {
2181 parent: cancel.clone(),
2182 cause: SyncMutex::new(NONFATAL_NONE),
2183 });
2184 let decision = Arc::new(Decision {
2185 value: AtomicU8::new(PENDING),
2186 changed: Notify::new(),
2187 cancel,
2188 nonfatal,
2189 after_pending_check: SyncMutex::new(Some(WaitBarriers {
2190 checked: checked.clone(),
2191 resume: resume.clone(),
2192 })),
2193 });
2194 (Self(decision), checked, resume)
2195 }
2196
2197 pub(crate) fn accept(&self) -> Result<(), DecisionError> {
2198 self.0.decide_consumer(ACCEPTED)
2199 }
2200
2201 pub(crate) fn reject(&self) -> Result<(), DecisionError> {
2202 self.0.decide_consumer(REJECTED)
2203 }
2204
2205 pub(crate) async fn wait(&self) -> StrongDecision {
2206 self.0.wait().await
2207 }
2208 }
2209
2210 pub(crate) fn register_probe(source: &EventSource) -> bool {
2211 let decision = DecisionProbe::plain(source.control.cancel.clone()).0;
2212 source.control.register(&decision);
2213 decision.value.load(Ordering::Acquire) == REJECTED
2214 }
2215
2216 pub(crate) fn tool_emitter_active(emitter: &ToolEmitter) -> usize {
2219 emitter
2220 .inner
2221 .state
2222 .lock()
2223 .expect("tool emitter lock poisoned")
2224 .active
2225 }
2226}
2227
2228#[cfg(feature = "serde")]
2240mod serde_impl {
2241 use std::fmt::{self, Formatter};
2242
2243 use serde_core::de::{
2244 Deserialize, Deserializer, EnumAccess, Error as DeError, VariantAccess, Visitor,
2245 };
2246 use serde_core::ser::{Serialize, Serializer};
2247
2248 use super::Kind;
2249 use crate::wire::IdentifierSeed;
2250
2251 const NAME: &str = "Kind";
2252 const VARIANTS: &[&str] = &[
2253 "text_delta",
2254 "text",
2255 "thinking_delta",
2256 "thinking",
2257 "turn_start",
2258 "turn_end",
2259 "step_start",
2260 "step_end",
2261 "generation_end",
2262 "tool_call",
2263 "tool_result",
2264 "error",
2265 "audit",
2266 "stop",
2267 "input_admitted",
2268 "input_rejected",
2269 ];
2270
2271 impl Serialize for Kind {
2272 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
2273 where
2274 S: Serializer,
2275 {
2276 let (index, tag) = match self {
2277 Self::TextDelta => (0, "text_delta"),
2278 Self::Text => (1, "text"),
2279 Self::ThinkingDelta => (2, "thinking_delta"),
2280 Self::Thinking => (3, "thinking"),
2281 Self::TurnStart => (4, "turn_start"),
2282 Self::TurnEnd => (5, "turn_end"),
2283 Self::StepStart => (6, "step_start"),
2284 Self::StepEnd => (7, "step_end"),
2285 Self::GenerationEnd => (8, "generation_end"),
2286 Self::ToolCall => (9, "tool_call"),
2287 Self::ToolResult => (10, "tool_result"),
2288 Self::Error => (11, "error"),
2289 Self::Audit => (12, "audit"),
2290 Self::Stop => (13, "stop"),
2291 Self::InputAdmitted => (14, "input_admitted"),
2292 Self::InputRejected => (15, "input_rejected"),
2293 };
2294 serializer.serialize_unit_variant(NAME, index, tag)
2295 }
2296 }
2297
2298 impl<'de> Deserialize<'de> for Kind {
2299 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
2300 where
2301 D: Deserializer<'de>,
2302 {
2303 deserializer.deserialize_enum(NAME, VARIANTS, KindVisitor)
2304 }
2305 }
2306
2307 struct KindVisitor;
2308
2309 impl<'de> Visitor<'de> for KindVisitor {
2310 type Value = Kind;
2311
2312 fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
2313 formatter.write_str("an outward event kind")
2314 }
2315
2316 fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
2317 where
2318 A: EnumAccess<'de>,
2319 {
2320 let (tag, variant) = data.variant_seed(IdentifierSeed(VARIANTS))?;
2321 variant.unit_variant()?;
2322 match tag.0.as_str() {
2323 "text_delta" => Ok(Kind::TextDelta),
2324 "text" => Ok(Kind::Text),
2325 "thinking_delta" => Ok(Kind::ThinkingDelta),
2326 "thinking" => Ok(Kind::Thinking),
2327 "turn_start" => Ok(Kind::TurnStart),
2328 "turn_end" => Ok(Kind::TurnEnd),
2329 "step_start" => Ok(Kind::StepStart),
2330 "step_end" => Ok(Kind::StepEnd),
2331 "generation_end" => Ok(Kind::GenerationEnd),
2332 "tool_call" => Ok(Kind::ToolCall),
2333 "tool_result" => Ok(Kind::ToolResult),
2334 "error" => Ok(Kind::Error),
2335 "audit" => Ok(Kind::Audit),
2336 "stop" => Ok(Kind::Stop),
2337 "input_admitted" => Ok(Kind::InputAdmitted),
2338 "input_rejected" => Ok(Kind::InputRejected),
2339 unknown => Err(A::Error::unknown_variant(unknown, VARIANTS)),
2340 }
2341 }
2342 }
2343}