use std::error::Error;
use std::fmt;
use std::future::Future;
use std::panic::{AssertUnwindSafe, catch_unwind, resume_unwind};
use std::pin::Pin;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll};
use tokio::sync::Notify;
use super::agent::start::AdmittedStart;
use super::agent::{AttachmentGuard, Revision};
use super::driver;
use super::event::{Event, EventSource, InputOrigin, Producer, StopCode, Stream, ValidationError};
use super::hook::{
self, BufferedFact, CallbackResources, FactBuffer, LifecycleEnd, LifecycleObservation,
TranscriptSource,
};
use super::model::Client;
use super::session::{Lease, Session};
use crate::audit;
use crate::state::run_state::{self};
use crate::state::session_state::{self};
use crate::transcript::controller::TranscriptController;
use crate::transcript::item::Item;
use crate::value::lifecycle::{Coord, Outcome};
pub struct Run<M: Client> {
inner: Arc<RunInner<M>>,
}
impl<M: Client> fmt::Debug for Run<M> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Run")
.field("session", &self.inner.session.id())
.field("revision", &self.inner.revision.id())
.field(
"handles",
&self.inner.public_handles.load(Ordering::Relaxed),
)
.finish()
}
}
impl<M: Client> Clone for Run<M> {
fn clone(&self) -> Self {
self.inner.public_handles.fetch_add(1, Ordering::Relaxed);
Self {
inner: Arc::clone(&self.inner),
}
}
}
impl<M: Client> Drop for Run<M> {
fn drop(&mut self) {
if self.inner.public_handles.fetch_sub(1, Ordering::AcqRel) == 1 {
self.inner.source.request_stop();
}
}
}
struct RunInner<M: Client> {
revision: Revision<M>,
session: Session,
source: Arc<EventSource>,
events: Mutex<Option<Stream>>,
terminal: Mutex<Option<Arc<Terminal>>>,
done: Notify,
public_handles: AtomicUsize,
task: Mutex<Option<tokio::task::JoinHandle<()>>>,
}
struct TaskExitState {
entered_task_body: AtomicBool,
task_panicked: AtomicBool,
fallback_armed: AtomicBool,
}
struct TaskFallback<M: Client> {
inner: Arc<RunInner<M>>,
identity: Coord,
state: Arc<TaskExitState>,
}
impl<M: Client> Drop for TaskFallback<M> {
fn drop(&mut self) {
if !self.state.fallback_armed.swap(false, Ordering::AcqRel) {
return;
}
let failure: Arc<dyn Error + Send + Sync> =
if !self.state.entered_task_body.load(Ordering::Acquire) {
Arc::new(TaskNotStartedError)
} else if self.state.task_panicked.load(Ordering::Acquire) {
Arc::new(TaskPanickedError)
} else {
Arc::new(TaskAbortedError)
};
self.inner.publish(Arc::new(Terminal::failed(
self.identity.clone(),
FailureKind::Internal,
failure,
)));
}
}
struct PanicMarkerFuture<F, M: Client> {
inner: Pin<Box<F>>,
fallback: TaskFallback<M>,
}
impl<F, M: Client> PanicMarkerFuture<F, M> {
fn new(inner: F, fallback: TaskFallback<M>) -> Self {
Self {
inner: Box::pin(inner),
fallback,
}
}
}
impl<F: Future, M: Client> Future for PanicMarkerFuture<F, M> {
type Output = F::Output;
fn poll(self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
let this = self.get_mut();
match catch_unwind(AssertUnwindSafe(|| this.inner.as_mut().poll(context))) {
Ok(poll) => poll,
Err(payload) => {
this.fallback
.state
.task_panicked
.store(true, Ordering::Release);
resume_unwind(payload);
}
}
}
}
struct TaskCleanup<M: Client> {
inner: Arc<RunInner<M>>,
lease: Option<Lease>,
attachment: Option<AttachmentGuard<M>>,
producer: Option<Arc<Producer>>,
state: Arc<TaskExitState>,
armed: bool,
}
impl<M: Client> TaskCleanup<M> {
const fn new(
inner: Arc<RunInner<M>>,
lease: Lease,
attachment: AttachmentGuard<M>,
producer: Arc<Producer>,
state: Arc<TaskExitState>,
) -> Self {
Self {
inner,
lease: Some(lease),
attachment: Some(attachment),
producer: Some(producer),
state,
armed: true,
}
}
fn enter_task_body(&mut self) {
self.state.entered_task_body.store(true, Ordering::Release);
}
const fn lease(&self) -> &Lease {
self.lease
.as_ref()
.expect("the Run Lease remains owned until terminal cleanup")
}
const fn producer(&self) -> &Arc<Producer> {
self.producer
.as_ref()
.expect("the event Producer remains open through RunEnd")
}
fn cleanup(&mut self) {
self.inner.source.request_stop();
drop(self.lease.take());
drop(self.attachment.take());
drop(self.producer.take());
self.inner.close_events();
}
fn complete(mut self, terminal: Terminal) {
self.cleanup();
self.armed = false;
self.state.fallback_armed.store(false, Ordering::Release);
self.inner.publish(Arc::new(terminal));
}
}
impl<M: Client> Drop for TaskCleanup<M> {
fn drop(&mut self) {
if !self.armed {
return;
}
self.cleanup();
self.armed = false;
}
}
impl<M: Client + 'static> Run<M> {
pub(crate) fn spawn(admitted: AdmittedStart<M>) -> Self {
Self::spawn_inner(admitted, |events| (Some(events), ())).0
}
pub(crate) fn spawn_observed(admitted: AdmittedStart<M>) -> (Self, Stream) {
Self::spawn_inner(admitted, |events| (None, events))
}
fn spawn_inner<R>(
admitted: AdmittedStart<M>,
place_stream: impl FnOnce(Stream) -> (Option<Stream>, R),
) -> (Self, R) {
let AdmittedStart {
lease,
attachment,
revision,
session,
input,
admitted_items,
plan,
identity,
cancellation,
producer,
mut source,
hooks,
reservation_resources,
run_states,
session_state,
fact_buffer,
} = admitted;
let events = source
.take_stream()
.expect("a freshly admitted Run owns its event stream");
let (run_events, returned) = place_stream(events);
let source = Arc::new(source);
let inner = Arc::new(RunInner {
revision: revision.clone(),
session: session.clone(),
source: Arc::clone(&source),
events: Mutex::new(run_events),
terminal: Mutex::new(None),
done: Notify::new(),
public_handles: AtomicUsize::new(1),
task: Mutex::new(None),
});
let task_state = Arc::new(TaskExitState {
entered_task_body: AtomicBool::new(false),
task_panicked: AtomicBool::new(false),
fallback_armed: AtomicBool::new(true),
});
let fallback = TaskFallback {
inner: Arc::clone(&inner),
identity: identity.clone(),
state: Arc::clone(&task_state),
};
let mut cleanup =
TaskCleanup::new(Arc::clone(&inner), lease, attachment, producer, task_state);
let task_body = async move {
cleanup.enter_task_body();
let lifecycle = LifecycleFanout {
hooks: &hooks,
run_states: &run_states,
identity: &identity,
session_state: &session_state,
session_state_writer: cleanup.lease().state(),
transcript: cleanup.lease().transcript_reader(),
emitter: &fact_buffer,
};
lifecycle.observe(&LifecycleObservation::RunStart {
coord: identity.clone(),
input,
});
let report = driver::Report::default();
let admission_failure = publish_admission(
cleanup.producer(),
&fact_buffer,
&lifecycle,
&admitted_items,
)
.await
.err();
let driver_terminal = if let Some(error) = admission_failure {
driver::Terminal::Failed(driver::Error::Event(error))
} else {
let callback_resources = run_states
.iter()
.map(|run_state| {
CallbackResources::new(
&identity,
run_state,
&session_state,
Some(cleanup.lease().state()),
&fact_buffer,
)
})
.collect::<Vec<_>>();
let controller = TranscriptController::new(
cleanup.lease(),
&hooks,
&reservation_resources,
&identity,
&fact_buffer,
);
let tool_phase = driver::ToolPhase::new(
driver::Outward::new(cleanup.producer(), &fact_buffer),
&hooks,
&callback_resources,
&controller,
&identity,
Some(session.id().to_owned()),
);
let inbox = session.input_mailbox();
let engine = driver::Driver::new(
revision.model().as_ref(),
cleanup.lease(),
&inbox,
revision.tools(),
&cancellation,
)
.with_tool_phase(tool_phase)
.with_turn_trigger(admitted_items)
.with_report(&report);
engine.run(plan, &source).await
};
let stop_code = report.stop_code();
let candidate =
terminal_from_driver(&driver_terminal, identity.clone(), stop_code.clone());
let observation = LifecycleObservation::RunEnd {
coord: identity.clone(),
end: lifecycle_end(&candidate),
turns: report.turns(),
};
lifecycle.observe(&observation);
let run_end_failure =
publish_buffered_facts(cleanup.producer(), &fact_buffer, Some(&lifecycle))
.await
.err();
let mut terminal = driver::TerminalLatch::default();
terminal.record(driver_terminal);
if let Some(error) = run_end_failure {
terminal.record(driver::Terminal::Failed(driver::Error::Event(error)));
}
let terminal = terminal_from_driver(&terminal.finish(&source), identity, stop_code);
cleanup.complete(terminal);
};
let task = tokio::spawn(PanicMarkerFuture::new(task_body, fallback));
*inner.task.lock().expect("Run task lock poisoned") = Some(task);
(Self { inner }, returned)
}
}
impl<M: Client> Run<M> {
#[must_use]
pub fn revision(&self) -> Revision<M> {
self.inner.revision.clone()
}
#[must_use]
pub fn session(&self) -> Session {
self.inner.session.clone()
}
pub fn take_events(&self) -> Result<Stream, EventsTakenError> {
self.inner
.events
.lock()
.expect("Run event lock poisoned")
.take()
.ok_or(EventsTakenError)
}
pub fn request_stop(&self) {
self.inner.source.request_stop();
}
pub async fn stop(&self) -> Arc<Terminal> {
self.request_stop();
self.wait().await
}
pub async fn wait(&self) -> Arc<Terminal> {
loop {
let notified = self.inner.done.notified();
tokio::pin!(notified);
notified.as_mut().enable();
if let Some(terminal) = self.inner.terminal() {
return terminal;
}
notified.await;
}
}
pub async fn close(&self) -> Arc<Terminal> {
self.inner.close_events();
self.stop().await
}
#[cfg(test)]
pub(super) fn terminal_ready(&self) -> bool {
self.inner.terminal().is_some()
}
#[cfg(test)]
pub(super) async fn join_tracked_task(&self) -> Result<(), tokio::task::JoinError> {
let task = self
.inner
.task
.lock()
.expect("Run task lock poisoned")
.take()
.expect("the sole tracked Run task is joined at most once");
task.await
}
}
impl<M: Client> RunInner<M> {
fn close_events(&self) {
drop(self.events.lock().expect("Run event lock poisoned").take());
}
fn terminal(&self) -> Option<Arc<Terminal>> {
self.terminal
.lock()
.expect("Run terminal lock poisoned")
.clone()
}
fn publish(&self, terminal: Arc<Terminal>) {
let mut slot = self.terminal.lock().expect("Run terminal lock poisoned");
debug_assert!(slot.is_none(), "the sole Run task publishes once");
*slot = Some(terminal);
drop(slot);
self.done.notify_waiters();
}
}
pub(super) struct LifecycleFanout<'a> {
hooks: &'a hook::RuntimeRegistry,
run_states: &'a [run_state::Store],
identity: &'a Coord,
session_state: &'a session_state::Reader,
session_state_writer: &'a session_state::Writer,
transcript: crate::transcript::store::SnapshotReader,
emitter: &'a FactBuffer,
}
impl LifecycleFanout<'_> {
fn observe_audit(&self, event: &audit::Event) {
for adapter in self.hooks.observer_hooks() {
let run_state = self
.run_states
.get(adapter.index())
.expect("Run resources cover every hook registration");
let resources = CallbackResources::new(
self.identity,
run_state,
self.session_state,
Some(self.session_state_writer),
self.emitter,
);
adapter.invoke_audit_event(resources, &self.transcript, event);
}
}
fn observe(&self, observation: &LifecycleObservation) {
for adapter in self.hooks.observer_hooks() {
let run_state = self
.run_states
.get(adapter.index())
.expect("Run resources cover every hook registration");
let resources = CallbackResources::new(
self.identity,
run_state,
self.session_state,
Some(self.session_state_writer),
self.emitter,
);
adapter.invoke_lifecycle(
resources,
TranscriptSource::Reader(&self.transcript),
None,
observation,
);
}
}
}
async fn publish_admission(
producer: &Producer,
buffer: &FactBuffer,
lifecycle: &LifecycleFanout<'_>,
admitted: &[Item],
) -> Result<(), ValidationError> {
publish_buffered_facts(producer, buffer, Some(lifecycle)).await?;
if admitted.is_empty() {
return Ok(());
}
producer
.emit_input_admitted(
InputOrigin::Start,
admitted.to_vec(),
lifecycle.identity.clone(),
)
.await?;
Ok(())
}
pub(super) async fn publish_buffered_facts(
producer: &Producer,
buffer: &FactBuffer,
observers: Option<&LifecycleFanout<'_>>,
) -> Result<(), ValidationError> {
for fact in buffer.take_facts() {
let event = match fact {
BufferedFact::Audit(audit) => {
if let Some(observers) = observers {
observers.observe_audit(&audit);
}
Event::from_audit(audit)?
}
BufferedFact::Error(error) => Event::from_error(error),
};
producer
.emit(event, None)
.await
.expect("a successfully constructed ordinary fact remains valid");
}
Ok(())
}
fn terminal_from_driver(
terminal: &driver::Terminal,
coord: Coord,
stop_code: Option<StopCode>,
) -> Terminal {
match terminal {
driver::Terminal::Completed => Terminal::new(Outcome::Completed, coord, None),
driver::Terminal::Stopped => Terminal::new(Outcome::Stopped, coord, stop_code),
driver::Terminal::Cancelled => Terminal::new(Outcome::Cancelled, coord, None),
driver::Terminal::Failed(error) => {
let failure = DriverError::from_loop(error);
Terminal::failed(coord, failure.kind, Arc::new(failure))
}
}
}
fn lifecycle_end(terminal: &Terminal) -> LifecycleEnd {
match terminal.outcome {
Outcome::Completed => LifecycleEnd::Completed,
Outcome::Stopped => LifecycleEnd::Stopped {
code: terminal.stop_code.clone(),
},
Outcome::Cancelled => LifecycleEnd::Cancelled {
error: Arc::new(CanceledError),
},
Outcome::Failed => LifecycleEnd::Failed {
error: terminal
.failure
.as_ref()
.expect("a failed terminal always retains failure detail")
.clone(),
},
}
}
pub struct Terminal {
outcome: Outcome,
coord: Coord,
stop_code: Option<StopCode>,
failure: Option<Arc<dyn Error + Send + Sync>>,
failure_kind: Option<FailureKind>,
}
impl fmt::Debug for Terminal {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Terminal")
.field("outcome", &self.outcome)
.field("coord", &self.coord)
.field("stop_code", &self.stop_code)
.field(
"failure",
&self.failure.as_ref().map(|failure| failure.to_string()),
)
.field("failure_kind", &self.failure_kind)
.finish()
}
}
impl Terminal {
fn new(outcome: Outcome, coord: Coord, stop_code: Option<StopCode>) -> Self {
Self {
outcome,
coord,
stop_code,
failure: None,
failure_kind: None,
}
}
fn failed(coord: Coord, kind: FailureKind, failure: Arc<dyn Error + Send + Sync>) -> Self {
Self {
outcome: Outcome::Failed,
coord,
stop_code: None,
failure: Some(failure),
failure_kind: Some(kind),
}
}
#[must_use]
pub const fn outcome(&self) -> Outcome {
self.outcome
}
#[must_use]
pub const fn coord(&self) -> &Coord {
&self.coord
}
#[must_use]
pub const fn stop_code(&self) -> Option<&StopCode> {
self.stop_code.as_ref()
}
#[must_use]
pub fn failure(&self) -> Option<&(dyn Error + Send + Sync + 'static)> {
self.failure.as_deref()
}
#[must_use]
pub const fn failure_kind(&self) -> Option<FailureKind> {
self.failure_kind
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct EventsTakenError;
impl fmt::Display for EventsTakenError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Run events were already consumed")
}
}
impl Error for EventsTakenError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TaskAbortedError;
impl fmt::Display for TaskAbortedError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Run task was aborted after it started")
}
}
impl Error for TaskAbortedError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TaskNotStartedError;
impl fmt::Display for TaskNotStartedError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Run task was dropped before it started")
}
}
impl Error for TaskNotStartedError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TaskPanickedError;
impl fmt::Display for TaskPanickedError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Run task panicked")
}
}
impl Error for TaskPanickedError {}
#[derive(Debug)]
struct CanceledError;
impl fmt::Display for CanceledError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Run canceled")
}
}
impl Error for CanceledError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum FailureKind {
Transcript,
ToolResolution,
Request,
Model,
Stream,
Event,
Hook,
ToolExecution,
ToolCommit,
Input,
Internal,
}
#[derive(Debug)]
struct DriverError {
kind: FailureKind,
message: String,
cause: Option<Arc<dyn Error + Send + Sync>>,
}
impl DriverError {
fn from_loop(error: &driver::Error) -> Self {
Self {
kind: error.classify(),
message: error.to_string(),
cause: error.cause(),
}
}
}
impl fmt::Display for DriverError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.message)
}
}
impl Error for DriverError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
self.cause
.as_ref()
.map(|cause| cause.as_ref() as &(dyn Error + 'static))
}
}