1use std::error::Error;
18use std::fmt;
19use std::pin::Pin;
20use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
21use std::sync::{Arc, Mutex as SyncMutex};
22use std::task::{Context, Poll};
23
24use crate::cancel::Token;
25#[cfg(test)]
26use tokio::sync::Semaphore;
27use tokio::sync::{Mutex, Notify, mpsc};
28
29use crate::audit;
30use crate::redact;
31use crate::transcript::item;
32use crate::value::lifecycle::{Coord, Outcome};
33use crate::value::tool_call::ToolCall;
34
35#[derive(Clone, Copy, Debug, Eq, PartialEq)]
80#[non_exhaustive]
81pub enum Kind {
82 TextDelta,
84 Text,
86 ThinkingDelta,
88 Thinking,
90 TurnStart,
92 TurnEnd,
94 StepStart,
96 StepEnd,
98 GenerationEnd,
100 ToolCall,
102 ToolResult,
104 Error,
106 Audit,
108 Stop,
110 InputAdmitted,
126 InputRejected,
136}
137
138#[derive(Clone, Copy, Debug, Eq, PartialEq)]
146#[non_exhaustive]
147pub enum InputOrigin {
148 Start,
157 Mailbox,
161 Continuation,
164}
165
166#[derive(Clone, Debug)]
174pub struct AdmittedInput {
175 origin: InputOrigin,
176 items: Vec<item::Item>,
177}
178
179impl AdmittedInput {
180 #[must_use]
182 pub const fn origin(&self) -> InputOrigin {
183 self.origin
184 }
185
186 #[must_use]
188 pub fn items(&self) -> &[item::Item] {
189 &self.items
190 }
191}
192
193#[derive(Clone, Copy, Debug, Eq, PartialEq)]
195#[non_exhaustive]
196pub enum DecisionPoint {
197 ToolCall,
199 ToolResult,
201 AfterToolCommit,
203}
204
205#[derive(Clone, Debug, Eq, PartialEq)]
207pub struct StopCode(String);
208
209impl StopCode {
210 pub fn new(code: String) -> Result<Self, ValidationError> {
219 if code.is_empty() {
220 return Err(ValidationError::EmptyStopCode);
221 }
222 Ok(Self(code))
223 }
224
225 #[must_use]
227 pub fn as_str(&self) -> &str {
228 &self.0
229 }
230}
231
232#[derive(Clone, Copy, Debug, Eq, PartialEq)]
234#[non_exhaustive]
235pub enum ValidationError {
236 EmptyAuditKind,
238 EmptyToolCallId,
240 EmptyToolName,
242 EmptyStopCode,
244 PayloadMismatch,
246 InvalidDecisionPoint,
248}
249
250impl fmt::Display for ValidationError {
251 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
252 formatter.write_str(match self {
253 Self::EmptyAuditKind => "event audit kind must be non-empty",
254 Self::EmptyToolCallId => "event tool-call identity must be non-empty",
255 Self::EmptyToolName => "event tool name must be non-empty",
256 Self::EmptyStopCode => "event stop code must be non-empty",
257 Self::PayloadMismatch => "event category and payload do not match",
258 Self::InvalidDecisionPoint => "event used an invalid decision point",
259 })
260 }
261}
262
263impl Error for ValidationError {}
264
265#[derive(Clone)]
266enum Payload {
267 Text(String),
268 Lifecycle(Option<Outcome>),
269 ToolCall(ToolCall),
270 ToolResult(item::ToolResult),
271 Audit(audit::Event),
272 Error(Arc<dyn Error + Send + Sync>),
273 Stop(StopCode),
274 Input(AdmittedInput),
275 Rejection(String),
276}
277
278impl fmt::Debug for Payload {
279 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
286 match self {
287 Self::Text(text) => formatter
288 .debug_tuple("Text")
289 .field(&redact::Bytes(text.len()))
290 .finish(),
291 Self::Lifecycle(outcome) => formatter.debug_tuple("Lifecycle").field(outcome).finish(),
292 Self::ToolCall(call) => formatter.debug_tuple("ToolCall").field(call).finish(),
293 Self::ToolResult(result) => formatter.debug_tuple("ToolResult").field(result).finish(),
294 Self::Audit(audit) => formatter.debug_tuple("Audit").field(audit).finish(),
295 Self::Error(error) => formatter
296 .debug_tuple("Error")
297 .field(&error.to_string())
298 .finish(),
299 Self::Stop(code) => formatter.debug_tuple("Stop").field(code).finish(),
300 Self::Input(input) => formatter.debug_tuple("Input").field(input).finish(),
303 Self::Rejection(reason) => formatter.debug_tuple("Rejection").field(reason).finish(),
304 }
305 }
306}
307
308#[derive(Clone, Debug)]
310pub struct Event {
311 kind: Kind,
312 coord: Option<Coord>,
313 item_id: Option<String>,
314 payload: Payload,
315}
316
317impl Event {
318 pub fn from_audit(audit: audit::Event) -> Result<Self, ValidationError> {
330 if audit.kind().is_empty() {
331 return Err(ValidationError::EmptyAuditKind);
332 }
333 Ok(Self {
334 kind: Kind::Audit,
335 coord: None,
336 item_id: None,
337 payload: Payload::Audit(audit),
338 })
339 }
340
341 #[must_use]
343 pub fn from_error(error: Arc<dyn Error + Send + Sync>) -> Self {
344 Self {
345 kind: Kind::Error,
346 coord: None,
347 item_id: None,
348 payload: Payload::Error(error),
349 }
350 }
351
352 #[must_use]
354 pub const fn kind(&self) -> Kind {
355 self.kind
356 }
357
358 #[must_use]
360 pub const fn coord(&self) -> Option<&Coord> {
361 self.coord.as_ref()
362 }
363
364 #[must_use]
393 pub fn item_id(&self) -> Option<&str> {
394 self.item_id.as_deref()
395 }
396
397 #[must_use]
399 pub fn text(&self) -> Option<&str> {
400 match &self.payload {
401 Payload::Text(text) => Some(text),
402 _ => None,
403 }
404 }
405
406 #[must_use]
408 pub const fn tool_call(&self) -> Option<&ToolCall> {
409 match &self.payload {
410 Payload::ToolCall(call) => Some(call),
411 _ => None,
412 }
413 }
414
415 #[must_use]
417 pub const fn tool_result(&self) -> Option<&item::ToolResult> {
418 match &self.payload {
419 Payload::ToolResult(result) => Some(result),
420 _ => None,
421 }
422 }
423
424 #[must_use]
429 pub const fn admitted_input(&self) -> Option<&AdmittedInput> {
430 match &self.payload {
431 Payload::Input(input) => Some(input),
432 _ => None,
433 }
434 }
435
436 #[must_use]
441 pub fn rejection_reason(&self) -> Option<&str> {
442 match &self.payload {
443 Payload::Rejection(reason) => Some(reason),
444 _ => None,
445 }
446 }
447
448 #[must_use]
450 pub const fn outcome(&self) -> Option<Outcome> {
451 match self.payload {
452 Payload::Lifecycle(outcome) => outcome,
453 _ => None,
454 }
455 }
456
457 #[must_use]
459 pub const fn as_audit(&self) -> Option<&audit::Event> {
460 match &self.payload {
461 Payload::Audit(audit) => Some(audit),
462 _ => None,
463 }
464 }
465
466 #[must_use]
468 pub fn as_error(&self) -> Option<&(dyn Error + Send + Sync)> {
469 match &self.payload {
470 Payload::Error(error) => Some(error.as_ref()),
471 _ => None,
472 }
473 }
474
475 #[must_use]
477 pub const fn stop_code(&self) -> Option<&StopCode> {
478 match &self.payload {
479 Payload::Stop(code) => Some(code),
480 _ => None,
481 }
482 }
483
484 const fn driver_text(kind: Kind, text: String, coord: Coord, item_id: Option<String>) -> Self {
485 Self {
486 kind,
487 coord: Some(coord),
488 item_id,
489 payload: Payload::Text(text),
490 }
491 }
492
493 const fn driver_lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Self {
494 Self {
495 kind,
496 coord: Some(coord),
497 item_id: None,
498 payload: Payload::Lifecycle(outcome),
499 }
500 }
501
502 const fn driver_tool_call(call: ToolCall, coord: Coord) -> Self {
503 Self {
504 kind: Kind::ToolCall,
505 coord: Some(coord),
506 item_id: None,
507 payload: Payload::ToolCall(call),
508 }
509 }
510
511 const fn driver_tool_result(result: item::ToolResult, coord: Coord) -> Self {
512 Self {
513 kind: Kind::ToolResult,
514 coord: Some(coord),
515 item_id: None,
516 payload: Payload::ToolResult(result),
517 }
518 }
519
520 const fn driver_stop(code: StopCode, coord: Coord) -> Self {
521 Self {
522 kind: Kind::Stop,
523 coord: Some(coord),
524 item_id: None,
525 payload: Payload::Stop(code),
526 }
527 }
528
529 const fn driver_input_admitted(
530 origin: InputOrigin,
531 items: Vec<item::Item>,
532 coord: Coord,
533 ) -> Self {
534 Self {
535 kind: Kind::InputAdmitted,
536 coord: Some(coord),
537 item_id: None,
538 payload: Payload::Input(AdmittedInput { origin, items }),
539 }
540 }
541
542 const fn driver_input_rejected(reason: String, coord: Coord) -> Self {
543 Self {
544 kind: Kind::InputRejected,
545 coord: Some(coord),
546 item_id: None,
547 payload: Payload::Rejection(reason),
548 }
549 }
550
551 fn validate(&self, decision_point: Option<DecisionPoint>) -> Result<(), ValidationError> {
552 if !payload_matches(self.kind, &self.payload) {
553 return Err(ValidationError::PayloadMismatch);
554 }
555 match &self.payload {
556 Payload::ToolCall(call) if call.id().as_str().is_empty() => {
557 Err(ValidationError::EmptyToolCallId)
558 }
559 Payload::ToolCall(call) if call.name().as_str().is_empty() => {
560 Err(ValidationError::EmptyToolName)
561 }
562 Payload::ToolResult(result) if result.call_id().as_str().is_empty() => {
563 Err(ValidationError::EmptyToolCallId)
564 }
565 Payload::ToolResult(result) if result.tool_name().as_str().is_empty() => {
566 Err(ValidationError::EmptyToolName)
567 }
568 Payload::Audit(audit) if audit.kind().is_empty() => {
569 Err(ValidationError::EmptyAuditKind)
570 }
571 Payload::Stop(code) if code.as_str().is_empty() => Err(ValidationError::EmptyStopCode),
572 _ if decision_point != expected_decision_point(self.kind, decision_point) => {
573 Err(ValidationError::InvalidDecisionPoint)
574 }
575 _ => Ok(()),
576 }
577 }
578}
579
580const fn payload_matches(kind: Kind, payload: &Payload) -> bool {
581 matches!(
582 (kind, payload),
583 (
584 Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking,
585 Payload::Text(_)
586 ) | (Kind::TurnStart | Kind::StepStart, Payload::Lifecycle(None))
587 | (
588 Kind::TurnEnd | Kind::StepEnd | Kind::GenerationEnd,
589 Payload::Lifecycle(Some(_))
590 )
591 | (Kind::ToolCall, Payload::ToolCall(_))
592 | (Kind::ToolResult, Payload::ToolResult(_))
593 | (Kind::Error, Payload::Error(_))
594 | (Kind::Audit, Payload::Audit(_))
595 | (Kind::Stop, Payload::Stop(_))
596 | (Kind::InputAdmitted, Payload::Input(_))
597 | (Kind::InputRejected, Payload::Rejection(_))
598 )
599}
600
601fn expected_decision_point(kind: Kind, requested: Option<DecisionPoint>) -> Option<DecisionPoint> {
602 match kind {
603 Kind::ToolCall => Some(DecisionPoint::ToolCall),
604 Kind::ToolResult => Some(DecisionPoint::ToolResult),
605 Kind::Audit | Kind::Error if requested == Some(DecisionPoint::AfterToolCommit) => requested,
606 _ => None,
607 }
608}
609
610#[derive(Clone, Copy, Debug, Eq, PartialEq)]
612#[non_exhaustive]
613pub enum DecisionError {
614 NotRequired,
616 AlreadyDecided,
618}
619
620impl fmt::Display for DecisionError {
621 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
622 formatter.write_str(match self {
623 Self::NotRequired => "event delivery does not require acceptance",
624 Self::AlreadyDecided => "event delivery was already decided",
625 })
626 }
627}
628
629impl Error for DecisionError {}
630
631const PENDING: u8 = 0;
632const ACCEPTED: u8 = 1;
633const REJECTED: u8 = 2;
634const CANCELED: u8 = 3;
635
636struct Decision {
637 value: AtomicU8,
638 changed: Notify,
639 cancel: Token,
641 nonfatal: Arc<NonfatalCause>,
647 #[cfg(test)]
648 after_pending_check: SyncMutex<Option<WaitBarriers>>,
649}
650
651#[cfg(test)]
652struct WaitBarriers {
653 checked: Arc<std::sync::Barrier>,
654 resume: Arc<std::sync::Barrier>,
655}
656
657impl Decision {
658 fn decide(&self, value: u8) -> Result<(), DecisionError> {
659 self.value
660 .compare_exchange(PENDING, value, Ordering::AcqRel, Ordering::Acquire)
661 .map(|_| self.changed.notify_waiters())
662 .map_err(|_| DecisionError::AlreadyDecided)
663 }
664
665 fn decide_consumer(&self, value: u8) -> Result<(), DecisionError> {
666 if self.cancel.is_cancelled() {
667 let _already_decided = self.decide(self.nonfatal.interrupted_decision());
668 Err(DecisionError::AlreadyDecided)
669 } else {
670 self.decide(value)
671 }
672 }
673
674 fn abandon(&self) -> Result<(), DecisionError> {
675 let value = if self.cancel.is_cancelled() {
676 self.nonfatal.interrupted_decision()
677 } else {
678 REJECTED
679 };
680 self.decide(value)
681 }
682
683 async fn wait(&self) -> StrongDecision {
684 loop {
685 let changed = self.changed.notified();
686 tokio::pin!(changed);
687 let _already_ready = changed.as_mut().enable();
688 match self.value.load(Ordering::Acquire) {
689 ACCEPTED => return StrongDecision::Accepted,
690 REJECTED => return StrongDecision::Rejected,
691 CANCELED => return StrongDecision::Cancelled,
692 _ => {
693 #[cfg(test)]
694 self.pause_after_pending_check();
695 tokio::select! {
696 biased;
697 () = self.cancel.cancelled() => {
698 let _already_decided =
699 self.decide(self.nonfatal.interrupted_decision());
700 }
701 () = &mut changed => {}
702 }
703 }
704 }
705 }
706 }
707
708 #[cfg(test)]
709 fn pause_after_pending_check(&self) {
710 let barriers = self
711 .after_pending_check
712 .lock()
713 .expect("event wait barrier lock poisoned")
714 .take();
715 if let Some(barriers) = barriers {
716 barriers.checked.wait();
717 barriers.resume.wait();
718 }
719 }
720}
721
722pub struct Delivery {
754 event: Event,
755 decision_point: Option<DecisionPoint>,
756 decision: Option<Arc<Decision>>,
757}
758
759impl fmt::Debug for Delivery {
760 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
767 formatter
768 .debug_struct("Delivery")
769 .field("event", &self.event)
770 .field("decision_point", &self.decision_point)
771 .field("decision", &redact::Presence(self.decision.is_some()))
772 .finish()
773 }
774}
775
776impl Delivery {
777 #[must_use]
779 pub const fn event(&self) -> &Event {
780 &self.event
781 }
782
783 #[must_use]
785 pub const fn decision_point(&self) -> Option<DecisionPoint> {
786 self.decision_point
787 }
788
789 pub fn accept(&self) -> Result<(), DecisionError> {
806 self.decision
807 .as_ref()
808 .ok_or(DecisionError::NotRequired)?
809 .decide_consumer(ACCEPTED)
810 }
811
812 pub fn reject(&self) -> Result<(), DecisionError> {
832 self.decision
833 .as_ref()
834 .ok_or(DecisionError::NotRequired)?
835 .decide_consumer(REJECTED)
836 }
837}
838
839impl Drop for Delivery {
840 fn drop(&mut self) {
841 if let Some(decision) = &self.decision {
842 let _already_decided = decision.abandon();
843 }
844 }
845}
846
847pub struct Stream {
880 receiver: mpsc::UnboundedReceiver<Delivery>,
881 control: Arc<Control>,
882}
883
884impl fmt::Debug for Stream {
885 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
891 formatter
892 .debug_struct("Stream")
893 .field("fatal", &self.control.fatal.load(Ordering::Relaxed))
894 .finish()
895 }
896}
897
898impl Stream {
899 pub async fn recv(&mut self) -> Option<Delivery> {
901 self.receiver.recv().await
902 }
903}
904
905impl futures_core::Stream for Stream {
906 type Item = Delivery;
907
908 fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
909 self.receiver.poll_recv(context)
910 }
911}
912
913impl Drop for Stream {
914 fn drop(&mut self) {
915 self.control.request_stop();
916 self.receiver.close();
917 }
918}
919
920#[derive(Clone, Copy, Debug, Eq, PartialEq)]
921pub(crate) enum DeliveryOutcome {
922 Delivered,
923 Accepted,
924 Rejected,
925}
926
927#[derive(Clone, Copy, Debug, Eq, PartialEq)]
931pub(crate) enum StrongDecision {
932 Accepted,
933 Rejected,
934 Cancelled,
935}
936
937impl From<StrongDecision> for DeliveryOutcome {
938 fn from(decision: StrongDecision) -> Self {
939 match decision {
940 StrongDecision::Accepted => Self::Accepted,
941 StrongDecision::Rejected | StrongDecision::Cancelled => Self::Rejected,
942 }
943 }
944}
945
946#[derive(Clone, Copy, Debug, Eq, PartialEq)]
947struct DeliveryResolution {
948 outward: DeliveryOutcome,
949 strong: Option<StrongDecision>,
950}
951
952impl DeliveryResolution {
953 const fn ordinary(outward: DeliveryOutcome) -> Self {
954 Self {
955 outward,
956 strong: None,
957 }
958 }
959
960 fn strong(decision: StrongDecision) -> Self {
961 Self {
962 outward: decision.into(),
963 strong: Some(decision),
964 }
965 }
966}
967
968#[derive(Clone, Copy, Debug, Eq, PartialEq)]
969pub(crate) enum TerminalIntent {
970 Running,
971 Stopped,
972 Cancelled,
973 Failed,
974}
975
976impl TerminalIntent {
977 #[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
978 pub(crate) const fn outcome(self) -> Option<Outcome> {
979 match self {
980 Self::Running => None,
981 Self::Stopped => Some(Outcome::Stopped),
982 Self::Cancelled => Some(Outcome::Cancelled),
983 Self::Failed => Some(Outcome::Failed),
984 }
985 }
986}
987
988const NONFATAL_NONE: u8 = 0;
990const NONFATAL_STOPPED: u8 = 1;
992const NONFATAL_CANCELED: u8 = 2;
994
995struct NonfatalCause {
1008 parent: Token,
1010 cause: SyncMutex<u8>,
1011}
1012
1013impl NonfatalCause {
1014 fn freeze(&self, normal_stop: bool) -> u8 {
1024 let mut cause = self
1025 .cause
1026 .lock()
1027 .expect("event nonfatal cause lock poisoned");
1028 if *cause == NONFATAL_NONE {
1029 if self.parent.is_cancelled() {
1030 *cause = NONFATAL_CANCELED;
1031 } else if normal_stop {
1032 *cause = NONFATAL_STOPPED;
1033 }
1034 }
1035 *cause
1036 }
1037
1038 #[cfg(test)]
1040 fn frozen(&self) -> u8 {
1041 *self
1042 .cause
1043 .lock()
1044 .expect("event nonfatal cause lock poisoned")
1045 }
1046
1047 fn interrupted_decision(&self) -> u8 {
1049 if self.freeze(false) == NONFATAL_CANCELED {
1050 CANCELED
1051 } else {
1052 REJECTED
1053 }
1054 }
1055}
1056
1057#[cfg(test)]
1058#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1059pub(crate) enum FreezePoint {
1060 Stop,
1061 Fatal,
1062}
1063
1064#[cfg(test)]
1065struct TestFreezePause {
1066 point: FreezePoint,
1067 reached: Arc<std::sync::Barrier>,
1068 resume: Arc<std::sync::Barrier>,
1069}
1070
1071#[cfg(test)]
1072struct TestFinalConfirmPause {
1073 reached: Semaphore,
1074 resume: Semaphore,
1075}
1076
1077#[cfg(test)]
1082struct TestEmitPause {
1083 reached: std::sync::mpsc::Sender<()>,
1084 resume: Semaphore,
1085}
1086
1087struct Control {
1088 nonfatal: Arc<NonfatalCause>,
1090 fatal: AtomicBool,
1091 fatal_event: SyncMutex<Option<ValidationError>>,
1092 stop_emitted: AtomicBool,
1093 pending: SyncMutex<Option<Arc<Decision>>>,
1094 cancel: Token,
1097 interruption: Token,
1098 #[cfg(test)]
1099 before_reject_pause: SyncMutex<Option<TestFreezePause>>,
1100 #[cfg(test)]
1101 after_final_confirm_pause: SyncMutex<Option<Arc<TestFinalConfirmPause>>>,
1102}
1103
1104struct PendingDecision<'a> {
1111 control: &'a Control,
1112 decision: Arc<Decision>,
1113}
1114
1115impl Drop for PendingDecision<'_> {
1116 fn drop(&mut self) {
1117 let _already_decided = self.decision.abandon();
1122 self.control.clear(&self.decision);
1123 }
1124}
1125
1126impl Control {
1127 fn intent(&self) -> TerminalIntent {
1128 if self.fatal.load(Ordering::Acquire) {
1131 return TerminalIntent::Failed;
1132 }
1133 match self.nonfatal.freeze(false) {
1136 NONFATAL_CANCELED => TerminalIntent::Cancelled,
1137 NONFATAL_STOPPED => TerminalIntent::Stopped,
1138 _ => TerminalIntent::Running,
1139 }
1140 }
1141
1142 fn strong_interruption(&self) -> Option<StrongDecision> {
1143 if self.fatal.load(Ordering::Acquire) {
1144 return Some(StrongDecision::Rejected);
1145 }
1146 match self.nonfatal.freeze(false) {
1147 NONFATAL_CANCELED => Some(StrongDecision::Cancelled),
1148 NONFATAL_STOPPED => Some(StrongDecision::Rejected),
1149 _ => None,
1150 }
1151 }
1152
1153 fn final_confirm_strong(&self, decision: StrongDecision) -> StrongDecision {
1161 if decision == StrongDecision::Accepted {
1162 self.strong_interruption().unwrap_or(decision)
1163 } else {
1164 decision
1165 }
1166 }
1167
1168 #[cfg(test)]
1169 fn pause_before_reject(&self, point: FreezePoint) {
1170 let pause = {
1171 let mut slot = self
1172 .before_reject_pause
1173 .lock()
1174 .expect("event freeze pause lock poisoned");
1175 if slot.as_ref().is_some_and(|pause| pause.point == point) {
1176 slot.take()
1177 } else {
1178 None
1179 }
1180 };
1181 if let Some(pause) = pause {
1182 pause.reached.wait();
1183 pause.resume.wait();
1184 }
1185 }
1186
1187 #[cfg(test)]
1188 async fn pause_after_final_confirm(&self) {
1189 let pause = self
1190 .after_final_confirm_pause
1191 .lock()
1192 .expect("event final-confirm pause lock poisoned")
1193 .take();
1194 if let Some(pause) = pause {
1195 pause.reached.add_permits(1);
1196 pause
1197 .resume
1198 .acquire()
1199 .await
1200 .expect("event final-confirm pause remains open")
1201 .forget();
1202 }
1203 }
1204
1205 fn interrupted(&self) -> bool {
1210 self.fatal.load(Ordering::Acquire) || self.nonfatal.freeze(false) != NONFATAL_NONE
1211 }
1212
1213 fn register(&self, decision: &Arc<Decision>) {
1214 let mut pending = self.pending.lock().expect("event pending lock poisoned");
1215 if self.interrupted() {
1216 let _already_decided = decision.decide(self.nonfatal.interrupted_decision());
1217 } else {
1218 *pending = Some(decision.clone());
1219 }
1220 }
1221
1222 fn clear(&self, decision: &Arc<Decision>) {
1223 let mut pending = self.pending.lock().expect("event pending lock poisoned");
1224 if pending
1225 .as_ref()
1226 .is_some_and(|current| Arc::ptr_eq(current, decision))
1227 {
1228 pending.take();
1229 }
1230 }
1231
1232 fn reject_pending(&self) {
1234 let decided = self.nonfatal.interrupted_decision();
1235 if let Some(decision) = self
1236 .pending
1237 .lock()
1238 .expect("event pending lock poisoned")
1239 .take()
1240 {
1241 let _already_decided = decision.decide(decided);
1242 }
1243 }
1244
1245 fn latch_stop(&self) {
1247 let _cause = self.nonfatal.freeze(true);
1248 #[cfg(test)]
1249 self.pause_before_reject(FreezePoint::Stop);
1250 self.reject_pending();
1251 self.interruption.cancel();
1252 }
1253
1254 fn request_stop(&self) {
1255 self.latch_stop();
1256 self.cancel.cancel();
1259 }
1260
1261 fn fail(&self, event_error: Option<ValidationError>) -> Option<ValidationError> {
1262 let first_event_error = {
1263 let mut fatal_event = self
1264 .fatal_event
1265 .lock()
1266 .expect("event fatal latch lock poisoned");
1267 if !self.fatal.load(Ordering::Acquire) {
1268 *fatal_event = event_error;
1269 self.fatal.store(true, Ordering::Release);
1270 }
1271 *fatal_event
1272 };
1273 #[cfg(test)]
1274 self.pause_before_reject(FreezePoint::Fatal);
1275 self.reject_pending();
1276 self.interruption.cancel();
1277 self.cancel.cancel();
1278 first_event_error
1279 }
1280}
1281
1282pub(crate) struct Producer {
1283 sender: mpsc::UnboundedSender<Delivery>,
1284 control: Arc<Control>,
1285 serial: Mutex<()>,
1286}
1287
1288impl Producer {
1289 pub(crate) async fn emit_text(
1290 &self,
1291 kind: Kind,
1292 text: String,
1293 coord: Coord,
1294 item_id: Option<String>,
1295 ) -> Result<DeliveryOutcome, ValidationError> {
1296 self.emit(Event::driver_text(kind, text, coord, item_id), None)
1297 .await
1298 }
1299
1300 pub(crate) async fn emit_lifecycle(
1301 &self,
1302 kind: Kind,
1303 outcome: Option<Outcome>,
1304 coord: Coord,
1305 ) -> Result<DeliveryOutcome, ValidationError> {
1306 self.emit(Event::driver_lifecycle(kind, outcome, coord), None)
1307 .await
1308 }
1309
1310 pub(crate) async fn emit_input_admitted(
1311 &self,
1312 origin: InputOrigin,
1313 items: Vec<item::Item>,
1314 coord: Coord,
1315 ) -> Result<DeliveryOutcome, ValidationError> {
1316 self.emit(Event::driver_input_admitted(origin, items, coord), None)
1317 .await
1318 }
1319
1320 pub(crate) async fn emit_input_rejected(
1321 &self,
1322 reason: String,
1323 coord: Coord,
1324 ) -> Result<DeliveryOutcome, ValidationError> {
1325 self.emit(Event::driver_input_rejected(reason, coord), None)
1326 .await
1327 }
1328
1329 pub(crate) async fn emit_tool_call(
1330 &self,
1331 call: ToolCall,
1332 coord: Coord,
1333 ) -> Result<StrongDecision, ValidationError> {
1334 self.emit_strong(
1335 Event::driver_tool_call(call, coord),
1336 DecisionPoint::ToolCall,
1337 )
1338 .await
1339 }
1340
1341 pub(crate) async fn emit_tool_result(
1342 &self,
1343 result: item::ToolResult,
1344 coord: Coord,
1345 ) -> Result<StrongDecision, ValidationError> {
1346 self.emit_strong(
1347 Event::driver_tool_result(result, coord),
1348 DecisionPoint::ToolResult,
1349 )
1350 .await
1351 }
1352
1353 pub(crate) async fn emit_extension(
1354 &self,
1355 mut event: Event,
1356 coord: Coord,
1357 ) -> Result<DeliveryOutcome, ValidationError> {
1358 event.coord = Some(coord);
1359 self.emit(event, None).await
1360 }
1361
1362 pub(crate) async fn emit_after_tool_commit(
1363 &self,
1364 mut event: Event,
1365 coord: Coord,
1366 ) -> Result<StrongDecision, ValidationError> {
1367 event.coord = Some(coord);
1368 self.emit_strong(event, DecisionPoint::AfterToolCommit)
1369 .await
1370 }
1371
1372 pub(crate) async fn emit(
1373 &self,
1374 event: Event,
1375 decision_point: Option<DecisionPoint>,
1376 ) -> Result<DeliveryOutcome, ValidationError> {
1377 if let Some(decision_point) = decision_point {
1378 return self
1379 .emit_strong(event, decision_point)
1380 .await
1381 .map(Into::into);
1382 }
1383 let _serial = self.serial.lock().await;
1384 if self.control.interrupted() {
1385 return Ok(DeliveryOutcome::Rejected);
1386 }
1387 self.emit_locked(event, None)
1388 .await
1389 .map(|resolution| resolution.outward)
1390 }
1391
1392 async fn emit_strong(
1393 &self,
1394 event: Event,
1395 decision_point: DecisionPoint,
1396 ) -> Result<StrongDecision, ValidationError> {
1397 let _serial = self.serial.lock().await;
1398 if let Some(decision) = self.control.strong_interruption() {
1399 return Ok(decision);
1400 }
1401 Ok(self
1402 .emit_locked(event, Some(decision_point))
1403 .await?
1404 .strong
1405 .expect("a strong decision point always has a decision"))
1406 }
1407
1408 async fn emit_locked(
1409 &self,
1410 event: Event,
1411 decision_point: Option<DecisionPoint>,
1412 ) -> Result<DeliveryResolution, ValidationError> {
1413 if let Err(error) = event.validate(decision_point) {
1414 let _first_event_error = self.control.fail(Some(error));
1415 return Err(error);
1416 }
1417 let decision = decision_point.map(|_| {
1418 Arc::new(Decision {
1419 value: AtomicU8::new(PENDING),
1420 changed: Notify::new(),
1421 cancel: self.control.cancel.clone(),
1422 nonfatal: Arc::clone(&self.control.nonfatal),
1423 #[cfg(test)]
1424 after_pending_check: SyncMutex::new(None),
1425 })
1426 });
1427 let _pending = decision.as_ref().map(|decision| {
1428 self.control.register(decision);
1429 PendingDecision {
1430 control: &self.control,
1431 decision: Arc::clone(decision),
1432 }
1433 });
1434 let delivery = Delivery {
1435 event,
1436 decision_point,
1437 decision: decision.clone(),
1438 };
1439 let delivered = !self.control.cancel.is_cancelled() && self.sender.send(delivery).is_ok();
1445 let outcome = if let Some(decision) = &decision {
1446 if !delivered {
1447 let _already_decided = decision.abandon();
1448 }
1449 let decision = self.control.final_confirm_strong(decision.wait().await);
1450 #[cfg(test)]
1451 self.control.pause_after_final_confirm().await;
1452 DeliveryResolution::strong(decision)
1453 } else {
1454 DeliveryResolution::ordinary(if delivered {
1455 DeliveryOutcome::Delivered
1456 } else {
1457 DeliveryOutcome::Rejected
1458 })
1459 };
1460 Ok(outcome)
1461 }
1462
1463 pub(crate) async fn emit_stop(
1464 &self,
1465 code: StopCode,
1466 coord: Coord,
1467 ) -> Result<DeliveryOutcome, ValidationError> {
1468 if self.control.stop_emitted.swap(true, Ordering::AcqRel) {
1469 return Ok(DeliveryOutcome::Rejected);
1470 }
1471 self.control.latch_stop();
1472 let _serial = self.serial.lock().await;
1473 if self.control.cancel.is_cancelled() {
1474 return Ok(DeliveryOutcome::Rejected);
1475 }
1476 self.emit_locked(Event::driver_stop(code, coord), None)
1477 .await
1478 .map(|resolution| resolution.outward)
1479 }
1480}
1481
1482#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1484#[non_exhaustive]
1485pub enum ToolEmitError {
1486 Closed,
1488 Rejected,
1490 Invalid(ValidationError),
1492}
1493
1494impl fmt::Display for ToolEmitError {
1495 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1496 match self {
1497 Self::Closed => formatter.write_str("tool invocation emit window is closed"),
1498 Self::Rejected => formatter.write_str("tool invocation event was not delivered"),
1499 Self::Invalid(error) => write!(formatter, "invalid tool invocation event: {error}"),
1500 }
1501 }
1502}
1503
1504impl Error for ToolEmitError {
1505 fn source(&self) -> Option<&(dyn Error + 'static)> {
1506 match self {
1507 Self::Invalid(error) => Some(error),
1508 Self::Closed | Self::Rejected => None,
1509 }
1510 }
1511}
1512
1513struct Outward {
1514 producer: Arc<Producer>,
1515 coord: Coord,
1516}
1517
1518enum EmitTarget {
1519 Closed,
1520 Open(Outward),
1521}
1522
1523struct EmitterState {
1524 target: EmitTarget,
1525 active: usize,
1526}
1527
1528struct ToolEmitterInner {
1529 state: SyncMutex<EmitterState>,
1530 idle: Notify,
1531 #[cfg(test)]
1537 pause: SyncMutex<Option<Arc<TestEmitPause>>>,
1538}
1539
1540impl ToolEmitterInner {
1541 #[cfg(test)]
1542 async fn pause(&self) {
1543 let pause = self
1544 .pause
1545 .lock()
1546 .expect("tool emitter pause lock poisoned")
1547 .take();
1548 if let Some(pause) = pause {
1549 let _observer_may_be_gone = pause.reached.send(());
1550 pause
1551 .resume
1552 .acquire()
1553 .await
1554 .expect("tool emitter pause remains open")
1555 .forget();
1556 }
1557 }
1558
1559 fn enter(&self) -> Option<(ActiveEmit<'_>, Arc<Producer>, Coord)> {
1560 let mut state = self.state.lock().expect("tool emitter lock poisoned");
1561 match &state.target {
1562 EmitTarget::Closed => None,
1563 EmitTarget::Open(outward) => {
1564 let producer = Arc::clone(&outward.producer);
1565 let coord = outward.coord.clone();
1566 state.active += 1;
1567 Some((ActiveEmit { inner: self }, producer, coord))
1568 }
1569 }
1570 }
1571
1572 fn leave(&self) {
1573 let mut state = self.state.lock().expect("tool emitter lock poisoned");
1574 state.active -= 1;
1575 if state.active == 0 {
1576 self.idle.notify_waiters();
1577 }
1578 }
1579
1580 fn close(&self) {
1581 self.state
1582 .lock()
1583 .expect("tool emitter lock poisoned")
1584 .target = EmitTarget::Closed;
1585 }
1586
1587 async fn drain(&self) {
1588 loop {
1589 let idle = self.idle.notified();
1590 tokio::pin!(idle);
1591 let _already_ready = idle.as_mut().enable();
1592 if self
1593 .state
1594 .lock()
1595 .expect("tool emitter lock poisoned")
1596 .active
1597 == 0
1598 {
1599 return;
1600 }
1601 idle.await;
1602 }
1603 }
1604}
1605
1606struct ActiveEmit<'a> {
1608 inner: &'a ToolEmitterInner,
1609}
1610
1611impl Drop for ActiveEmit<'_> {
1612 fn drop(&mut self) {
1613 self.inner.leave();
1614 }
1615}
1616
1617pub struct ToolEmitter {
1635 inner: Arc<ToolEmitterInner>,
1636}
1637
1638impl fmt::Debug for ToolEmitter {
1639 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1646 formatter.debug_struct("ToolEmitter").finish()
1647 }
1648}
1649
1650impl ToolEmitter {
1651 #[must_use]
1657 pub fn closed() -> Self {
1658 Self {
1659 inner: Arc::new(ToolEmitterInner {
1660 state: SyncMutex::new(EmitterState {
1661 target: EmitTarget::Closed,
1662 active: 0,
1663 }),
1664 idle: Notify::new(),
1665 #[cfg(test)]
1666 pause: SyncMutex::new(None),
1667 }),
1668 }
1669 }
1670
1671 pub async fn emit_audit(&self, audit: audit::Event) -> Result<(), ToolEmitError> {
1684 let event = Event::from_audit(audit).map_err(ToolEmitError::Invalid)?;
1685 self.emit_extension(event).await
1686 }
1687
1688 pub async fn emit_error(
1700 &self,
1701 error: Arc<dyn Error + Send + Sync>,
1702 ) -> Result<(), ToolEmitError> {
1703 self.emit_extension(Event::from_error(error)).await
1704 }
1705
1706 async fn emit_extension(&self, event: Event) -> Result<(), ToolEmitError> {
1707 let Some((_active, producer, coord)) = self.inner.enter() else {
1708 return Err(ToolEmitError::Closed);
1709 };
1710 #[cfg(test)]
1711 self.inner.pause().await;
1712 let outcome = producer.emit_extension(event, coord).await;
1713 if matches!(outcome, Ok(DeliveryOutcome::Delivered)) {
1717 Ok(())
1718 } else {
1719 Err(ToolEmitError::Rejected)
1720 }
1721 }
1722}
1723
1724pub(crate) struct ToolEmitterGate {
1726 inner: Arc<ToolEmitterInner>,
1727}
1728
1729impl ToolEmitterGate {
1730 pub(crate) async fn close_and_wait(self) {
1732 self.inner.close();
1733 self.inner.drain().await;
1734 }
1735}
1736
1737pub(crate) fn tool_emitter(
1739 producer: &Arc<Producer>,
1740 coord: Coord,
1741) -> (ToolEmitter, ToolEmitterGate) {
1742 let inner = Arc::new(ToolEmitterInner {
1743 state: SyncMutex::new(EmitterState {
1744 target: EmitTarget::Open(Outward {
1745 producer: Arc::clone(producer),
1746 coord,
1747 }),
1748 active: 0,
1749 }),
1750 idle: Notify::new(),
1751 #[cfg(test)]
1752 pause: SyncMutex::new(None),
1753 });
1754 (
1755 ToolEmitter {
1756 inner: Arc::clone(&inner),
1757 },
1758 ToolEmitterGate { inner },
1759 )
1760}
1761
1762pub(crate) struct EventSource {
1763 stream: Option<Stream>,
1764 control: Arc<Control>,
1765}
1766
1767#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1768pub(crate) struct StreamTakenError;
1769
1770impl EventSource {
1771 pub(crate) fn take_stream(&mut self) -> Result<Stream, StreamTakenError> {
1772 self.stream.take().ok_or(StreamTakenError)
1773 }
1774
1775 pub(crate) fn request_stop(&self) {
1776 self.control.request_stop();
1777 }
1778
1779 pub(crate) fn terminal_intent(&self) -> TerminalIntent {
1780 self.control.intent()
1781 }
1782
1783 pub(crate) async fn interruption(&self) {
1791 self.control.interruption.cancelled().await;
1792 }
1793
1794 pub(crate) fn latch_failure(&self) -> Option<ValidationError> {
1795 self.control.fail(None)
1796 }
1797
1798 #[cfg(test)]
1799 fn state(&self) -> (bool, bool, bool) {
1800 (
1801 self.control.nonfatal.frozen() == NONFATAL_STOPPED,
1802 self.control.fatal.load(Ordering::Acquire),
1803 self.control.cancel.is_cancelled(),
1804 )
1805 }
1806}
1807
1808pub(crate) fn channel(parent: &Token) -> (Arc<Producer>, EventSource) {
1818 let (sender, receiver) = mpsc::unbounded_channel();
1819 let nonfatal = Arc::new(NonfatalCause {
1820 parent: parent.clone(),
1821 cause: SyncMutex::new(NONFATAL_NONE),
1822 });
1823 let control = Arc::new(Control {
1824 nonfatal,
1825 fatal: AtomicBool::new(false),
1826 fatal_event: SyncMutex::new(None),
1827 stop_emitted: AtomicBool::new(false),
1828 pending: SyncMutex::new(None),
1829 cancel: parent.child_token(),
1830 interruption: Token::new(),
1831 #[cfg(test)]
1832 before_reject_pause: SyncMutex::new(None),
1833 #[cfg(test)]
1834 after_final_confirm_pause: SyncMutex::new(None),
1835 });
1836 let producer = Arc::new(Producer {
1837 sender,
1838 control: control.clone(),
1839 serial: Mutex::new(()),
1840 });
1841 let stream = Stream {
1842 receiver,
1843 control: control.clone(),
1844 };
1845 (
1846 producer,
1847 EventSource {
1848 stream: Some(stream),
1849 control,
1850 },
1851 )
1852}
1853
1854#[cfg(test)]
1855pub(crate) mod testing {
1856 use super::*;
1857
1858 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
1865 pub(crate) enum Emission {
1866 Content,
1868 Lifecycle,
1870 ToolCall,
1872 ToolResult,
1874 Extension,
1876 Stop,
1878 Input,
1881 }
1882
1883 pub(crate) const fn emission(kind: Kind) -> Emission {
1900 match kind {
1901 Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking => {
1902 Emission::Content
1903 }
1904 Kind::TurnStart
1905 | Kind::TurnEnd
1906 | Kind::StepStart
1907 | Kind::StepEnd
1908 | Kind::GenerationEnd => Emission::Lifecycle,
1909 Kind::ToolCall => Emission::ToolCall,
1910 Kind::ToolResult => Emission::ToolResult,
1911 Kind::Audit | Kind::Error => Emission::Extension,
1912 Kind::Stop => Emission::Stop,
1913 Kind::InputAdmitted | Kind::InputRejected => Emission::Input,
1914 }
1915 }
1916
1917 pub(crate) const ALL_KINDS: &[Kind] = &[
1919 Kind::TextDelta,
1920 Kind::Text,
1921 Kind::ThinkingDelta,
1922 Kind::Thinking,
1923 Kind::TurnStart,
1924 Kind::TurnEnd,
1925 Kind::StepStart,
1926 Kind::StepEnd,
1927 Kind::GenerationEnd,
1928 Kind::ToolCall,
1929 Kind::ToolResult,
1930 Kind::Error,
1931 Kind::Audit,
1932 Kind::Stop,
1933 Kind::InputAdmitted,
1934 Kind::InputRejected,
1935 ];
1936
1937 pub(crate) fn text(kind: Kind, text: &str, coord: Coord) -> Event {
1938 Event::driver_text(kind, text.into(), coord, None)
1939 }
1940
1941 pub(crate) fn lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Event {
1942 Event::driver_lifecycle(kind, outcome, coord)
1943 }
1944
1945 pub(crate) fn tool_call(call: ToolCall, coord: Coord) -> Event {
1946 Event::driver_tool_call(call, coord)
1947 }
1948
1949 pub(crate) fn tool_result(result: item::ToolResult, coord: Coord) -> Event {
1950 Event::driver_tool_result(result, coord)
1951 }
1952
1953 pub(crate) fn stop(code: StopCode, coord: Coord) -> Event {
1954 Event::driver_stop(code, coord)
1955 }
1956
1957 pub(crate) fn input_admitted(
1958 origin: InputOrigin,
1959 items: Vec<item::Item>,
1960 coord: Coord,
1961 ) -> Event {
1962 Event::driver_input_admitted(origin, items, coord)
1963 }
1964
1965 pub(crate) fn input_rejected(reason: String, coord: Coord) -> Event {
1966 Event::driver_input_rejected(reason, coord)
1967 }
1968
1969 pub(crate) fn forged(kind: Kind, event: Event) -> Event {
1970 Event { kind, ..event }
1971 }
1972
1973 pub(crate) fn invalid_audit(coord: Coord) -> Event {
1974 Event {
1975 kind: Kind::Audit,
1976 coord: Some(coord),
1977 item_id: None,
1978 payload: Payload::Audit(audit::Event::new(String::new(), None)),
1979 }
1980 }
1981
1982 pub(crate) fn invalid_stop(coord: Coord) -> Event {
1983 Event {
1984 kind: Kind::Stop,
1985 coord: Some(coord),
1986 item_id: None,
1987 payload: Payload::Stop(StopCode(String::new())),
1988 }
1989 }
1990
1991 pub(crate) fn control(source: &EventSource) -> (bool, bool, bool) {
1992 source.state()
1993 }
1994
1995 pub(crate) use super::FreezePoint;
1996
1997 #[derive(Clone)]
1998 pub(crate) struct InterruptionProbe(Arc<Control>);
1999
2000 impl InterruptionProbe {
2001 pub(crate) fn request_stop(&self) {
2002 self.0.request_stop();
2003 }
2004
2005 pub(crate) fn fail(&self) {
2006 let _first_event_error = self.0.fail(Some(ValidationError::PayloadMismatch));
2007 }
2008 }
2009
2010 pub(crate) fn interruption_probe(source: &EventSource) -> InterruptionProbe {
2011 InterruptionProbe(Arc::clone(&source.control))
2012 }
2013
2014 pub(crate) struct FreezePauseProbe {
2015 reached: Arc<std::sync::Barrier>,
2016 resume: Arc<std::sync::Barrier>,
2017 }
2018
2019 impl FreezePauseProbe {
2020 pub(crate) fn wait_until_frozen(&self) {
2021 self.reached.wait();
2022 }
2023
2024 pub(crate) fn resume_rejection(&self) {
2025 self.resume.wait();
2026 }
2027 }
2028
2029 pub(crate) fn pause_before_reject(
2030 source: &EventSource,
2031 point: FreezePoint,
2032 ) -> (InterruptionProbe, FreezePauseProbe) {
2033 let reached = Arc::new(std::sync::Barrier::new(2));
2034 let resume = Arc::new(std::sync::Barrier::new(2));
2035 *source
2036 .control
2037 .before_reject_pause
2038 .lock()
2039 .expect("event freeze pause lock poisoned") = Some(TestFreezePause {
2040 point,
2041 reached: Arc::clone(&reached),
2042 resume: Arc::clone(&resume),
2043 });
2044 (
2045 interruption_probe(source),
2046 FreezePauseProbe { reached, resume },
2047 )
2048 }
2049
2050 pub(crate) struct FinalConfirmPauseProbe(Arc<TestFinalConfirmPause>);
2051
2052 impl FinalConfirmPauseProbe {
2053 pub(crate) async fn wait_until_confirmed(&self) {
2054 self.0
2055 .reached
2056 .acquire()
2057 .await
2058 .expect("event final-confirm pause remains open")
2059 .forget();
2060 }
2061
2062 pub(crate) fn resume_return(&self) {
2063 self.0.resume.add_permits(1);
2064 }
2065 }
2066
2067 pub(crate) fn pause_after_final_confirm(source: &EventSource) -> FinalConfirmPauseProbe {
2068 let pause = Arc::new(TestFinalConfirmPause {
2069 reached: Semaphore::new(0),
2070 resume: Semaphore::new(0),
2071 });
2072 *source
2073 .control
2074 .after_final_confirm_pause
2075 .lock()
2076 .expect("event final-confirm pause lock poisoned") = Some(Arc::clone(&pause));
2077 FinalConfirmPauseProbe(pause)
2078 }
2079
2080 pub(crate) fn intent(source: &EventSource) -> TerminalIntent {
2081 source.terminal_intent()
2082 }
2083
2084 pub(crate) fn has_pending_strong_decision(source: &EventSource) -> bool {
2085 source
2086 .control
2087 .pending
2088 .lock()
2089 .expect("event pending lock poisoned")
2090 .is_some()
2091 }
2092
2093 pub(crate) fn stale_pending_guard_preserves_successor(source: &EventSource) -> (bool, bool) {
2094 let decision = || {
2095 Arc::new(Decision {
2096 value: AtomicU8::new(PENDING),
2097 changed: Notify::new(),
2098 cancel: source.control.cancel.clone(),
2099 nonfatal: Arc::clone(&source.control.nonfatal),
2100 after_pending_check: SyncMutex::new(None),
2101 })
2102 };
2103 let stale = decision();
2104 source.control.register(&stale);
2105 let stale_guard = PendingDecision {
2106 control: &source.control,
2107 decision: Arc::clone(&stale),
2108 };
2109 let successor = decision();
2110 source.control.register(&successor);
2111
2112 drop(stale_guard);
2113 let successor_preserved = source
2114 .control
2115 .pending
2116 .lock()
2117 .expect("event pending lock poisoned")
2118 .as_ref()
2119 .is_some_and(|pending| Arc::ptr_eq(pending, &successor));
2120 let stale_abandoned = stale.decide(ACCEPTED) == Err(DecisionError::AlreadyDecided);
2121 source.control.reject_pending();
2122 (successor_preserved, stale_abandoned)
2123 }
2124
2125 #[derive(Clone)]
2126 pub(crate) struct EmitterProbe(Arc<ToolEmitterInner>);
2127
2128 impl EmitterProbe {
2129 pub(crate) fn state(&self) -> (bool, usize) {
2130 let state = self.0.state.lock().expect("tool emitter lock poisoned");
2131 (matches!(state.target, EmitTarget::Closed), state.active)
2132 }
2133 }
2134
2135 pub(crate) fn emitter_probe(emitter: &ToolEmitter) -> EmitterProbe {
2136 EmitterProbe(Arc::clone(&emitter.inner))
2137 }
2138
2139 #[derive(Clone)]
2141 pub(crate) struct EmitPauseProbe(Arc<TestEmitPause>);
2142
2143 impl EmitPauseProbe {
2144 pub(crate) fn new(reached: std::sync::mpsc::Sender<()>) -> Self {
2146 Self(Arc::new(TestEmitPause {
2147 reached,
2148 resume: Semaphore::new(0),
2149 }))
2150 }
2151
2152 pub(crate) fn arm(&self, emitter: &ToolEmitter) {
2154 *emitter
2155 .inner
2156 .pause
2157 .lock()
2158 .expect("tool emitter pause lock poisoned") = Some(Arc::clone(&self.0));
2159 }
2160
2161 pub(crate) fn resume(&self) {
2162 self.0.resume.add_permits(1);
2163 }
2164 }
2165
2166 pub(crate) fn cancel_lane(source: &EventSource) {
2173 source.control.cancel.cancel();
2174 }
2175
2176 pub(crate) fn fail(source: &EventSource) {
2177 let _first_event_error = source.control.fail(Some(ValidationError::PayloadMismatch));
2178 }
2179
2180 #[derive(Clone)]
2181 pub(crate) struct DecisionProbe(Arc<Decision>);
2182
2183 impl DecisionProbe {
2184 pub(crate) fn plain(cancel: Token) -> Self {
2185 let nonfatal = Arc::new(NonfatalCause {
2186 parent: cancel.clone(),
2187 cause: SyncMutex::new(NONFATAL_NONE),
2188 });
2189 Self(Arc::new(Decision {
2190 value: AtomicU8::new(PENDING),
2191 changed: Notify::new(),
2192 cancel,
2193 nonfatal,
2194 after_pending_check: SyncMutex::new(None),
2195 }))
2196 }
2197
2198 pub(crate) fn paused_after_pending_check(
2199 cancel: Token,
2200 ) -> (Self, Arc<std::sync::Barrier>, Arc<std::sync::Barrier>) {
2201 let checked = Arc::new(std::sync::Barrier::new(2));
2202 let resume = Arc::new(std::sync::Barrier::new(2));
2203 let nonfatal = Arc::new(NonfatalCause {
2204 parent: cancel.clone(),
2205 cause: SyncMutex::new(NONFATAL_NONE),
2206 });
2207 let decision = Arc::new(Decision {
2208 value: AtomicU8::new(PENDING),
2209 changed: Notify::new(),
2210 cancel,
2211 nonfatal,
2212 after_pending_check: SyncMutex::new(Some(WaitBarriers {
2213 checked: checked.clone(),
2214 resume: resume.clone(),
2215 })),
2216 });
2217 (Self(decision), checked, resume)
2218 }
2219
2220 pub(crate) fn accept(&self) -> Result<(), DecisionError> {
2221 self.0.decide_consumer(ACCEPTED)
2222 }
2223
2224 pub(crate) fn reject(&self) -> Result<(), DecisionError> {
2225 self.0.decide_consumer(REJECTED)
2226 }
2227
2228 pub(crate) async fn wait(&self) -> StrongDecision {
2229 self.0.wait().await
2230 }
2231 }
2232
2233 pub(crate) fn register_probe(source: &EventSource) -> bool {
2234 let decision = DecisionProbe::plain(source.control.cancel.clone()).0;
2235 source.control.register(&decision);
2236 decision.value.load(Ordering::Acquire) == REJECTED
2237 }
2238
2239 pub(crate) fn tool_emitter_active(emitter: &ToolEmitter) -> usize {
2242 emitter
2243 .inner
2244 .state
2245 .lock()
2246 .expect("tool emitter lock poisoned")
2247 .active
2248 }
2249}
2250
2251#[cfg(feature = "serde")]
2264mod serde_impl {
2265 use std::fmt::{self, Formatter};
2266
2267 use serde_core::de::{
2268 Deserialize, Deserializer, EnumAccess, Error as DeError, VariantAccess, Visitor,
2269 };
2270 use serde_core::ser::{Serialize, Serializer};
2271
2272 use super::Kind;
2273 use crate::wire::IdentifierSeed;
2274
2275 const NAME: &str = "Kind";
2276 const VARIANTS: &[&str] = &[
2277 "text_delta",
2278 "text",
2279 "thinking_delta",
2280 "thinking",
2281 "turn_start",
2282 "turn_end",
2283 "step_start",
2284 "step_end",
2285 "generation_end",
2286 "tool_call",
2287 "tool_result",
2288 "error",
2289 "audit",
2290 "stop",
2291 "input_admitted",
2292 "input_rejected",
2293 ];
2294
2295 impl Serialize for Kind {
2296 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
2297 where
2298 S: Serializer,
2299 {
2300 let (index, tag) = match self {
2301 Self::TextDelta => (0, "text_delta"),
2302 Self::Text => (1, "text"),
2303 Self::ThinkingDelta => (2, "thinking_delta"),
2304 Self::Thinking => (3, "thinking"),
2305 Self::TurnStart => (4, "turn_start"),
2306 Self::TurnEnd => (5, "turn_end"),
2307 Self::StepStart => (6, "step_start"),
2308 Self::StepEnd => (7, "step_end"),
2309 Self::GenerationEnd => (8, "generation_end"),
2310 Self::ToolCall => (9, "tool_call"),
2311 Self::ToolResult => (10, "tool_result"),
2312 Self::Error => (11, "error"),
2313 Self::Audit => (12, "audit"),
2314 Self::Stop => (13, "stop"),
2315 Self::InputAdmitted => (14, "input_admitted"),
2316 Self::InputRejected => (15, "input_rejected"),
2317 };
2318 serializer.serialize_unit_variant(NAME, index, tag)
2319 }
2320 }
2321
2322 impl<'de> Deserialize<'de> for Kind {
2323 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
2324 where
2325 D: Deserializer<'de>,
2326 {
2327 deserializer.deserialize_enum(NAME, VARIANTS, KindVisitor)
2328 }
2329 }
2330
2331 struct KindVisitor;
2332
2333 impl<'de> Visitor<'de> for KindVisitor {
2334 type Value = Kind;
2335
2336 fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
2337 formatter.write_str("an outward event kind")
2338 }
2339
2340 fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
2341 where
2342 A: EnumAccess<'de>,
2343 {
2344 let (tag, variant) = data.variant_seed(IdentifierSeed(VARIANTS))?;
2345 variant.unit_variant()?;
2346 match tag.0.as_str() {
2347 "text_delta" => Ok(Kind::TextDelta),
2348 "text" => Ok(Kind::Text),
2349 "thinking_delta" => Ok(Kind::ThinkingDelta),
2350 "thinking" => Ok(Kind::Thinking),
2351 "turn_start" => Ok(Kind::TurnStart),
2352 "turn_end" => Ok(Kind::TurnEnd),
2353 "step_start" => Ok(Kind::StepStart),
2354 "step_end" => Ok(Kind::StepEnd),
2355 "generation_end" => Ok(Kind::GenerationEnd),
2356 "tool_call" => Ok(Kind::ToolCall),
2357 "tool_result" => Ok(Kind::ToolResult),
2358 "error" => Ok(Kind::Error),
2359 "audit" => Ok(Kind::Audit),
2360 "stop" => Ok(Kind::Stop),
2361 "input_admitted" => Ok(Kind::InputAdmitted),
2362 "input_rejected" => Ok(Kind::InputRejected),
2363 unknown => Err(A::Error::unknown_variant(unknown, VARIANTS)),
2364 }
2365 }
2366 }
2367}