use std::cell::RefCell;
use std::error::Error;
use std::fmt;
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::Arc;
use crate::cancel::Token;
use crate::audit;
use crate::redact::Presence;
use crate::runtime::event::StopCode;
use crate::runtime::model::{self, CompletionReason, Info, Request, RequestPlan};
use crate::runtime::session::InputTarget;
use crate::runtime::tool::{CallDisposition, StepToolSnapshot};
use crate::state::run_state::{self};
use crate::state::session_state::{self, CallbackWritePermit};
use crate::transcript::item::{Assistant, Item};
use crate::transcript::store::{
self, Appender, Replacer, Snapshot, SnapshotReader, Store, Version,
};
use crate::value::content::Part;
use crate::value::lifecycle::{Coord, Outcome};
use crate::value::tool_call::{ToolCall, ToolResult};
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub(crate) enum HookFamily {
Run,
Input,
TurnStep,
Model,
Tool,
Observer,
Transcript,
AgentTeardown,
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub(crate) enum ScopeKind {
Prepare,
Finalize,
Continue,
InputAdmit,
Turn,
BeforeStep,
AfterStep,
BeforeModel,
AfterModel,
ToolCall,
ToolResult,
AfterToolCommit,
Observer,
Read,
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub(crate) enum DecisionKind {
BeforeModel,
AfterModel,
ToolCall,
ToolResult,
InputAdmit,
Continue,
AfterStep,
Prepare,
Finalize,
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub(crate) struct HookSpec {
pub(crate) name: &'static str,
pub(crate) family: HookFamily,
pub(crate) scope: Option<ScopeKind>,
pub(crate) decision: Option<DecisionKind>,
}
#[cfg(test)]
pub(crate) const fn hook(
name: &'static str,
family: HookFamily,
scope: Option<ScopeKind>,
decision: Option<DecisionKind>,
) -> HookSpec {
HookSpec {
name,
family,
scope,
decision,
}
}
#[cfg(test)]
pub(crate) const HOOK_INVENTORY: &[HookSpec] = &[
hook(
"OnPrepareRun",
HookFamily::Run,
Some(ScopeKind::Prepare),
Some(DecisionKind::Prepare),
),
hook(
"OnFinalizeRun",
HookFamily::Run,
Some(ScopeKind::Finalize),
Some(DecisionKind::Finalize),
),
hook(
"OnRunAdmitted",
HookFamily::Observer,
Some(ScopeKind::Read),
None,
),
hook(
"OnBeforeToolCall",
HookFamily::Tool,
Some(ScopeKind::ToolCall),
Some(DecisionKind::ToolCall),
),
hook(
"OnBeforeToolResult",
HookFamily::Tool,
Some(ScopeKind::ToolResult),
Some(DecisionKind::ToolResult),
),
hook(
"OnAfterToolExecute",
HookFamily::Tool,
Some(ScopeKind::AfterToolCommit),
None,
),
hook(
"OnBeforeModel",
HookFamily::Model,
Some(ScopeKind::BeforeModel),
Some(DecisionKind::BeforeModel),
),
hook(
"OnAfterModel",
HookFamily::Model,
Some(ScopeKind::AfterModel),
Some(DecisionKind::AfterModel),
),
hook(
"OnBeforeInputAdmit",
HookFamily::Input,
Some(ScopeKind::InputAdmit),
Some(DecisionKind::InputAdmit),
),
hook(
"OnBeforeTurn",
HookFamily::TurnStep,
Some(ScopeKind::Turn),
None,
),
hook(
"OnAfterTurn",
HookFamily::TurnStep,
Some(ScopeKind::Turn),
None,
),
hook(
"OnBeforeStep",
HookFamily::TurnStep,
Some(ScopeKind::BeforeStep),
None,
),
hook(
"OnAfterStep",
HookFamily::TurnStep,
Some(ScopeKind::AfterStep),
Some(DecisionKind::AfterStep),
),
hook("OnClose", HookFamily::AgentTeardown, None, None),
hook(
"OnContinueRun",
HookFamily::Run,
Some(ScopeKind::Continue),
Some(DecisionKind::Continue),
),
hook(
"OnRunStart",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnRunEnd",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnTurnStart",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnTurnEnd",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnStepStart",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnStepEnd",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnGenerationStart",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnGenerationEnd",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnToolCallStart",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnToolCallEnd",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnModelEvent",
HookFamily::Observer,
Some(ScopeKind::Observer),
None,
),
hook(
"OnAuditEvent",
HookFamily::Observer,
Some(ScopeKind::Read),
None,
),
hook(
"OnTranscriptMutation",
HookFamily::Transcript,
Some(ScopeKind::Read),
None,
),
];
#[derive(Clone)]
#[expect(
clippy::module_name_repetitions,
reason = "HookError distinguishes callback failures from the hook module's other errors"
)]
pub struct HookError(Arc<dyn Error + Send + Sync>);
impl HookError {
#[must_use]
pub fn new(error: impl Error + Send + Sync + 'static) -> Self {
Self(Arc::new(error))
}
#[must_use]
pub fn source_ref(&self) -> &(dyn Error + Send + Sync + 'static) {
self.0.as_ref()
}
}
impl fmt::Debug for HookError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut tuple = formatter.debug_tuple("HookError");
let mut link: Option<&(dyn Error + 'static)> = Some(self.0.as_ref());
while let Some(error) = link {
tuple.field(&error.to_string());
link = error.source();
}
tuple.finish()
}
}
impl fmt::Display for HookError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(formatter)
}
}
impl Error for HookError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(self.0.as_ref())
}
}
#[expect(
clippy::module_name_repetitions,
reason = "HookResult names the shared callback result contract rather than a generic module result"
)]
pub type HookResult<T> = Result<T, HookError>;
#[derive(Clone, Copy, Debug)]
pub struct SessionIdentity<'a>(&'a Coord);
impl SessionIdentity<'_> {
#[must_use]
pub fn id(&self) -> &str {
self.0.session_id()
}
}
#[derive(Debug)]
pub struct StagedTranscript {
reader: SnapshotReader,
appender: Appender,
replacer: Replacer,
}
impl StagedTranscript {
pub(crate) fn from_store(store: &Store) -> Self {
Self {
reader: store.snapshot_reader(),
appender: store.appender(),
replacer: store.replacer(),
}
}
pub fn append_batch(&self, items: Vec<Item>) -> Result<Version, store::Error> {
self.appender.append_batch(items)
}
pub fn replace(&self, items: Vec<Item>) -> Result<Version, store::Error> {
self.replacer.replace(items)
}
}
pub(crate) trait Emitter: Send + Sync {
fn emit_audit(&self, event: audit::Event);
fn emit_error(&self, error: Arc<dyn Error + Send + Sync>);
}
#[derive(Debug)]
pub(crate) enum BufferedFact {
Audit(audit::Event),
Error(Arc<dyn Error + Send + Sync>),
}
#[derive(Debug, Default)]
pub(crate) struct FactBuffer {
facts: std::sync::Mutex<Vec<BufferedFact>>,
}
impl FactBuffer {
pub(crate) fn take_facts(&self) -> Vec<BufferedFact> {
std::mem::take(&mut *self.facts.lock().expect("hook fact lock poisoned"))
}
#[cfg(test)]
pub(crate) fn audit_kinds(&self) -> Vec<String> {
self.facts
.lock()
.expect("hook fact lock poisoned")
.iter()
.filter_map(|fact| match fact {
BufferedFact::Audit(event) => Some(event.kind().to_owned()),
BufferedFact::Error(_) => None,
})
.collect()
}
#[cfg(test)]
pub(crate) fn error_messages(&self) -> Vec<String> {
self.facts
.lock()
.expect("hook fact lock poisoned")
.iter()
.filter_map(|fact| match fact {
BufferedFact::Audit(_) => None,
BufferedFact::Error(error) => Some(error.to_string()),
})
.collect()
}
}
impl Emitter for FactBuffer {
fn emit_audit(&self, event: audit::Event) {
self.facts
.lock()
.expect("hook fact lock poisoned")
.push(BufferedFact::Audit(event));
}
fn emit_error(&self, error: Arc<dyn Error + Send + Sync>) {
self.facts
.lock()
.expect("hook fact lock poisoned")
.push(BufferedFact::Error(error));
}
}
#[derive(Clone, Copy, Debug)]
pub(crate) enum TranscriptSource<'a> {
Reader(&'a SnapshotReader),
Snapshot(&'a Snapshot),
}
impl TranscriptSource<'_> {
pub(crate) fn snapshot(self) -> Result<Snapshot, store::Error> {
match self {
Self::Reader(reader) => reader.snapshot(),
Self::Snapshot(snapshot) => Ok(snapshot.clone()),
}
}
}
#[derive(Clone, Copy, Debug)]
struct ReadBase<'a> {
session: SessionIdentity<'a>,
coord: &'a Coord,
run_state: &'a run_state::Store,
session_state: &'a session_state::Reader,
transcript: TranscriptSource<'a>,
}
#[derive(Clone, Copy, Debug)]
struct WriteBase<'a> {
read: ReadBase<'a>,
session_state: Option<&'a session_state::Writer>,
}
#[derive(Clone, Copy, Debug)]
struct PrepareBase<'a> {
read: ReadBase<'a>,
session_state: Option<&'a session_state::StagedWriter>,
}
#[derive(Clone, Copy)]
struct ControlBase<'a> {
write: WriteBase<'a>,
emitter: &'a dyn Emitter,
}
impl fmt::Debug for ControlBase<'_> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ControlBase")
.field("write", &self.write)
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, Debug)]
struct StagedBase<'a> {
control: ControlBase<'a>,
staged: &'a StagedTranscript,
}
macro_rules! read_capabilities {
($this:ident, $base:expr) => {
#[must_use]
pub const fn session(&$this) -> SessionIdentity<'_> {
$base.read.session
}
#[must_use]
pub const fn coord(&$this) -> &Coord {
$base.read.coord
}
#[must_use]
pub const fn run_state(&$this) -> &run_state::Store {
$base.read.run_state
}
#[must_use]
pub const fn session_state(&$this) -> &session_state::Reader {
$base.read.session_state
}
pub fn transcript(&$this) -> Result<Snapshot, store::Error> {
$base.read.transcript.snapshot()
}
};
}
macro_rules! direct_read_capabilities {
($this:ident, $base:expr) => {
#[must_use]
pub const fn session(&$this) -> SessionIdentity<'_> {
$base.session
}
#[must_use]
pub const fn coord(&$this) -> &Coord {
$base.coord
}
#[must_use]
pub const fn run_state(&$this) -> &run_state::Store {
$base.run_state
}
#[must_use]
pub const fn session_state(&$this) -> &session_state::Reader {
$base.session_state
}
pub fn transcript(&$this) -> Result<Snapshot, store::Error> {
$base.transcript.snapshot()
}
};
}
macro_rules! write_capabilities {
($this:ident, $base:expr) => {
read_capabilities!($this, $base);
#[must_use]
pub const fn session_state_writer(&$this) -> Option<&session_state::Writer> {
$base.session_state
}
};
}
macro_rules! control_capabilities {
($this:ident, $base:expr) => {
write_capabilities!($this, $base.write);
pub fn emit_audit(&$this, event: audit::Event) {
$base.emitter.emit_audit(event);
}
pub fn emit_error(&$this, error: Arc<dyn Error + Send + Sync>) {
$base.emitter.emit_error(error);
}
};
}
macro_rules! staged_capabilities {
($this:ident, $base:expr) => {
control_capabilities!($this, $base.control);
#[must_use]
pub const fn staged(&$this) -> &StagedTranscript {
$base.staged
}
};
}
#[derive(Debug)]
pub struct PrepareScope<'a> {
base: PrepareBase<'a>,
staged: &'a StagedTranscript,
base_snapshot: &'a Snapshot,
input: &'a [Part],
}
impl PrepareScope<'_> {
direct_read_capabilities!(self, self.base.read);
#[must_use]
pub const fn staged_session_state_writer(&self) -> Option<&session_state::StagedWriter> {
self.base.session_state
}
#[must_use]
pub const fn staged(&self) -> &StagedTranscript {
self.staged
}
#[must_use]
pub const fn base_snapshot(&self) -> &Snapshot {
self.base_snapshot
}
#[must_use]
pub const fn input(&self) -> &[Part] {
self.input
}
}
#[derive(Debug)]
pub struct ContinuationScope<'a> {
base: StagedBase<'a>,
continuation: &'a [Part],
continuations: usize,
turns: usize,
}
impl ContinuationScope<'_> {
staged_capabilities!(self, self.base);
#[must_use]
pub const fn continuation(&self) -> &[Part] {
self.continuation
}
#[must_use]
pub const fn continuations(&self) -> usize {
self.continuations
}
#[must_use]
pub const fn turns(&self) -> usize {
self.turns
}
}
#[derive(Debug)]
pub struct StopDecisionScope<'a> {
base: ControlBase<'a>,
}
impl StopDecisionScope<'_> {
control_capabilities!(self, self.base);
}
#[derive(Debug)]
pub struct InputAdmitScope<'a> {
base: ControlBase<'a>,
target: InputTarget,
items: &'a [Item],
}
impl InputAdmitScope<'_> {
control_capabilities!(self, self.base);
#[must_use]
pub const fn target(&self) -> InputTarget {
self.target
}
#[must_use]
pub const fn items(&self) -> &[Item] {
self.items
}
}
#[derive(Debug)]
pub struct TurnScope<'a> {
base: StagedBase<'a>,
trigger: &'a [Item],
}
impl TurnScope<'_> {
staged_capabilities!(self, self.base);
#[must_use]
pub const fn trigger(&self) -> &[Item] {
self.trigger
}
}
#[derive(Debug)]
pub struct StepSnapshot {
model: Info,
plan: RequestPlan,
tools: StepToolSnapshot,
shared_tools: Arc<StepToolSnapshot>,
}
impl StepSnapshot {
pub(crate) fn freeze(model: Info, plan: RequestPlan, tools: StepToolSnapshot) -> Arc<Self> {
let shared_tools = Arc::new(tools.shallow_clone());
Arc::new(Self {
model,
plan,
tools,
shared_tools,
})
}
#[must_use]
pub const fn model(&self) -> &Info {
&self.model
}
#[must_use]
pub const fn plan(&self) -> &RequestPlan {
&self.plan
}
#[must_use]
pub const fn tools(&self) -> &StepToolSnapshot {
&self.tools
}
pub(crate) const fn shared_tools(&self) -> &Arc<StepToolSnapshot> {
&self.shared_tools
}
}
#[derive(Debug)]
pub struct BeforeStepScope<'a> {
base: StagedBase<'a>,
model: &'a Info,
plan: &'a mut RequestPlan,
}
impl BeforeStepScope<'_> {
staged_capabilities!(self, self.base);
#[must_use]
pub const fn model(&self) -> &Info {
self.model
}
pub const fn plan(&mut self) -> &mut RequestPlan {
self.plan
}
}
#[derive(Debug)]
pub struct AfterStepScope<'a> {
base: StagedBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
}
impl AfterStepScope<'_> {
staged_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
}
#[derive(Debug)]
pub struct BeforeModelScope<'a> {
base: ControlBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
request: &'a Request,
}
impl BeforeModelScope<'_> {
control_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
#[must_use]
pub const fn request(&self) -> &Request {
self.request
}
}
#[derive(Debug)]
pub struct AfterModelScope<'a> {
base: ControlBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
output: &'a Assistant,
generated: bool,
finish_reason: &'a str,
completion: CompletionReason,
}
impl AfterModelScope<'_> {
control_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
#[must_use]
pub const fn output(&self) -> &Assistant {
self.output
}
#[must_use]
pub const fn generated(&self) -> bool {
self.generated
}
#[must_use]
pub const fn finish_reason(&self) -> &str {
self.finish_reason
}
#[must_use]
pub const fn completion(&self) -> CompletionReason {
self.completion
}
}
#[derive(Debug)]
pub struct ToolCallScope<'a> {
base: ControlBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
call: &'a ToolCall,
}
impl ToolCallScope<'_> {
control_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
#[must_use]
pub const fn call(&self) -> &ToolCall {
self.call
}
}
#[derive(Debug)]
pub struct ToolResultScope<'a> {
base: ControlBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
call: &'a ToolCall,
disposition: CallDisposition,
result: &'a ToolResult,
}
impl ToolResultScope<'_> {
control_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
#[must_use]
pub const fn call(&self) -> &ToolCall {
self.call
}
#[must_use]
pub const fn disposition(&self) -> CallDisposition {
self.disposition
}
#[must_use]
pub const fn result(&self) -> &ToolResult {
self.result
}
}
#[derive(Debug)]
pub struct AfterToolCommitScope<'a> {
base: StagedBase<'a>,
snapshot: &'a Arc<StepSnapshot>,
result: &'a ToolResult,
}
impl AfterToolCommitScope<'_> {
staged_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> &StepSnapshot {
self.snapshot
}
#[must_use]
pub const fn result(&self) -> &ToolResult {
self.result
}
}
pub struct ObserverScope<'a> {
base: ReadBase<'a>,
snapshot: Option<&'a Arc<StepSnapshot>>,
audit_sink: &'a dyn ObserverAuditSink,
}
impl fmt::Debug for ObserverScope<'_> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ObserverScope")
.field("base", &self.base)
.field("snapshot", &Presence(self.snapshot.is_some()))
.finish_non_exhaustive()
}
}
impl ObserverScope<'_> {
direct_read_capabilities!(self, self.base);
#[must_use]
pub fn snapshot(&self) -> Option<&StepSnapshot> {
self.snapshot.map(Arc::as_ref)
}
pub fn emit_audit(&self, event: audit::Event) {
self.audit_sink.push(event);
}
fn with_audit_sink<'a>(&'a self, audit_sink: &'a dyn ObserverAuditSink) -> ObserverScope<'a> {
ObserverScope {
base: self.base,
snapshot: self.snapshot,
audit_sink,
}
}
}
trait ObserverAuditSink {
fn push(&self, event: audit::Event);
}
struct CallbackAuditBuffer {
pending: RefCell<Vec<audit::Event>>,
}
impl CallbackAuditBuffer {
const fn new() -> Self {
Self {
pending: RefCell::new(Vec::new()),
}
}
fn flush_to(&self, emitter: &dyn Emitter) {
for event in self.pending.borrow_mut().drain(..) {
emitter.emit_audit(event);
}
}
}
impl ObserverAuditSink for CallbackAuditBuffer {
fn push(&self, event: audit::Event) {
self.pending.borrow_mut().push(event);
}
}
struct DirectAuditSink<'a>(&'a dyn Emitter);
impl ObserverAuditSink for DirectAuditSink<'_> {
fn push(&self, event: audit::Event) {
self.0.emit_audit(event);
}
}
#[derive(Debug)]
pub struct ReadScope<'a> {
base: ReadBase<'a>,
}
impl ReadScope<'_> {
direct_read_capabilities!(self, self.base);
}
#[derive(Debug)]
pub enum PrepareDecision {
Continue,
Modify(Vec<Part>),
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum PrepareError {
EmptyModify,
}
impl fmt::Display for PrepareError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyModify => {
formatter.write_str("a registration rewrote the initial input to nothing")
}
}
}
}
impl Error for PrepareError {}
#[derive(Debug)]
pub enum ContinuationDecision {
Keep,
Replace(Vec<Part>),
}
#[derive(Debug)]
pub enum BeforeModelDecision {
Continue,
Modify(Request),
ShortCircuit(Assistant),
Abort(String),
}
#[derive(Debug)]
pub enum AfterModelDecision {
Continue,
Modify(Assistant),
}
#[derive(Debug)]
pub enum ToolCallDecision {
Continue,
Modify(ToolCall),
Block(String),
ShortCircuit(ToolResult),
}
#[derive(Debug)]
pub enum ToolResultDecision {
Continue,
Modify(ToolResult),
}
#[derive(Debug)]
pub enum InputAdmitDecision {
Admit,
Modify(Vec<Item>),
Reject(String),
}
#[derive(Debug)]
pub enum StopDecision {
Continue,
Stop(StopCode),
}
#[derive(Debug)]
pub enum AfterStepDecision {
Continue(Vec<Item>),
EndTurn(Vec<Item>),
}
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum LifecycleKind {
RunStart,
RunEnd,
TurnStart,
TurnEnd,
StepStart,
StepEnd,
GenerationStart,
GenerationEnd,
ToolCallStart,
ToolCallEnd,
}
#[derive(Clone)]
#[non_exhaustive]
pub enum LifecycleEnd {
Completed,
#[non_exhaustive]
Stopped {
code: Option<StopCode>,
},
#[non_exhaustive]
Cancelled {
error: Arc<dyn Error + Send + Sync>,
},
#[non_exhaustive]
Failed {
error: Arc<dyn Error + Send + Sync>,
},
}
impl fmt::Debug for LifecycleEnd {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Completed => formatter.write_str("Completed"),
Self::Stopped { code } => formatter
.debug_struct("Stopped")
.field("code", code)
.finish(),
Self::Cancelled { error } => formatter
.debug_struct("Cancelled")
.field("error", &error.to_string())
.finish(),
Self::Failed { error } => formatter
.debug_struct("Failed")
.field("error", &error.to_string())
.finish(),
}
}
}
impl LifecycleEnd {
#[must_use]
pub const fn outcome(&self) -> Outcome {
match self {
Self::Completed => Outcome::Completed,
Self::Stopped { .. } => Outcome::Stopped,
Self::Cancelled { .. } => Outcome::Cancelled,
Self::Failed { .. } => Outcome::Failed,
}
}
#[must_use]
pub const fn stop_code(&self) -> Option<&StopCode> {
match self {
Self::Stopped { code } => code.as_ref(),
Self::Completed | Self::Cancelled { .. } | Self::Failed { .. } => None,
}
}
#[must_use]
pub fn error(&self) -> Option<&(dyn Error + Send + Sync)> {
match self {
Self::Cancelled { error } | Self::Failed { error } => Some(error.as_ref()),
Self::Completed | Self::Stopped { .. } => None,
}
}
}
#[derive(Clone, Debug)]
pub struct ToolCallProgress {
disposition: CallDisposition,
state: ToolCallProgressState,
}
#[derive(Clone, Debug)]
enum ToolCallProgressState {
Observed,
ResultAvailable(ToolResult),
ResultCommitted(ToolResult),
PostHooksCompleted(ToolResult),
}
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum ToolCallProgressKind {
Observed,
ResultAvailable,
ResultCommitted,
PostHooksCompleted,
}
impl ToolCallProgress {
pub(crate) const fn observed(disposition: CallDisposition) -> Self {
Self {
disposition,
state: ToolCallProgressState::Observed,
}
}
pub(crate) const fn result_available(disposition: CallDisposition, result: ToolResult) -> Self {
Self {
disposition,
state: ToolCallProgressState::ResultAvailable(result),
}
}
pub(crate) const fn result_committed(disposition: CallDisposition, result: ToolResult) -> Self {
Self {
disposition,
state: ToolCallProgressState::ResultCommitted(result),
}
}
pub(crate) const fn completed_post_hooks(
disposition: CallDisposition,
result: ToolResult,
) -> Self {
Self {
disposition,
state: ToolCallProgressState::PostHooksCompleted(result),
}
}
#[must_use]
pub const fn disposition(&self) -> CallDisposition {
self.disposition
}
#[must_use]
pub const fn kind(&self) -> ToolCallProgressKind {
match self.state {
ToolCallProgressState::Observed => ToolCallProgressKind::Observed,
ToolCallProgressState::ResultAvailable(_) => ToolCallProgressKind::ResultAvailable,
ToolCallProgressState::ResultCommitted(_) => ToolCallProgressKind::ResultCommitted,
ToolCallProgressState::PostHooksCompleted(_) => {
ToolCallProgressKind::PostHooksCompleted
}
}
}
#[must_use]
pub const fn result(&self) -> Option<&ToolResult> {
match &self.state {
ToolCallProgressState::Observed => None,
ToolCallProgressState::ResultAvailable(result)
| ToolCallProgressState::ResultCommitted(result)
| ToolCallProgressState::PostHooksCompleted(result) => Some(result),
}
}
#[must_use]
pub const fn is_result_committed(&self) -> bool {
matches!(
self.state,
ToolCallProgressState::ResultCommitted(_)
| ToolCallProgressState::PostHooksCompleted(_)
)
}
#[must_use]
pub const fn post_hooks_completed(&self) -> bool {
matches!(self.state, ToolCallProgressState::PostHooksCompleted(_))
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum ToolCallEndError {
InvalidDisposition {
disposition: CallDisposition,
progress: ToolCallProgressKind,
},
CompletedBeforePostHooks(ToolCallProgressKind),
PostHooksWithoutCompletion(Outcome),
}
#[derive(Clone, Debug)]
pub struct ToolCallEndObservation {
coord: Coord,
end: LifecycleEnd,
original_call: ToolCall,
effective_call: ToolCall,
progress: ToolCallProgress,
}
impl ToolCallEndObservation {
pub(crate) fn try_new(
coord: Coord,
end: LifecycleEnd,
original_call: ToolCall,
effective_call: ToolCall,
progress: ToolCallProgress,
) -> Result<Self, ToolCallEndError> {
let progress_kind = progress.kind();
let disposition = progress.disposition();
let disposition_matches_progress = match progress_kind {
ToolCallProgressKind::Observed => matches!(
disposition,
CallDisposition::Truncated | CallDisposition::NotExecuted
),
ToolCallProgressKind::ResultAvailable
| ToolCallProgressKind::ResultCommitted
| ToolCallProgressKind::PostHooksCompleted => !matches!(
disposition,
CallDisposition::Truncated | CallDisposition::NotExecuted
),
};
if !disposition_matches_progress {
return Err(ToolCallEndError::InvalidDisposition {
disposition,
progress: progress_kind,
});
}
match (&end, progress_kind) {
(LifecycleEnd::Completed, ToolCallProgressKind::PostHooksCompleted) => {}
(LifecycleEnd::Completed, incomplete) => {
return Err(ToolCallEndError::CompletedBeforePostHooks(incomplete));
}
(
LifecycleEnd::Stopped { .. }
| LifecycleEnd::Cancelled { .. }
| LifecycleEnd::Failed { .. },
ToolCallProgressKind::PostHooksCompleted,
) => {
return Err(ToolCallEndError::PostHooksWithoutCompletion(end.outcome()));
}
(
LifecycleEnd::Stopped { .. }
| LifecycleEnd::Cancelled { .. }
| LifecycleEnd::Failed { .. },
ToolCallProgressKind::Observed
| ToolCallProgressKind::ResultAvailable
| ToolCallProgressKind::ResultCommitted,
) => {}
}
Ok(Self {
coord,
end,
original_call,
effective_call,
progress,
})
}
#[must_use]
pub const fn coord(&self) -> &Coord {
&self.coord
}
#[must_use]
pub const fn end(&self) -> &LifecycleEnd {
&self.end
}
#[must_use]
pub const fn original_call(&self) -> &ToolCall {
&self.original_call
}
#[must_use]
pub const fn effective_call(&self) -> &ToolCall {
&self.effective_call
}
#[must_use]
pub const fn progress(&self) -> &ToolCallProgress {
&self.progress
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum LifecycleObservation {
#[non_exhaustive]
RunStart {
coord: Coord,
input: Vec<Part>,
},
#[non_exhaustive]
RunEnd {
coord: Coord,
end: LifecycleEnd,
turns: usize,
},
#[non_exhaustive]
TurnStart {
coord: Coord,
trigger: Vec<Item>,
},
#[non_exhaustive]
TurnEnd {
coord: Coord,
end: LifecycleEnd,
steps: usize,
},
#[non_exhaustive]
StepStart {
coord: Coord,
snapshot: Arc<StepSnapshot>,
},
#[non_exhaustive]
StepEnd {
coord: Coord,
end: LifecycleEnd,
snapshot: Arc<StepSnapshot>,
},
#[non_exhaustive]
GenerationStart {
coord: Coord,
request: Request,
},
#[non_exhaustive]
GenerationEnd {
coord: Coord,
end: LifecycleEnd,
finish_reason: String,
completion: CompletionReason,
},
#[non_exhaustive]
ToolCallStart {
coord: Coord,
call: ToolCall,
},
ToolCallEnd(ToolCallEndObservation),
}
impl LifecycleObservation {
#[must_use]
pub const fn kind(&self) -> LifecycleKind {
match self {
Self::RunStart { .. } => LifecycleKind::RunStart,
Self::RunEnd { .. } => LifecycleKind::RunEnd,
Self::TurnStart { .. } => LifecycleKind::TurnStart,
Self::TurnEnd { .. } => LifecycleKind::TurnEnd,
Self::StepStart { .. } => LifecycleKind::StepStart,
Self::StepEnd { .. } => LifecycleKind::StepEnd,
Self::GenerationStart { .. } => LifecycleKind::GenerationStart,
Self::GenerationEnd { .. } => LifecycleKind::GenerationEnd,
Self::ToolCallStart { .. } => LifecycleKind::ToolCallStart,
Self::ToolCallEnd(_) => LifecycleKind::ToolCallEnd,
}
}
#[must_use]
pub const fn coord(&self) -> &Coord {
match self {
Self::RunStart { coord, .. }
| Self::RunEnd { coord, .. }
| Self::TurnStart { coord, .. }
| Self::TurnEnd { coord, .. }
| Self::StepStart { coord, .. }
| Self::StepEnd { coord, .. }
| Self::GenerationStart { coord, .. }
| Self::GenerationEnd { coord, .. }
| Self::ToolCallStart { coord, .. } => coord,
Self::ToolCallEnd(observation) => observation.coord(),
}
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum TranscriptMutation {
#[non_exhaustive]
Append {
previous: Version,
version: Version,
items: Vec<Item>,
},
#[non_exhaustive]
Replace {
previous: Version,
snapshot: Snapshot,
},
}
impl TranscriptMutation {
#[must_use]
pub const fn previous_version(&self) -> Version {
match self {
Self::Append { previous, .. } | Self::Replace { previous, .. } => *previous,
}
}
#[must_use]
pub const fn version(&self) -> Version {
match self {
Self::Append { version, .. } => *version,
Self::Replace { snapshot, .. } => snapshot.version(),
}
}
#[must_use]
pub fn items(&self) -> &[Item] {
match self {
Self::Append { items, .. } => items,
Self::Replace { snapshot, .. } => snapshot.items(),
}
}
#[must_use]
pub const fn replacement(&self) -> Option<&Snapshot> {
match self {
Self::Append { .. } => None,
Self::Replace { snapshot, .. } => Some(snapshot),
}
}
}
pub trait TranscriptReservation: Send {
fn publish(self: Box<Self>);
fn abort(self: Box<Self>) {}
}
pub trait RunHooks: Send + Sync {
fn prepare(&self, scope: &PrepareScope<'_>) -> HookResult<PrepareDecision>;
fn compose_continuation(
&self,
scope: &ContinuationScope<'_>,
) -> HookResult<ContinuationDecision>;
fn decide_stop(&self, scope: &StopDecisionScope<'_>) -> HookResult<StopDecision>;
}
pub trait InputHooks: Send + Sync {
fn before_input_admit(&self, scope: &InputAdmitScope<'_>) -> InputAdmitDecision;
}
pub trait TurnStepHooks: Send + Sync {
fn before_turn(&self, scope: &TurnScope<'_>) -> HookResult<Vec<Item>>;
fn after_turn(&self, scope: &TurnScope<'_>) -> HookResult<Vec<Item>>;
fn before_step(&self, scope: &mut BeforeStepScope<'_>) -> HookResult<Vec<Item>>;
fn after_step(&self, scope: &AfterStepScope<'_>) -> HookResult<AfterStepDecision>;
}
pub trait ModelHooks: Send + Sync {
fn before_model(&self, scope: &BeforeModelScope<'_>) -> HookResult<BeforeModelDecision>;
fn after_model(&self, scope: &AfterModelScope<'_>) -> AfterModelDecision;
}
pub trait ToolHooks: Send + Sync {
fn before_tool_call(&self, scope: &ToolCallScope<'_>) -> HookResult<ToolCallDecision>;
fn before_tool_result(&self, scope: &ToolResultScope<'_>) -> HookResult<ToolResultDecision>;
fn after_tool_commit(&self, scope: &AfterToolCommitScope<'_>) -> Vec<Item>;
}
pub trait ObserverHooks: Send + Sync {
fn run_admitted(&self, scope: &ReadScope<'_>) {
let _ = scope;
}
fn lifecycle(&self, observation: &LifecycleObservation, scope: &ObserverScope<'_>) {
let _ = (observation, scope);
}
fn model_event(&self, scope: &ObserverScope<'_>, event: &model::Event) {
let _ = (scope, event);
}
fn audit_event(&self, scope: &ReadScope<'_>, event: &audit::Event) {
let _ = (scope, event);
}
}
pub trait TranscriptHooks: Send + Sync {
fn reserve(
&self,
scope: &ReadScope<'_>,
mutation: &TranscriptMutation,
) -> HookResult<Box<dyn TranscriptReservation>>;
}
pub trait AgentTeardown: Send + Sync {
fn close(&self) -> HookResult<()>;
}
pub struct Registration {
name: String,
requires_session_state: bool,
run: Option<Arc<dyn RunHooks>>,
input: Option<Arc<dyn InputHooks>>,
turn_step: Option<Arc<dyn TurnStepHooks>>,
model: Option<Arc<dyn ModelHooks>>,
tool: Option<Arc<dyn ToolHooks>>,
observer: Option<Arc<dyn ObserverHooks>>,
transcript: Option<Arc<dyn TranscriptHooks>>,
teardown: Option<Arc<dyn AgentTeardown>>,
}
impl fmt::Debug for Registration {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Registration")
.field("name", &self.name)
.field("requires_session_state", &self.requires_session_state)
.field("run", &Presence(self.run.is_some()))
.field("input", &Presence(self.input.is_some()))
.field("turn_step", &Presence(self.turn_step.is_some()))
.field("model", &Presence(self.model.is_some()))
.field("tool", &Presence(self.tool.is_some()))
.field("observer", &Presence(self.observer.is_some()))
.field("transcript", &Presence(self.transcript.is_some()))
.field("teardown", &Presence(self.teardown.is_some()))
.finish()
}
}
impl Registration {
#[must_use]
pub fn new(name: String) -> Self {
Self {
name,
requires_session_state: false,
run: None,
input: None,
turn_step: None,
model: None,
tool: None,
observer: None,
transcript: None,
teardown: None,
}
}
#[must_use]
pub const fn requires_session_state(mut self, required: bool) -> Self {
self.requires_session_state = required;
self
}
#[must_use]
pub fn run(mut self, hooks: Arc<dyn RunHooks>) -> Self {
self.run = Some(hooks);
self
}
#[must_use]
pub fn input(mut self, hooks: Arc<dyn InputHooks>) -> Self {
self.input = Some(hooks);
self
}
#[must_use]
pub fn turn_step(mut self, hooks: Arc<dyn TurnStepHooks>) -> Self {
self.turn_step = Some(hooks);
self
}
#[must_use]
pub fn model(mut self, hooks: Arc<dyn ModelHooks>) -> Self {
self.model = Some(hooks);
self
}
#[must_use]
pub fn tool(mut self, hooks: Arc<dyn ToolHooks>) -> Self {
self.tool = Some(hooks);
self
}
#[must_use]
pub fn observer(mut self, hooks: Arc<dyn ObserverHooks>) -> Self {
self.observer = Some(hooks);
self
}
#[must_use]
pub fn transcript(mut self, hooks: Arc<dyn TranscriptHooks>) -> Self {
self.transcript = Some(hooks);
self
}
#[must_use]
pub fn teardown(mut self, hooks: Arc<dyn AgentTeardown>) -> Self {
self.teardown = Some(hooks);
self
}
}
struct RegisteredHook {
registration: Registration,
}
pub(crate) struct RegistrationAdapter<'a, H: ?Sized> {
index: usize,
name: &'a str,
requires_session_state: bool,
hook: &'a H,
}
pub(crate) struct OwnedToolRegistrationAdapter {
index: usize,
name: String,
requires_session_state: bool,
hook: Arc<dyn ToolHooks>,
}
impl<'a, H: ?Sized> RegistrationAdapter<'a, H> {
pub(crate) const fn index(&self) -> usize {
self.index
}
#[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
pub(crate) const fn name(&self) -> &'a str {
self.name
}
#[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
pub(crate) const fn requires_session_state(&self) -> bool {
self.requires_session_state
}
#[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
pub(crate) const fn hook(&self) -> &'a H {
self.hook
}
}
impl OwnedToolRegistrationAdapter {
pub(crate) const fn index(&self) -> usize {
self.index
}
pub(crate) fn name(&self) -> &str {
&self.name
}
pub(crate) fn invoke_after_tool_commit(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
snapshot: &Arc<StepSnapshot>,
result: &ToolResult,
) -> Vec<Item> {
RegistrationAdapter {
index: self.index,
name: &self.name,
requires_session_state: self.requires_session_state,
hook: &*self.hook,
}
.invoke_after_tool_commit(resources, staged, snapshot, result)
}
}
#[derive(Clone, Copy)]
pub(crate) struct CallbackResources<'a> {
coord: &'a Coord,
run_state: &'a run_state::Store,
session_state: &'a session_state::Reader,
session_state_writer: Option<&'a session_state::Writer>,
emitter: &'a dyn Emitter,
}
pub(crate) struct OwnedCallbackResources {
run_state: run_state::Store,
session_state: session_state::Reader,
session_state_writer: Option<session_state::Writer>,
callback_write_permit: Option<CallbackWritePermit>,
}
impl OwnedCallbackResources {
pub(crate) fn callback_write_permit(&self) -> Option<CallbackWritePermit> {
self.callback_write_permit.clone()
}
pub(crate) fn bind<'a>(
&'a self,
coord: &'a Coord,
emitter: &'a dyn Emitter,
) -> CallbackResources<'a> {
CallbackResources::new(
coord,
&self.run_state,
&self.session_state,
self.session_state_writer.as_ref(),
emitter,
)
}
}
impl<'a> CallbackResources<'a> {
pub(crate) const fn new(
coord: &'a Coord,
run_state: &'a run_state::Store,
session_state: &'a session_state::Reader,
session_state_writer: Option<&'a session_state::Writer>,
emitter: &'a dyn Emitter,
) -> Self {
Self {
coord,
run_state,
session_state,
session_state_writer,
emitter,
}
}
pub(crate) fn owned_handles(self) -> OwnedCallbackResources {
let (session_state_writer, callback_write_permit) = match self.session_state_writer {
Some(writer) => {
let (writer, permit) = writer.clone_with_callback_permit();
(Some(writer), Some(permit))
}
None => (None, None),
};
OwnedCallbackResources {
run_state: self.run_state.clone_handle(),
session_state: self.session_state.clone_handle(),
session_state_writer,
callback_write_permit,
}
}
pub(crate) const fn with_coord<'b>(self, coord: &'b Coord) -> CallbackResources<'b>
where
'a: 'b,
{
self.rebind(coord, self.emitter)
}
pub(crate) const fn rebind<'b>(
self,
coord: &'b Coord,
emitter: &'b dyn Emitter,
) -> CallbackResources<'b>
where
'a: 'b,
{
CallbackResources {
coord,
run_state: self.run_state,
session_state: self.session_state,
session_state_writer: self.session_state_writer,
emitter,
}
}
const fn scope_factory(
self,
requires_session_state: bool,
transcript: TranscriptSource<'a>,
) -> ScopeFactory<'a> {
ScopeFactory::new(
self.coord,
self.run_state,
self.session_state,
self.session_state_writer,
requires_session_state,
transcript,
self.emitter,
)
}
}
impl RegistrationAdapter<'_, dyn RunHooks> {
pub(crate) fn invoke_prepare(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
session_state_stage: Option<&session_state::StagedWriter>,
base_snapshot: &Snapshot,
input: &[Part],
cancellation: &Token,
) -> Result<PrepareDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let scope = factory.prepare(staged, session_state_stage, base_snapshot, input);
match self.hook.prepare(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(PrepareDecision::Modify(replacement)) if replacement.is_empty() => {
Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error: HookError::new(PrepareError::EmptyModify),
}))
}
Ok(decision) => Ok(decision),
}
}
pub(crate) fn invoke_compose_continuation(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
continuation: &[Part],
continuations: usize,
turns: usize,
cancellation: &Token,
) -> Result<ContinuationDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let scope = factory.compose_continuation(staged, continuation, continuations, turns);
match self.hook.compose_continuation(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(decision) => Ok(decision),
}
}
pub(crate) fn invoke_decide_stop(
&self,
resources: CallbackResources<'_>,
transcript: &SnapshotReader,
cancellation: &Token,
) -> Result<StopDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(transcript),
);
let scope = factory.decide_stop();
match self.hook.decide_stop(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(decision) => Ok(decision),
}
}
}
impl RegistrationAdapter<'_, dyn TurnStepHooks> {
pub(crate) fn invoke_before_turn(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
trigger: &[Item],
cancellation: &Token,
) -> Result<Vec<Item>, DispatchError> {
self.invoke_turn(resources, staged, trigger, cancellation, TurnHook::Before)
}
pub(crate) fn invoke_after_turn(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
trigger: &[Item],
cancellation: &Token,
) -> Result<Vec<Item>, DispatchError> {
self.invoke_turn(resources, staged, trigger, cancellation, TurnHook::After)
}
fn invoke_turn(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
trigger: &[Item],
cancellation: &Token,
boundary: TurnHook,
) -> Result<Vec<Item>, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let scope = factory.turn(staged, trigger);
let result = match boundary {
TurnHook::Before => self.hook.before_turn(&scope),
TurnHook::After => self.hook.after_turn(&scope),
};
match result {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_items) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(items) => Ok(items),
}
}
pub(crate) fn invoke_after_step(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
snapshot: &Arc<StepSnapshot>,
cancellation: &Token,
) -> Result<AfterStepDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let scope = factory.after_step(staged, snapshot);
match self.hook.after_step(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(decision) => Ok(decision),
}
}
pub(crate) fn invoke_before_step(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
model: &Info,
plan: &mut RequestPlan,
cancellation: &Token,
) -> Result<Vec<Item>, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let mut scope = factory.before_step(staged, model, plan);
match self.hook.before_step(&mut scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_items) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(items) => Ok(items),
}
}
}
impl RegistrationAdapter<'_, dyn ObserverHooks> {
pub(crate) fn invoke_lifecycle(
&self,
resources: CallbackResources<'_>,
transcript: TranscriptSource<'_>,
snapshot: Option<&Arc<StepSnapshot>>,
observation: &LifecycleObservation,
) {
let factory = resources.scope_factory(self.requires_session_state, transcript);
let pending = CallbackAuditBuffer::new();
let scope = factory.observer(snapshot);
let buffered_scope = scope.with_audit_sink(&pending);
let panicked = match catch_unwind(AssertUnwindSafe(|| {
self.hook.lifecycle(observation, &buffered_scope);
})) {
Ok(()) => false,
Err(payload) => {
std::mem::forget(payload);
true
}
};
pending.flush_to(resources.emitter);
if panicked {
emit_observer_panic(
resources.emitter,
self.name,
lifecycle_hook_name(observation.kind()),
);
}
}
pub(crate) fn invoke_run_admitted(
&self,
resources: CallbackResources<'_>,
transcript: &SnapshotReader,
) {
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(transcript),
);
let scope = factory.read();
let panicked = match catch_unwind(AssertUnwindSafe(|| self.hook.run_admitted(&scope))) {
Ok(()) => false,
Err(payload) => {
std::mem::forget(payload);
true
}
};
if panicked {
emit_observer_panic(resources.emitter, self.name, "OnRunAdmitted");
}
}
pub(crate) fn invoke_model_event(
&self,
resources: CallbackResources<'_>,
transcript: &Snapshot,
snapshot: Option<&Arc<StepSnapshot>>,
event: &model::Event,
) {
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(transcript),
);
let pending = CallbackAuditBuffer::new();
let scope = factory.observer(snapshot);
let buffered_scope = scope.with_audit_sink(&pending);
let panicked = match catch_unwind(AssertUnwindSafe(|| {
self.hook.model_event(&buffered_scope, event);
})) {
Ok(()) => false,
Err(payload) => {
std::mem::forget(payload);
true
}
};
pending.flush_to(resources.emitter);
if panicked {
emit_observer_panic(resources.emitter, self.name, "OnModelEvent");
}
}
pub(crate) fn invoke_audit_event(
&self,
resources: CallbackResources<'_>,
transcript: &SnapshotReader,
event: &audit::Event,
) {
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(transcript),
);
let scope = factory.read();
let panicked = match catch_unwind(AssertUnwindSafe(|| self.hook.audit_event(&scope, event)))
{
Ok(()) => false,
Err(payload) => {
std::mem::forget(payload);
true
}
};
if panicked {
emit_observer_panic(resources.emitter, self.name, "OnAuditEvent");
}
}
}
impl RegistrationAdapter<'_, dyn InputHooks> {
pub(crate) fn invoke_before_input_admit(
&self,
resources: CallbackResources<'_>,
transcript: &SnapshotReader,
target: InputTarget,
items: &[Item],
cancellation: &Token,
) -> Result<InputAdmitDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(transcript),
);
let scope = factory.input_admit(target, items);
let decision = self.hook.before_input_admit(&scope);
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
Ok(decision)
}
}
fn validate_hook_assistant(
registration: &str,
assistant: &Assistant,
snapshot: &StepSnapshot,
) -> Result<(), DispatchError> {
model::validate_assistant(assistant, snapshot.tools().transcript().items()).map_err(|error| {
DispatchError::Callback(AttributedError {
name: registration.to_owned(),
error: HookError::new(error),
})
})
}
impl RegistrationAdapter<'_, dyn ModelHooks> {
pub(crate) fn invoke_before_model(
&self,
resources: CallbackResources<'_>,
snapshot: &Arc<StepSnapshot>,
request: &Request,
cancellation: &Token,
) -> Result<BeforeModelDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(snapshot.tools().transcript()),
);
let scope = factory.before_model(snapshot, request);
match self.hook.before_model(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(decision) => {
if let BeforeModelDecision::ShortCircuit(assistant) = &decision {
validate_hook_assistant(self.name, assistant, snapshot)?;
}
Ok(decision)
}
}
}
#[expect(
clippy::too_many_arguments,
reason = "OnAfterModel observes five independent frozen model facts plus its resources"
)]
pub(crate) fn invoke_after_model(
&self,
resources: CallbackResources<'_>,
snapshot: &Arc<StepSnapshot>,
output: &Assistant,
generated: bool,
finish_reason: &str,
completion: CompletionReason,
cancellation: &Token,
) -> Result<AfterModelDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(snapshot.tools().transcript()),
);
let scope = factory.after_model(snapshot, output, generated, finish_reason, completion);
let decision = self.hook.after_model(&scope);
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
if let AfterModelDecision::Modify(assistant) = &decision {
validate_hook_assistant(self.name, assistant, snapshot)?;
}
Ok(decision)
}
}
impl RegistrationAdapter<'_, dyn ToolHooks> {
pub(crate) fn invoke_before_tool_call(
&self,
resources: CallbackResources<'_>,
snapshot: &Arc<StepSnapshot>,
call: &ToolCall,
cancellation: &Token,
) -> Result<ToolCallDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(snapshot.tools().transcript()),
);
let scope = factory.tool_call(snapshot, call);
match self.hook.before_tool_call(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(ToolCallDecision::Modify(modified)) if modified.name().as_str().is_empty() => {
Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error: HookError::new(model::RequestError::EmptyToolCallName {
call_id: call.id().as_str().to_owned(),
}),
}))
}
Ok(decision) => Ok(decision),
}
}
pub(crate) fn invoke_before_tool_result(
&self,
resources: CallbackResources<'_>,
snapshot: &Arc<StepSnapshot>,
call: &ToolCall,
disposition: CallDisposition,
result: &ToolResult,
cancellation: &Token,
) -> Result<ToolResultDecision, DispatchError> {
if cancellation.is_cancelled() {
return Err(DispatchError::Cancelled);
}
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(snapshot.tools().transcript()),
);
let scope = factory.tool_result(snapshot, call, disposition, result);
match self.hook.before_tool_result(&scope) {
Err(error) => Err(DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})),
Ok(_decision) if cancellation.is_cancelled() => Err(DispatchError::Cancelled),
Ok(decision) => Ok(decision),
}
}
pub(crate) fn invoke_after_tool_commit(
&self,
resources: CallbackResources<'_>,
staged: &StagedTranscript,
snapshot: &Arc<StepSnapshot>,
result: &ToolResult,
) -> Vec<Item> {
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Reader(&staged.reader),
);
let scope = factory.after_tool_commit(staged, snapshot, result);
self.hook.after_tool_commit(&scope)
}
}
impl RegistrationAdapter<'_, dyn TranscriptHooks> {
pub(crate) fn invoke_reserve(
&self,
resources: CallbackResources<'_>,
transcript: &Snapshot,
mutation: &TranscriptMutation,
) -> Result<Box<dyn TranscriptReservation>, DispatchError> {
let factory = resources.scope_factory(
self.requires_session_state,
TranscriptSource::Snapshot(transcript),
);
let scope = factory.read();
self.hook.reserve(&scope, mutation).map_err(|error| {
DispatchError::Callback(AttributedError {
name: self.name.to_owned(),
error,
})
})
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum RegistryError {
EmptyName,
DuplicateName(String),
}
impl fmt::Display for RegistryError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyName => formatter.write_str("hook name must be non-empty"),
Self::DuplicateName(name) => write!(formatter, "duplicate hook name: {name}"),
}
}
}
impl Error for RegistryError {}
#[derive(Clone, Debug)]
pub struct AttributedError {
name: String,
error: HookError,
}
impl AttributedError {
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn error(&self) -> &HookError {
&self.error
}
}
impl fmt::Display for AttributedError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "hook {} failed: {}", self.name, self.error)
}
}
impl Error for AttributedError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(&self.error)
}
}
#[derive(Clone, Copy)]
enum TurnHook {
Before,
After,
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub(crate) enum DispatchError {
Callback(AttributedError),
Cancelled,
}
impl fmt::Display for DispatchError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Callback(failure) => write!(
formatter,
"hook {} failed: {}",
failure.name(),
failure.error()
),
Self::Cancelled => formatter.write_str("cancelled around a callback"),
}
}
}
impl Error for DispatchError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Callback(failure) => Some(failure),
Self::Cancelled => None,
}
}
}
#[derive(Default)]
pub struct RegistryBuilder {
hooks: Vec<Registration>,
}
impl fmt::Debug for RegistryBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
debug_hook_names("RegistryBuilder", self.hooks.iter(), formatter)
}
}
fn debug_hook_names<'a>(
name: &str,
hooks: impl Iterator<Item = &'a Registration>,
formatter: &mut fmt::Formatter<'_>,
) -> fmt::Result {
formatter
.debug_struct(name)
.field(
"hooks",
&hooks
.map(|registration| registration.name.as_str())
.collect::<Vec<_>>(),
)
.finish()
}
impl RegistryBuilder {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn register(&mut self, hook: Registration) -> &mut Self {
self.hooks.push(hook);
self
}
pub(crate) fn build_runtime(self) -> Result<RuntimeRegistry, RegistryError> {
self.freeze().map(RuntimeRegistry::new)
}
fn freeze(self) -> Result<FrozenRegistry, RegistryError> {
let mut names = std::collections::HashSet::new();
let mut hooks = Vec::with_capacity(self.hooks.len());
for registration in self.hooks {
if registration.name.is_empty() {
return Err(RegistryError::EmptyName);
}
if !names.insert(registration.name.clone()) {
return Err(RegistryError::DuplicateName(registration.name));
}
hooks.push(RegisteredHook { registration });
}
Ok(FrozenRegistry {
hooks: hooks.into(),
})
}
}
#[derive(Clone)]
pub(crate) struct FrozenRegistry {
hooks: Arc<[RegisteredHook]>,
}
#[derive(Clone)]
pub(crate) struct RuntimeRegistry {
frozen: FrozenRegistry,
}
impl RuntimeRegistry {
const fn new(frozen: FrozenRegistry) -> Self {
Self { frozen }
}
}
impl std::ops::Deref for RuntimeRegistry {
type Target = FrozenRegistry;
fn deref(&self) -> &Self::Target {
&self.frozen
}
}
impl fmt::Debug for RuntimeRegistry {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
debug_hook_names(
"RuntimeRegistry",
self.frozen.hooks.iter().map(|hook| &hook.registration),
formatter,
)
}
}
impl FrozenRegistry {
#[must_use]
pub(crate) fn len(&self) -> usize {
self.hooks.len()
}
#[cfg(test)]
#[must_use]
pub(crate) fn is_empty(&self) -> bool {
self.hooks.is_empty()
}
#[must_use]
pub(crate) fn names(&self) -> impl ExactSizeIterator<Item = &str> {
self.hooks
.iter()
.map(|hook| hook.registration.name.as_str())
}
#[must_use]
pub(crate) fn requires_session_state(&self) -> bool {
self.hooks
.iter()
.any(|hook| hook.registration.requires_session_state)
}
pub(crate) fn run_hooks(&self) -> impl Iterator<Item = RegistrationAdapter<'_, dyn RunHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.run
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn input_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn InputHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.input
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn turn_step_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn TurnStepHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.turn_step
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn model_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn ModelHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.model
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn tool_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn ToolHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.tool
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn owned_tool_hooks(
&self,
) -> impl Iterator<Item = OwnedToolRegistrationAdapter> + '_ {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.tool
.as_ref()
.map(|hook| OwnedToolRegistrationAdapter {
index,
name: registered.registration.name.clone(),
requires_session_state: registered.registration.requires_session_state,
hook: Arc::clone(hook),
})
})
}
pub(crate) fn observer_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn ObserverHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.observer
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
pub(crate) fn transcript_hooks(
&self,
) -> impl Iterator<Item = RegistrationAdapter<'_, dyn TranscriptHooks>> {
self.hooks
.iter()
.enumerate()
.filter_map(|(index, registered)| {
registered
.registration
.transcript
.as_deref()
.map(|hook| RegistrationAdapter {
index,
name: registered.registration.name.as_str(),
requires_session_state: registered.registration.requires_session_state,
hook,
})
})
}
#[must_use]
pub(crate) fn close(&self) -> Vec<AttributedError> {
let panic_error = HookError::new(crate::runtime::agent::ClosePanickedError);
let mut failures = Vec::new();
for hook in self.hooks.iter() {
let Some(teardown) = &hook.registration.teardown else {
continue;
};
let error = match catch_unwind(AssertUnwindSafe(|| teardown.close())) {
Ok(Ok(())) => continue,
Ok(Err(error)) => error,
Err(payload) => {
std::mem::forget(payload);
panic_error.clone()
}
};
failures.push(AttributedError {
name: hook.registration.name.clone(),
error,
});
}
failures
}
}
pub(crate) const fn lifecycle_hook_name(kind: LifecycleKind) -> &'static str {
match kind {
LifecycleKind::RunStart => "OnRunStart",
LifecycleKind::RunEnd => "OnRunEnd",
LifecycleKind::TurnStart => "OnTurnStart",
LifecycleKind::TurnEnd => "OnTurnEnd",
LifecycleKind::StepStart => "OnStepStart",
LifecycleKind::StepEnd => "OnStepEnd",
LifecycleKind::GenerationStart => "OnGenerationStart",
LifecycleKind::GenerationEnd => "OnGenerationEnd",
LifecycleKind::ToolCallStart => "OnToolCallStart",
LifecycleKind::ToolCallEnd => "OnToolCallEnd",
}
}
fn emit_observer_panic(emitter: &dyn Emitter, registration: &str, callback: &str) {
let payload = format!("{registration}:{callback}")
.into_bytes()
.into_boxed_slice();
emitter.emit_audit(audit::Event::new(
"hook.observer_panic".to_owned(),
Some(payload),
));
}
pub(crate) struct ScopeFactory<'a> {
coord: &'a Coord,
run_state: &'a run_state::Store,
session_state: &'a session_state::Reader,
session_state_writer: Option<&'a session_state::Writer>,
requires_session_state: bool,
transcript: TranscriptSource<'a>,
emitter: &'a dyn Emitter,
direct_audit: DirectAuditSink<'a>,
}
impl<'a> ScopeFactory<'a> {
pub(crate) const fn new(
coord: &'a Coord,
run_state: &'a run_state::Store,
session_state: &'a session_state::Reader,
session_state_writer: Option<&'a session_state::Writer>,
requires_session_state: bool,
transcript: TranscriptSource<'a>,
emitter: &'a dyn Emitter,
) -> Self {
Self {
coord,
run_state,
session_state,
session_state_writer,
requires_session_state,
transcript,
emitter,
direct_audit: DirectAuditSink(emitter),
}
}
const fn read_base(&self) -> ReadBase<'a> {
ReadBase {
session: SessionIdentity(self.coord),
coord: self.coord,
run_state: self.run_state,
session_state: self.session_state,
transcript: self.transcript,
}
}
const fn write_base(&self) -> WriteBase<'a> {
WriteBase {
read: self.read_base(),
session_state: if self.requires_session_state {
self.session_state_writer
} else {
None
},
}
}
const fn control_base(&self) -> ControlBase<'a> {
ControlBase {
write: self.write_base(),
emitter: self.emitter,
}
}
const fn staged_base(&self, staged: &'a StagedTranscript) -> StagedBase<'a> {
StagedBase {
control: self.control_base(),
staged,
}
}
pub(crate) const fn prepare(
&self,
staged: &'a StagedTranscript,
session_state_stage: Option<&'a session_state::StagedWriter>,
base_snapshot: &'a Snapshot,
input: &'a [Part],
) -> PrepareScope<'a> {
PrepareScope {
base: PrepareBase {
read: self.read_base(),
session_state: if self.requires_session_state {
session_state_stage
} else {
None
},
},
staged,
base_snapshot,
input,
}
}
pub(crate) const fn compose_continuation(
&self,
staged: &'a StagedTranscript,
continuation: &'a [Part],
continuations: usize,
turns: usize,
) -> ContinuationScope<'a> {
ContinuationScope {
base: self.staged_base(staged),
continuation,
continuations,
turns,
}
}
pub(crate) const fn decide_stop(&self) -> StopDecisionScope<'a> {
StopDecisionScope {
base: self.control_base(),
}
}
pub(crate) const fn input_admit(
&self,
target: InputTarget,
items: &'a [Item],
) -> InputAdmitScope<'a> {
InputAdmitScope {
base: self.control_base(),
target,
items,
}
}
pub(crate) const fn turn(
&self,
staged: &'a StagedTranscript,
trigger: &'a [Item],
) -> TurnScope<'a> {
TurnScope {
base: self.staged_base(staged),
trigger,
}
}
pub(crate) const fn before_step<'scope>(
&'scope self,
staged: &'scope StagedTranscript,
model: &'scope Info,
plan: &'scope mut RequestPlan,
) -> BeforeStepScope<'scope> {
BeforeStepScope {
base: self.staged_base(staged),
model,
plan,
}
}
pub(crate) const fn after_step(
&self,
staged: &'a StagedTranscript,
snapshot: &'a Arc<StepSnapshot>,
) -> AfterStepScope<'a> {
AfterStepScope {
base: self.staged_base(staged),
snapshot,
}
}
pub(crate) const fn before_model(
&self,
snapshot: &'a Arc<StepSnapshot>,
request: &'a Request,
) -> BeforeModelScope<'a> {
BeforeModelScope {
base: self.control_base(),
snapshot,
request,
}
}
pub(crate) const fn after_model(
&self,
snapshot: &'a Arc<StepSnapshot>,
output: &'a Assistant,
generated: bool,
finish_reason: &'a str,
completion: CompletionReason,
) -> AfterModelScope<'a> {
AfterModelScope {
base: self.control_base(),
snapshot,
output,
generated,
finish_reason,
completion,
}
}
pub(crate) const fn tool_call(
&self,
snapshot: &'a Arc<StepSnapshot>,
call: &'a ToolCall,
) -> ToolCallScope<'a> {
ToolCallScope {
base: self.control_base(),
snapshot,
call,
}
}
pub(crate) const fn tool_result(
&self,
snapshot: &'a Arc<StepSnapshot>,
call: &'a ToolCall,
disposition: CallDisposition,
result: &'a ToolResult,
) -> ToolResultScope<'a> {
ToolResultScope {
base: self.control_base(),
snapshot,
call,
disposition,
result,
}
}
pub(crate) const fn after_tool_commit(
&self,
staged: &'a StagedTranscript,
snapshot: &'a Arc<StepSnapshot>,
result: &'a ToolResult,
) -> AfterToolCommitScope<'a> {
AfterToolCommitScope {
base: self.staged_base(staged),
snapshot,
result,
}
}
pub(crate) fn observer(&self, snapshot: Option<&'a Arc<StepSnapshot>>) -> ObserverScope<'_> {
ObserverScope {
base: self.read_base(),
snapshot,
audit_sink: &self.direct_audit,
}
}
pub(crate) const fn read(&self) -> ReadScope<'a> {
ReadScope {
base: self.read_base(),
}
}
}