use std::error::Error;
use std::fmt;
use std::pin::Pin;
use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
use std::sync::{Arc, Mutex as SyncMutex};
use std::task::{Context, Poll};
use crate::cancel::Token;
#[cfg(test)]
use tokio::sync::Semaphore;
use tokio::sync::{Mutex, Notify, mpsc};
use crate::audit;
use crate::redact;
use crate::transcript::item;
use crate::value::lifecycle::{Coord, Outcome};
use crate::value::tool_call::ToolCall;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Kind {
TextDelta,
Text,
ThinkingDelta,
Thinking,
TurnStart,
TurnEnd,
StepStart,
StepEnd,
GenerationEnd,
ToolCall,
ToolResult,
Error,
Audit,
Stop,
InputAdmitted,
InputRejected,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum InputOrigin {
Start,
Mailbox,
Continuation,
}
#[derive(Clone, Debug)]
pub struct AdmittedInput {
origin: InputOrigin,
items: Vec<item::Item>,
}
impl AdmittedInput {
#[must_use]
pub const fn origin(&self) -> InputOrigin {
self.origin
}
#[must_use]
pub fn items(&self) -> &[item::Item] {
&self.items
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum DecisionPoint {
ToolCall,
ToolResult,
AfterToolCommit,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StopCode(String);
impl StopCode {
pub fn new(code: String) -> Result<Self, ValidationError> {
if code.is_empty() {
return Err(ValidationError::EmptyStopCode);
}
Ok(Self(code))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ValidationError {
EmptyAuditKind,
EmptyToolCallId,
EmptyToolName,
EmptyStopCode,
PayloadMismatch,
InvalidDecisionPoint,
}
impl fmt::Display for ValidationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::EmptyAuditKind => "event audit kind must be non-empty",
Self::EmptyToolCallId => "event tool-call identity must be non-empty",
Self::EmptyToolName => "event tool name must be non-empty",
Self::EmptyStopCode => "event stop code must be non-empty",
Self::PayloadMismatch => "event category and payload do not match",
Self::InvalidDecisionPoint => "event used an invalid decision point",
})
}
}
impl Error for ValidationError {}
#[derive(Clone)]
enum Payload {
Text(String),
Lifecycle(Option<Outcome>),
ToolCall(ToolCall),
ToolResult(item::ToolResult),
Audit(audit::Event),
Error(Arc<dyn Error + Send + Sync>),
Stop(StopCode),
Input(AdmittedInput),
Rejection(String),
}
impl fmt::Debug for Payload {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Text(text) => formatter
.debug_tuple("Text")
.field(&redact::Bytes(text.len()))
.finish(),
Self::Lifecycle(outcome) => formatter.debug_tuple("Lifecycle").field(outcome).finish(),
Self::ToolCall(call) => formatter.debug_tuple("ToolCall").field(call).finish(),
Self::ToolResult(result) => formatter.debug_tuple("ToolResult").field(result).finish(),
Self::Audit(audit) => formatter.debug_tuple("Audit").field(audit).finish(),
Self::Error(error) => formatter
.debug_tuple("Error")
.field(&error.to_string())
.finish(),
Self::Stop(code) => formatter.debug_tuple("Stop").field(code).finish(),
Self::Input(input) => formatter.debug_tuple("Input").field(input).finish(),
Self::Rejection(reason) => formatter.debug_tuple("Rejection").field(reason).finish(),
}
}
}
#[derive(Clone, Debug)]
pub struct Event {
kind: Kind,
coord: Option<Coord>,
item_id: Option<String>,
payload: Payload,
}
impl Event {
pub fn from_audit(audit: audit::Event) -> Result<Self, ValidationError> {
if audit.kind().is_empty() {
return Err(ValidationError::EmptyAuditKind);
}
Ok(Self {
kind: Kind::Audit,
coord: None,
item_id: None,
payload: Payload::Audit(audit),
})
}
#[must_use]
pub fn from_error(error: Arc<dyn Error + Send + Sync>) -> Self {
Self {
kind: Kind::Error,
coord: None,
item_id: None,
payload: Payload::Error(error),
}
}
#[must_use]
pub const fn kind(&self) -> Kind {
self.kind
}
#[must_use]
pub const fn coord(&self) -> Option<&Coord> {
self.coord.as_ref()
}
#[must_use]
pub fn item_id(&self) -> Option<&str> {
self.item_id.as_deref()
}
#[must_use]
pub fn text(&self) -> Option<&str> {
match &self.payload {
Payload::Text(text) => Some(text),
_ => None,
}
}
#[must_use]
pub const fn tool_call(&self) -> Option<&ToolCall> {
match &self.payload {
Payload::ToolCall(call) => Some(call),
_ => None,
}
}
#[must_use]
pub const fn tool_result(&self) -> Option<&item::ToolResult> {
match &self.payload {
Payload::ToolResult(result) => Some(result),
_ => None,
}
}
#[must_use]
pub const fn admitted_input(&self) -> Option<&AdmittedInput> {
match &self.payload {
Payload::Input(input) => Some(input),
_ => None,
}
}
#[must_use]
pub fn rejection_reason(&self) -> Option<&str> {
match &self.payload {
Payload::Rejection(reason) => Some(reason),
_ => None,
}
}
#[must_use]
pub const fn outcome(&self) -> Option<Outcome> {
match self.payload {
Payload::Lifecycle(outcome) => outcome,
_ => None,
}
}
#[must_use]
pub const fn as_audit(&self) -> Option<&audit::Event> {
match &self.payload {
Payload::Audit(audit) => Some(audit),
_ => None,
}
}
#[must_use]
pub fn as_error(&self) -> Option<&(dyn Error + Send + Sync)> {
match &self.payload {
Payload::Error(error) => Some(error.as_ref()),
_ => None,
}
}
#[must_use]
pub const fn stop_code(&self) -> Option<&StopCode> {
match &self.payload {
Payload::Stop(code) => Some(code),
_ => None,
}
}
const fn driver_text(kind: Kind, text: String, coord: Coord, item_id: Option<String>) -> Self {
Self {
kind,
coord: Some(coord),
item_id,
payload: Payload::Text(text),
}
}
const fn driver_lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Self {
Self {
kind,
coord: Some(coord),
item_id: None,
payload: Payload::Lifecycle(outcome),
}
}
const fn driver_tool_call(call: ToolCall, coord: Coord) -> Self {
Self {
kind: Kind::ToolCall,
coord: Some(coord),
item_id: None,
payload: Payload::ToolCall(call),
}
}
const fn driver_tool_result(result: item::ToolResult, coord: Coord) -> Self {
Self {
kind: Kind::ToolResult,
coord: Some(coord),
item_id: None,
payload: Payload::ToolResult(result),
}
}
const fn driver_stop(code: StopCode, coord: Coord) -> Self {
Self {
kind: Kind::Stop,
coord: Some(coord),
item_id: None,
payload: Payload::Stop(code),
}
}
const fn driver_input_admitted(
origin: InputOrigin,
items: Vec<item::Item>,
coord: Coord,
) -> Self {
Self {
kind: Kind::InputAdmitted,
coord: Some(coord),
item_id: None,
payload: Payload::Input(AdmittedInput { origin, items }),
}
}
const fn driver_input_rejected(reason: String, coord: Coord) -> Self {
Self {
kind: Kind::InputRejected,
coord: Some(coord),
item_id: None,
payload: Payload::Rejection(reason),
}
}
fn validate(&self, decision_point: Option<DecisionPoint>) -> Result<(), ValidationError> {
if !payload_matches(self.kind, &self.payload) {
return Err(ValidationError::PayloadMismatch);
}
match &self.payload {
Payload::ToolCall(call) if call.id().as_str().is_empty() => {
Err(ValidationError::EmptyToolCallId)
}
Payload::ToolCall(call) if call.name().as_str().is_empty() => {
Err(ValidationError::EmptyToolName)
}
Payload::ToolResult(result) if result.call_id().as_str().is_empty() => {
Err(ValidationError::EmptyToolCallId)
}
Payload::ToolResult(result) if result.tool_name().as_str().is_empty() => {
Err(ValidationError::EmptyToolName)
}
Payload::Audit(audit) if audit.kind().is_empty() => {
Err(ValidationError::EmptyAuditKind)
}
Payload::Stop(code) if code.as_str().is_empty() => Err(ValidationError::EmptyStopCode),
_ if decision_point != expected_decision_point(self.kind, decision_point) => {
Err(ValidationError::InvalidDecisionPoint)
}
_ => Ok(()),
}
}
}
const fn payload_matches(kind: Kind, payload: &Payload) -> bool {
matches!(
(kind, payload),
(
Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking,
Payload::Text(_)
) | (Kind::TurnStart | Kind::StepStart, Payload::Lifecycle(None))
| (
Kind::TurnEnd | Kind::StepEnd | Kind::GenerationEnd,
Payload::Lifecycle(Some(_))
)
| (Kind::ToolCall, Payload::ToolCall(_))
| (Kind::ToolResult, Payload::ToolResult(_))
| (Kind::Error, Payload::Error(_))
| (Kind::Audit, Payload::Audit(_))
| (Kind::Stop, Payload::Stop(_))
| (Kind::InputAdmitted, Payload::Input(_))
| (Kind::InputRejected, Payload::Rejection(_))
)
}
fn expected_decision_point(kind: Kind, requested: Option<DecisionPoint>) -> Option<DecisionPoint> {
match kind {
Kind::ToolCall => Some(DecisionPoint::ToolCall),
Kind::ToolResult => Some(DecisionPoint::ToolResult),
Kind::Audit | Kind::Error if requested == Some(DecisionPoint::AfterToolCommit) => requested,
_ => None,
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum DecisionError {
NotRequired,
AlreadyDecided,
}
impl fmt::Display for DecisionError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::NotRequired => "event delivery does not require acceptance",
Self::AlreadyDecided => "event delivery was already decided",
})
}
}
impl Error for DecisionError {}
const PENDING: u8 = 0;
const ACCEPTED: u8 = 1;
const REJECTED: u8 = 2;
const CANCELED: u8 = 3;
struct Decision {
value: AtomicU8,
changed: Notify,
cancel: Token,
nonfatal: Arc<NonfatalCause>,
#[cfg(test)]
after_pending_check: SyncMutex<Option<WaitBarriers>>,
}
#[cfg(test)]
struct WaitBarriers {
checked: Arc<std::sync::Barrier>,
resume: Arc<std::sync::Barrier>,
}
impl Decision {
fn decide(&self, value: u8) -> Result<(), DecisionError> {
self.value
.compare_exchange(PENDING, value, Ordering::AcqRel, Ordering::Acquire)
.map(|_| self.changed.notify_waiters())
.map_err(|_| DecisionError::AlreadyDecided)
}
fn decide_consumer(&self, value: u8) -> Result<(), DecisionError> {
if self.cancel.is_cancelled() {
let _already_decided = self.decide(self.nonfatal.interrupted_decision());
Err(DecisionError::AlreadyDecided)
} else {
self.decide(value)
}
}
fn abandon(&self) -> Result<(), DecisionError> {
let value = if self.cancel.is_cancelled() {
self.nonfatal.interrupted_decision()
} else {
REJECTED
};
self.decide(value)
}
async fn wait(&self) -> StrongDecision {
loop {
let changed = self.changed.notified();
tokio::pin!(changed);
let _already_ready = changed.as_mut().enable();
match self.value.load(Ordering::Acquire) {
ACCEPTED => return StrongDecision::Accepted,
REJECTED => return StrongDecision::Rejected,
CANCELED => return StrongDecision::Cancelled,
_ => {
#[cfg(test)]
self.pause_after_pending_check();
tokio::select! {
biased;
() = self.cancel.cancelled() => {
let _already_decided =
self.decide(self.nonfatal.interrupted_decision());
}
() = &mut changed => {}
}
}
}
}
}
#[cfg(test)]
fn pause_after_pending_check(&self) {
let barriers = self
.after_pending_check
.lock()
.expect("event wait barrier lock poisoned")
.take();
if let Some(barriers) = barriers {
barriers.checked.wait();
barriers.resume.wait();
}
}
}
pub struct Delivery {
event: Event,
decision_point: Option<DecisionPoint>,
decision: Option<Arc<Decision>>,
}
impl fmt::Debug for Delivery {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Delivery")
.field("event", &self.event)
.field("decision_point", &self.decision_point)
.field("decision", &redact::Presence(self.decision.is_some()))
.finish()
}
}
impl Delivery {
#[must_use]
pub const fn event(&self) -> &Event {
&self.event
}
#[must_use]
pub const fn decision_point(&self) -> Option<DecisionPoint> {
self.decision_point
}
pub fn accept(&self) -> Result<(), DecisionError> {
self.decision
.as_ref()
.ok_or(DecisionError::NotRequired)?
.decide_consumer(ACCEPTED)
}
pub fn reject(&self) -> Result<(), DecisionError> {
self.decision
.as_ref()
.ok_or(DecisionError::NotRequired)?
.decide_consumer(REJECTED)
}
}
impl Drop for Delivery {
fn drop(&mut self) {
if let Some(decision) = &self.decision {
let _already_decided = decision.abandon();
}
}
}
pub struct Stream {
receiver: mpsc::UnboundedReceiver<Delivery>,
control: Arc<Control>,
}
impl fmt::Debug for Stream {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Stream")
.field("fatal", &self.control.fatal.load(Ordering::Relaxed))
.finish()
}
}
impl Stream {
pub async fn recv(&mut self) -> Option<Delivery> {
self.receiver.recv().await
}
}
impl futures_core::Stream for Stream {
type Item = Delivery;
fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
self.receiver.poll_recv(context)
}
}
impl Drop for Stream {
fn drop(&mut self) {
self.control.request_stop();
self.receiver.close();
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum DeliveryOutcome {
Delivered,
Accepted,
Rejected,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum StrongDecision {
Accepted,
Rejected,
Cancelled,
}
impl From<StrongDecision> for DeliveryOutcome {
fn from(decision: StrongDecision) -> Self {
match decision {
StrongDecision::Accepted => Self::Accepted,
StrongDecision::Rejected | StrongDecision::Cancelled => Self::Rejected,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct DeliveryResolution {
outward: DeliveryOutcome,
strong: Option<StrongDecision>,
}
impl DeliveryResolution {
const fn ordinary(outward: DeliveryOutcome) -> Self {
Self {
outward,
strong: None,
}
}
fn strong(decision: StrongDecision) -> Self {
Self {
outward: decision.into(),
strong: Some(decision),
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum TerminalIntent {
Running,
Stopped,
Cancelled,
Failed,
}
impl TerminalIntent {
#[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
pub(crate) const fn outcome(self) -> Option<Outcome> {
match self {
Self::Running => None,
Self::Stopped => Some(Outcome::Stopped),
Self::Cancelled => Some(Outcome::Cancelled),
Self::Failed => Some(Outcome::Failed),
}
}
}
const NONFATAL_NONE: u8 = 0;
const NONFATAL_STOPPED: u8 = 1;
const NONFATAL_CANCELED: u8 = 2;
struct NonfatalCause {
parent: Token,
cause: SyncMutex<u8>,
}
impl NonfatalCause {
fn freeze(&self, normal_stop: bool) -> u8 {
let mut cause = self
.cause
.lock()
.expect("event nonfatal cause lock poisoned");
if *cause == NONFATAL_NONE {
if self.parent.is_cancelled() {
*cause = NONFATAL_CANCELED;
} else if normal_stop {
*cause = NONFATAL_STOPPED;
}
}
*cause
}
#[cfg(test)]
fn frozen(&self) -> u8 {
*self
.cause
.lock()
.expect("event nonfatal cause lock poisoned")
}
fn interrupted_decision(&self) -> u8 {
if self.freeze(false) == NONFATAL_CANCELED {
CANCELED
} else {
REJECTED
}
}
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum FreezePoint {
Stop,
Fatal,
}
#[cfg(test)]
struct TestFreezePause {
point: FreezePoint,
reached: Arc<std::sync::Barrier>,
resume: Arc<std::sync::Barrier>,
}
#[cfg(test)]
struct TestFinalConfirmPause {
reached: Semaphore,
resume: Semaphore,
}
#[cfg(test)]
struct TestEmitPause {
reached: std::sync::mpsc::Sender<()>,
resume: Semaphore,
}
struct Control {
nonfatal: Arc<NonfatalCause>,
fatal: AtomicBool,
fatal_event: SyncMutex<Option<ValidationError>>,
stop_emitted: AtomicBool,
pending: SyncMutex<Option<Arc<Decision>>>,
cancel: Token,
interruption: Token,
#[cfg(test)]
before_reject_pause: SyncMutex<Option<TestFreezePause>>,
#[cfg(test)]
after_final_confirm_pause: SyncMutex<Option<Arc<TestFinalConfirmPause>>>,
}
struct PendingDecision<'a> {
control: &'a Control,
decision: Arc<Decision>,
}
impl Drop for PendingDecision<'_> {
fn drop(&mut self) {
let _already_decided = self.decision.abandon();
self.control.clear(&self.decision);
}
}
impl Control {
fn intent(&self) -> TerminalIntent {
if self.fatal.load(Ordering::Acquire) {
return TerminalIntent::Failed;
}
match self.nonfatal.freeze(false) {
NONFATAL_CANCELED => TerminalIntent::Cancelled,
NONFATAL_STOPPED => TerminalIntent::Stopped,
_ => TerminalIntent::Running,
}
}
fn strong_interruption(&self) -> Option<StrongDecision> {
if self.fatal.load(Ordering::Acquire) {
return Some(StrongDecision::Rejected);
}
match self.nonfatal.freeze(false) {
NONFATAL_CANCELED => Some(StrongDecision::Cancelled),
NONFATAL_STOPPED => Some(StrongDecision::Rejected),
_ => None,
}
}
fn final_confirm_strong(&self, decision: StrongDecision) -> StrongDecision {
if decision == StrongDecision::Accepted {
self.strong_interruption().unwrap_or(decision)
} else {
decision
}
}
#[cfg(test)]
fn pause_before_reject(&self, point: FreezePoint) {
let pause = {
let mut slot = self
.before_reject_pause
.lock()
.expect("event freeze pause lock poisoned");
if slot.as_ref().is_some_and(|pause| pause.point == point) {
slot.take()
} else {
None
}
};
if let Some(pause) = pause {
pause.reached.wait();
pause.resume.wait();
}
}
#[cfg(test)]
async fn pause_after_final_confirm(&self) {
let pause = self
.after_final_confirm_pause
.lock()
.expect("event final-confirm pause lock poisoned")
.take();
if let Some(pause) = pause {
pause.reached.add_permits(1);
pause
.resume
.acquire()
.await
.expect("event final-confirm pause remains open")
.forget();
}
}
fn interrupted(&self) -> bool {
self.fatal.load(Ordering::Acquire) || self.nonfatal.freeze(false) != NONFATAL_NONE
}
fn register(&self, decision: &Arc<Decision>) {
let mut pending = self.pending.lock().expect("event pending lock poisoned");
if self.interrupted() {
let _already_decided = decision.decide(self.nonfatal.interrupted_decision());
} else {
*pending = Some(decision.clone());
}
}
fn clear(&self, decision: &Arc<Decision>) {
let mut pending = self.pending.lock().expect("event pending lock poisoned");
if pending
.as_ref()
.is_some_and(|current| Arc::ptr_eq(current, decision))
{
pending.take();
}
}
fn reject_pending(&self) {
let decided = self.nonfatal.interrupted_decision();
if let Some(decision) = self
.pending
.lock()
.expect("event pending lock poisoned")
.take()
{
let _already_decided = decision.decide(decided);
}
}
fn latch_stop(&self) {
let _cause = self.nonfatal.freeze(true);
#[cfg(test)]
self.pause_before_reject(FreezePoint::Stop);
self.reject_pending();
self.interruption.cancel();
}
fn request_stop(&self) {
self.latch_stop();
self.cancel.cancel();
}
fn fail(&self, event_error: Option<ValidationError>) -> Option<ValidationError> {
let first_event_error = {
let mut fatal_event = self
.fatal_event
.lock()
.expect("event fatal latch lock poisoned");
if !self.fatal.load(Ordering::Acquire) {
*fatal_event = event_error;
self.fatal.store(true, Ordering::Release);
}
*fatal_event
};
#[cfg(test)]
self.pause_before_reject(FreezePoint::Fatal);
self.reject_pending();
self.interruption.cancel();
self.cancel.cancel();
first_event_error
}
}
pub(crate) struct Producer {
sender: mpsc::UnboundedSender<Delivery>,
control: Arc<Control>,
serial: Mutex<()>,
}
impl Producer {
pub(crate) async fn emit_text(
&self,
kind: Kind,
text: String,
coord: Coord,
item_id: Option<String>,
) -> Result<DeliveryOutcome, ValidationError> {
self.emit(Event::driver_text(kind, text, coord, item_id), None)
.await
}
pub(crate) async fn emit_lifecycle(
&self,
kind: Kind,
outcome: Option<Outcome>,
coord: Coord,
) -> Result<DeliveryOutcome, ValidationError> {
self.emit(Event::driver_lifecycle(kind, outcome, coord), None)
.await
}
pub(crate) async fn emit_input_admitted(
&self,
origin: InputOrigin,
items: Vec<item::Item>,
coord: Coord,
) -> Result<DeliveryOutcome, ValidationError> {
self.emit(Event::driver_input_admitted(origin, items, coord), None)
.await
}
pub(crate) async fn emit_input_rejected(
&self,
reason: String,
coord: Coord,
) -> Result<DeliveryOutcome, ValidationError> {
self.emit(Event::driver_input_rejected(reason, coord), None)
.await
}
pub(crate) async fn emit_tool_call(
&self,
call: ToolCall,
coord: Coord,
) -> Result<StrongDecision, ValidationError> {
self.emit_strong(
Event::driver_tool_call(call, coord),
DecisionPoint::ToolCall,
)
.await
}
pub(crate) async fn emit_tool_result(
&self,
result: item::ToolResult,
coord: Coord,
) -> Result<StrongDecision, ValidationError> {
self.emit_strong(
Event::driver_tool_result(result, coord),
DecisionPoint::ToolResult,
)
.await
}
pub(crate) async fn emit_extension(
&self,
mut event: Event,
coord: Coord,
) -> Result<DeliveryOutcome, ValidationError> {
event.coord = Some(coord);
self.emit(event, None).await
}
pub(crate) async fn emit_after_tool_commit(
&self,
mut event: Event,
coord: Coord,
) -> Result<StrongDecision, ValidationError> {
event.coord = Some(coord);
self.emit_strong(event, DecisionPoint::AfterToolCommit)
.await
}
pub(crate) async fn emit(
&self,
event: Event,
decision_point: Option<DecisionPoint>,
) -> Result<DeliveryOutcome, ValidationError> {
if let Some(decision_point) = decision_point {
return self
.emit_strong(event, decision_point)
.await
.map(Into::into);
}
let _serial = self.serial.lock().await;
if self.control.interrupted() {
return Ok(DeliveryOutcome::Rejected);
}
self.emit_locked(event, None)
.await
.map(|resolution| resolution.outward)
}
async fn emit_strong(
&self,
event: Event,
decision_point: DecisionPoint,
) -> Result<StrongDecision, ValidationError> {
let _serial = self.serial.lock().await;
if let Some(decision) = self.control.strong_interruption() {
return Ok(decision);
}
Ok(self
.emit_locked(event, Some(decision_point))
.await?
.strong
.expect("a strong decision point always has a decision"))
}
async fn emit_locked(
&self,
event: Event,
decision_point: Option<DecisionPoint>,
) -> Result<DeliveryResolution, ValidationError> {
if let Err(error) = event.validate(decision_point) {
let _first_event_error = self.control.fail(Some(error));
return Err(error);
}
let decision = decision_point.map(|_| {
Arc::new(Decision {
value: AtomicU8::new(PENDING),
changed: Notify::new(),
cancel: self.control.cancel.clone(),
nonfatal: Arc::clone(&self.control.nonfatal),
#[cfg(test)]
after_pending_check: SyncMutex::new(None),
})
});
let _pending = decision.as_ref().map(|decision| {
self.control.register(decision);
PendingDecision {
control: &self.control,
decision: Arc::clone(decision),
}
});
let delivery = Delivery {
event,
decision_point,
decision: decision.clone(),
};
let delivered = !self.control.cancel.is_cancelled() && self.sender.send(delivery).is_ok();
let outcome = if let Some(decision) = &decision {
if !delivered {
let _already_decided = decision.abandon();
}
let decision = self.control.final_confirm_strong(decision.wait().await);
#[cfg(test)]
self.control.pause_after_final_confirm().await;
DeliveryResolution::strong(decision)
} else {
DeliveryResolution::ordinary(if delivered {
DeliveryOutcome::Delivered
} else {
DeliveryOutcome::Rejected
})
};
Ok(outcome)
}
pub(crate) async fn emit_stop(
&self,
code: StopCode,
coord: Coord,
) -> Result<DeliveryOutcome, ValidationError> {
if self.control.stop_emitted.swap(true, Ordering::AcqRel) {
return Ok(DeliveryOutcome::Rejected);
}
self.control.latch_stop();
let _serial = self.serial.lock().await;
if self.control.cancel.is_cancelled() {
return Ok(DeliveryOutcome::Rejected);
}
self.emit_locked(Event::driver_stop(code, coord), None)
.await
.map(|resolution| resolution.outward)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ToolEmitError {
Closed,
Rejected,
Invalid(ValidationError),
}
impl fmt::Display for ToolEmitError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Closed => formatter.write_str("tool invocation emit window is closed"),
Self::Rejected => formatter.write_str("tool invocation event was not delivered"),
Self::Invalid(error) => write!(formatter, "invalid tool invocation event: {error}"),
}
}
}
impl Error for ToolEmitError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Invalid(error) => Some(error),
Self::Closed | Self::Rejected => None,
}
}
}
struct Outward {
producer: Arc<Producer>,
coord: Coord,
}
enum EmitTarget {
Closed,
Open(Outward),
}
struct EmitterState {
target: EmitTarget,
active: usize,
}
struct ToolEmitterInner {
state: SyncMutex<EmitterState>,
idle: Notify,
#[cfg(test)]
pause: SyncMutex<Option<Arc<TestEmitPause>>>,
}
impl ToolEmitterInner {
#[cfg(test)]
async fn pause(&self) {
let pause = self
.pause
.lock()
.expect("tool emitter pause lock poisoned")
.take();
if let Some(pause) = pause {
let _observer_may_be_gone = pause.reached.send(());
pause
.resume
.acquire()
.await
.expect("tool emitter pause remains open")
.forget();
}
}
fn enter(&self) -> Option<(ActiveEmit<'_>, Arc<Producer>, Coord)> {
let mut state = self.state.lock().expect("tool emitter lock poisoned");
match &state.target {
EmitTarget::Closed => None,
EmitTarget::Open(outward) => {
let producer = Arc::clone(&outward.producer);
let coord = outward.coord.clone();
state.active += 1;
Some((ActiveEmit { inner: self }, producer, coord))
}
}
}
fn leave(&self) {
let mut state = self.state.lock().expect("tool emitter lock poisoned");
state.active -= 1;
if state.active == 0 {
self.idle.notify_waiters();
}
}
fn close(&self) {
self.state
.lock()
.expect("tool emitter lock poisoned")
.target = EmitTarget::Closed;
}
async fn drain(&self) {
loop {
let idle = self.idle.notified();
tokio::pin!(idle);
let _already_ready = idle.as_mut().enable();
if self
.state
.lock()
.expect("tool emitter lock poisoned")
.active
== 0
{
return;
}
idle.await;
}
}
}
struct ActiveEmit<'a> {
inner: &'a ToolEmitterInner,
}
impl Drop for ActiveEmit<'_> {
fn drop(&mut self) {
self.inner.leave();
}
}
pub struct ToolEmitter {
inner: Arc<ToolEmitterInner>,
}
impl fmt::Debug for ToolEmitter {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.debug_struct("ToolEmitter").finish()
}
}
impl ToolEmitter {
#[must_use]
pub fn closed() -> Self {
Self {
inner: Arc::new(ToolEmitterInner {
state: SyncMutex::new(EmitterState {
target: EmitTarget::Closed,
active: 0,
}),
idle: Notify::new(),
#[cfg(test)]
pause: SyncMutex::new(None),
}),
}
}
pub async fn emit_audit(&self, audit: audit::Event) -> Result<(), ToolEmitError> {
let event = Event::from_audit(audit).map_err(ToolEmitError::Invalid)?;
self.emit_extension(event).await
}
pub async fn emit_error(
&self,
error: Arc<dyn Error + Send + Sync>,
) -> Result<(), ToolEmitError> {
self.emit_extension(Event::from_error(error)).await
}
async fn emit_extension(&self, event: Event) -> Result<(), ToolEmitError> {
let Some((_active, producer, coord)) = self.inner.enter() else {
return Err(ToolEmitError::Closed);
};
#[cfg(test)]
self.inner.pause().await;
let outcome = producer.emit_extension(event, coord).await;
if matches!(outcome, Ok(DeliveryOutcome::Delivered)) {
Ok(())
} else {
Err(ToolEmitError::Rejected)
}
}
}
pub(crate) struct ToolEmitterGate {
inner: Arc<ToolEmitterInner>,
}
impl ToolEmitterGate {
pub(crate) async fn close_and_wait(self) {
self.inner.close();
self.inner.drain().await;
}
}
pub(crate) fn tool_emitter(
producer: &Arc<Producer>,
coord: Coord,
) -> (ToolEmitter, ToolEmitterGate) {
let inner = Arc::new(ToolEmitterInner {
state: SyncMutex::new(EmitterState {
target: EmitTarget::Open(Outward {
producer: Arc::clone(producer),
coord,
}),
active: 0,
}),
idle: Notify::new(),
#[cfg(test)]
pause: SyncMutex::new(None),
});
(
ToolEmitter {
inner: Arc::clone(&inner),
},
ToolEmitterGate { inner },
)
}
pub(crate) struct EventSource {
stream: Option<Stream>,
control: Arc<Control>,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct StreamTakenError;
impl EventSource {
pub(crate) fn take_stream(&mut self) -> Result<Stream, StreamTakenError> {
self.stream.take().ok_or(StreamTakenError)
}
pub(crate) fn request_stop(&self) {
self.control.request_stop();
}
pub(crate) fn terminal_intent(&self) -> TerminalIntent {
self.control.intent()
}
pub(crate) async fn interruption(&self) {
self.control.interruption.cancelled().await;
}
pub(crate) fn latch_failure(&self) -> Option<ValidationError> {
self.control.fail(None)
}
#[cfg(test)]
fn state(&self) -> (bool, bool, bool) {
(
self.control.nonfatal.frozen() == NONFATAL_STOPPED,
self.control.fatal.load(Ordering::Acquire),
self.control.cancel.is_cancelled(),
)
}
}
pub(crate) fn channel(parent: &Token) -> (Arc<Producer>, EventSource) {
let (sender, receiver) = mpsc::unbounded_channel();
let nonfatal = Arc::new(NonfatalCause {
parent: parent.clone(),
cause: SyncMutex::new(NONFATAL_NONE),
});
let control = Arc::new(Control {
nonfatal,
fatal: AtomicBool::new(false),
fatal_event: SyncMutex::new(None),
stop_emitted: AtomicBool::new(false),
pending: SyncMutex::new(None),
cancel: parent.child_token(),
interruption: Token::new(),
#[cfg(test)]
before_reject_pause: SyncMutex::new(None),
#[cfg(test)]
after_final_confirm_pause: SyncMutex::new(None),
});
let producer = Arc::new(Producer {
sender,
control: control.clone(),
serial: Mutex::new(()),
});
let stream = Stream {
receiver,
control: control.clone(),
};
(
producer,
EventSource {
stream: Some(stream),
control,
},
)
}
#[cfg(test)]
pub(crate) mod testing {
use super::*;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum Emission {
Content,
Lifecycle,
ToolCall,
ToolResult,
Extension,
Stop,
Input,
}
pub(crate) const fn emission(kind: Kind) -> Emission {
match kind {
Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking => {
Emission::Content
}
Kind::TurnStart
| Kind::TurnEnd
| Kind::StepStart
| Kind::StepEnd
| Kind::GenerationEnd => Emission::Lifecycle,
Kind::ToolCall => Emission::ToolCall,
Kind::ToolResult => Emission::ToolResult,
Kind::Audit | Kind::Error => Emission::Extension,
Kind::Stop => Emission::Stop,
Kind::InputAdmitted | Kind::InputRejected => Emission::Input,
}
}
pub(crate) const ALL_KINDS: &[Kind] = &[
Kind::TextDelta,
Kind::Text,
Kind::ThinkingDelta,
Kind::Thinking,
Kind::TurnStart,
Kind::TurnEnd,
Kind::StepStart,
Kind::StepEnd,
Kind::GenerationEnd,
Kind::ToolCall,
Kind::ToolResult,
Kind::Error,
Kind::Audit,
Kind::Stop,
Kind::InputAdmitted,
Kind::InputRejected,
];
pub(crate) fn text(kind: Kind, text: &str, coord: Coord) -> Event {
Event::driver_text(kind, text.into(), coord, None)
}
pub(crate) fn lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Event {
Event::driver_lifecycle(kind, outcome, coord)
}
pub(crate) fn tool_call(call: ToolCall, coord: Coord) -> Event {
Event::driver_tool_call(call, coord)
}
pub(crate) fn tool_result(result: item::ToolResult, coord: Coord) -> Event {
Event::driver_tool_result(result, coord)
}
pub(crate) fn stop(code: StopCode, coord: Coord) -> Event {
Event::driver_stop(code, coord)
}
pub(crate) fn input_admitted(
origin: InputOrigin,
items: Vec<item::Item>,
coord: Coord,
) -> Event {
Event::driver_input_admitted(origin, items, coord)
}
pub(crate) fn input_rejected(reason: String, coord: Coord) -> Event {
Event::driver_input_rejected(reason, coord)
}
pub(crate) fn forged(kind: Kind, event: Event) -> Event {
Event { kind, ..event }
}
pub(crate) fn invalid_audit(coord: Coord) -> Event {
Event {
kind: Kind::Audit,
coord: Some(coord),
item_id: None,
payload: Payload::Audit(audit::Event::new(String::new(), None)),
}
}
pub(crate) fn invalid_stop(coord: Coord) -> Event {
Event {
kind: Kind::Stop,
coord: Some(coord),
item_id: None,
payload: Payload::Stop(StopCode(String::new())),
}
}
pub(crate) fn control(source: &EventSource) -> (bool, bool, bool) {
source.state()
}
pub(crate) use super::FreezePoint;
#[derive(Clone)]
pub(crate) struct InterruptionProbe(Arc<Control>);
impl InterruptionProbe {
pub(crate) fn request_stop(&self) {
self.0.request_stop();
}
pub(crate) fn fail(&self) {
let _first_event_error = self.0.fail(Some(ValidationError::PayloadMismatch));
}
}
pub(crate) fn interruption_probe(source: &EventSource) -> InterruptionProbe {
InterruptionProbe(Arc::clone(&source.control))
}
pub(crate) struct FreezePauseProbe {
reached: Arc<std::sync::Barrier>,
resume: Arc<std::sync::Barrier>,
}
impl FreezePauseProbe {
pub(crate) fn wait_until_frozen(&self) {
self.reached.wait();
}
pub(crate) fn resume_rejection(&self) {
self.resume.wait();
}
}
pub(crate) fn pause_before_reject(
source: &EventSource,
point: FreezePoint,
) -> (InterruptionProbe, FreezePauseProbe) {
let reached = Arc::new(std::sync::Barrier::new(2));
let resume = Arc::new(std::sync::Barrier::new(2));
*source
.control
.before_reject_pause
.lock()
.expect("event freeze pause lock poisoned") = Some(TestFreezePause {
point,
reached: Arc::clone(&reached),
resume: Arc::clone(&resume),
});
(
interruption_probe(source),
FreezePauseProbe { reached, resume },
)
}
pub(crate) struct FinalConfirmPauseProbe(Arc<TestFinalConfirmPause>);
impl FinalConfirmPauseProbe {
pub(crate) async fn wait_until_confirmed(&self) {
self.0
.reached
.acquire()
.await
.expect("event final-confirm pause remains open")
.forget();
}
pub(crate) fn resume_return(&self) {
self.0.resume.add_permits(1);
}
}
pub(crate) fn pause_after_final_confirm(source: &EventSource) -> FinalConfirmPauseProbe {
let pause = Arc::new(TestFinalConfirmPause {
reached: Semaphore::new(0),
resume: Semaphore::new(0),
});
*source
.control
.after_final_confirm_pause
.lock()
.expect("event final-confirm pause lock poisoned") = Some(Arc::clone(&pause));
FinalConfirmPauseProbe(pause)
}
pub(crate) fn intent(source: &EventSource) -> TerminalIntent {
source.terminal_intent()
}
pub(crate) fn has_pending_strong_decision(source: &EventSource) -> bool {
source
.control
.pending
.lock()
.expect("event pending lock poisoned")
.is_some()
}
pub(crate) fn stale_pending_guard_preserves_successor(source: &EventSource) -> (bool, bool) {
let decision = || {
Arc::new(Decision {
value: AtomicU8::new(PENDING),
changed: Notify::new(),
cancel: source.control.cancel.clone(),
nonfatal: Arc::clone(&source.control.nonfatal),
after_pending_check: SyncMutex::new(None),
})
};
let stale = decision();
source.control.register(&stale);
let stale_guard = PendingDecision {
control: &source.control,
decision: Arc::clone(&stale),
};
let successor = decision();
source.control.register(&successor);
drop(stale_guard);
let successor_preserved = source
.control
.pending
.lock()
.expect("event pending lock poisoned")
.as_ref()
.is_some_and(|pending| Arc::ptr_eq(pending, &successor));
let stale_abandoned = stale.decide(ACCEPTED) == Err(DecisionError::AlreadyDecided);
source.control.reject_pending();
(successor_preserved, stale_abandoned)
}
#[derive(Clone)]
pub(crate) struct EmitterProbe(Arc<ToolEmitterInner>);
impl EmitterProbe {
pub(crate) fn state(&self) -> (bool, usize) {
let state = self.0.state.lock().expect("tool emitter lock poisoned");
(matches!(state.target, EmitTarget::Closed), state.active)
}
}
pub(crate) fn emitter_probe(emitter: &ToolEmitter) -> EmitterProbe {
EmitterProbe(Arc::clone(&emitter.inner))
}
#[derive(Clone)]
pub(crate) struct EmitPauseProbe(Arc<TestEmitPause>);
impl EmitPauseProbe {
pub(crate) fn new(reached: std::sync::mpsc::Sender<()>) -> Self {
Self(Arc::new(TestEmitPause {
reached,
resume: Semaphore::new(0),
}))
}
pub(crate) fn arm(&self, emitter: &ToolEmitter) {
*emitter
.inner
.pause
.lock()
.expect("tool emitter pause lock poisoned") = Some(Arc::clone(&self.0));
}
pub(crate) fn resume(&self) {
self.0.resume.add_permits(1);
}
}
pub(crate) fn cancel_lane(source: &EventSource) {
source.control.cancel.cancel();
}
pub(crate) fn fail(source: &EventSource) {
let _first_event_error = source.control.fail(Some(ValidationError::PayloadMismatch));
}
#[derive(Clone)]
pub(crate) struct DecisionProbe(Arc<Decision>);
impl DecisionProbe {
pub(crate) fn plain(cancel: Token) -> Self {
let nonfatal = Arc::new(NonfatalCause {
parent: cancel.clone(),
cause: SyncMutex::new(NONFATAL_NONE),
});
Self(Arc::new(Decision {
value: AtomicU8::new(PENDING),
changed: Notify::new(),
cancel,
nonfatal,
after_pending_check: SyncMutex::new(None),
}))
}
pub(crate) fn paused_after_pending_check(
cancel: Token,
) -> (Self, Arc<std::sync::Barrier>, Arc<std::sync::Barrier>) {
let checked = Arc::new(std::sync::Barrier::new(2));
let resume = Arc::new(std::sync::Barrier::new(2));
let nonfatal = Arc::new(NonfatalCause {
parent: cancel.clone(),
cause: SyncMutex::new(NONFATAL_NONE),
});
let decision = Arc::new(Decision {
value: AtomicU8::new(PENDING),
changed: Notify::new(),
cancel,
nonfatal,
after_pending_check: SyncMutex::new(Some(WaitBarriers {
checked: checked.clone(),
resume: resume.clone(),
})),
});
(Self(decision), checked, resume)
}
pub(crate) fn accept(&self) -> Result<(), DecisionError> {
self.0.decide_consumer(ACCEPTED)
}
pub(crate) fn reject(&self) -> Result<(), DecisionError> {
self.0.decide_consumer(REJECTED)
}
pub(crate) async fn wait(&self) -> StrongDecision {
self.0.wait().await
}
}
pub(crate) fn register_probe(source: &EventSource) -> bool {
let decision = DecisionProbe::plain(source.control.cancel.clone()).0;
source.control.register(&decision);
decision.value.load(Ordering::Acquire) == REJECTED
}
pub(crate) fn tool_emitter_active(emitter: &ToolEmitter) -> usize {
emitter
.inner
.state
.lock()
.expect("tool emitter lock poisoned")
.active
}
}
#[cfg(feature = "serde")]
mod serde_impl {
use std::fmt::{self, Formatter};
use serde_core::de::{
Deserialize, Deserializer, EnumAccess, Error as DeError, VariantAccess, Visitor,
};
use serde_core::ser::{Serialize, Serializer};
use super::Kind;
use crate::wire::IdentifierSeed;
const NAME: &str = "Kind";
const VARIANTS: &[&str] = &[
"text_delta",
"text",
"thinking_delta",
"thinking",
"turn_start",
"turn_end",
"step_start",
"step_end",
"generation_end",
"tool_call",
"tool_result",
"error",
"audit",
"stop",
"input_admitted",
"input_rejected",
];
impl Serialize for Kind {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let (index, tag) = match self {
Self::TextDelta => (0, "text_delta"),
Self::Text => (1, "text"),
Self::ThinkingDelta => (2, "thinking_delta"),
Self::Thinking => (3, "thinking"),
Self::TurnStart => (4, "turn_start"),
Self::TurnEnd => (5, "turn_end"),
Self::StepStart => (6, "step_start"),
Self::StepEnd => (7, "step_end"),
Self::GenerationEnd => (8, "generation_end"),
Self::ToolCall => (9, "tool_call"),
Self::ToolResult => (10, "tool_result"),
Self::Error => (11, "error"),
Self::Audit => (12, "audit"),
Self::Stop => (13, "stop"),
Self::InputAdmitted => (14, "input_admitted"),
Self::InputRejected => (15, "input_rejected"),
};
serializer.serialize_unit_variant(NAME, index, tag)
}
}
impl<'de> Deserialize<'de> for Kind {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
deserializer.deserialize_enum(NAME, VARIANTS, KindVisitor)
}
}
struct KindVisitor;
impl<'de> Visitor<'de> for KindVisitor {
type Value = Kind;
fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str("an outward event kind")
}
fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
where
A: EnumAccess<'de>,
{
let (tag, variant) = data.variant_seed(IdentifierSeed(VARIANTS))?;
variant.unit_variant()?;
match tag.0.as_str() {
"text_delta" => Ok(Kind::TextDelta),
"text" => Ok(Kind::Text),
"thinking_delta" => Ok(Kind::ThinkingDelta),
"thinking" => Ok(Kind::Thinking),
"turn_start" => Ok(Kind::TurnStart),
"turn_end" => Ok(Kind::TurnEnd),
"step_start" => Ok(Kind::StepStart),
"step_end" => Ok(Kind::StepEnd),
"generation_end" => Ok(Kind::GenerationEnd),
"tool_call" => Ok(Kind::ToolCall),
"tool_result" => Ok(Kind::ToolResult),
"error" => Ok(Kind::Error),
"audit" => Ok(Kind::Audit),
"stop" => Ok(Kind::Stop),
"input_admitted" => Ok(Kind::InputAdmitted),
"input_rejected" => Ok(Kind::InputRejected),
unknown => Err(A::Error::unknown_variant(unknown, VARIANTS)),
}
}
}
}