use rig_core::conversation::{Aside, Author};
use rig_core::message::CallId;
use rig_core::streaming::Part;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::{
any::{Any, TypeId},
collections::HashMap,
future::Future,
sync::Arc,
};
use rig_core::{
completion::FinishReason,
message::{AssistantContent, Message},
wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
};
use rig_core::{
completion::ModelRef,
effect::{Answered, EffectFamily, EffectId, EffectKind},
error::{ErrorKind, ErrorReport},
};
use crate::{
completion::{ResponseIdentity, Usage},
handlers::{Handle, Handlers, IndexHandle, ModelHandle, ToolHandle},
tool::{ToolContext, ToolOutput, ToolResult},
};
pub use rig_core::id::RunId;
#[derive(Clone, Default)]
pub struct Scratchpad {
inner: Arc<std::sync::Mutex<HashMap<TypeId, Box<dyn Entry>>>>,
}
trait Entry: Any + WasmCompatSend + WasmCompatSync {}
impl<T: Any + WasmCompatSend + WasmCompatSync> Entry for T {}
fn take<T: 'static>(entry: Box<dyn Entry>) -> Option<T> {
(entry as Box<dyn Any>).downcast().ok().map(|value| *value)
}
impl Scratchpad {
fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<TypeId, Box<dyn Entry>>> {
self.inner
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
pub fn insert<T>(&self, value: T) -> Option<T>
where
T: Clone + WasmCompatSend + WasmCompatSync + 'static,
{
self.lock()
.insert(TypeId::of::<T>(), Box::new(value))
.and_then(take)
}
pub fn get<T>(&self) -> Option<T>
where
T: Clone + WasmCompatSend + WasmCompatSync + 'static,
{
let entries = self.lock();
let entry = entries.get(&TypeId::of::<T>())?;
(&**entry as &dyn Any).downcast_ref::<T>().cloned()
}
pub fn contains<T>(&self) -> bool
where
T: WasmCompatSend + WasmCompatSync + 'static,
{
self.lock().contains_key(&TypeId::of::<T>())
}
pub fn remove<T>(&self) -> Option<T>
where
T: Clone + WasmCompatSend + WasmCompatSync + 'static,
{
self.lock().remove(&TypeId::of::<T>()).and_then(take)
}
pub fn update<T, R>(&self, update: impl FnOnce(&mut T) -> R) -> R
where
T: Clone + Default + WasmCompatSend + WasmCompatSync + 'static,
{
let mut value = self.remove::<T>().unwrap_or_default();
let result = update(&mut value);
self.insert(value);
result
}
}
impl std::fmt::Debug for Scratchpad {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Scratchpad")
.field("entries", &self.lock().len())
.finish()
}
}
#[derive(Debug)]
pub struct HookContext {
handlers: Handlers,
run_id: RunId,
turn: AtomicUsize,
is_streaming: bool,
agent_name: Option<String>,
scratchpad: Scratchpad,
salvaged_patches: std::sync::Mutex<HashMap<EffectId, EffectKind>>,
entries: std::sync::Mutex<Vec<Aside>>,
pending_entries: std::sync::Mutex<Vec<Aside>>,
}
impl HookContext {
pub(crate) fn new(is_streaming: bool, agent_name: Option<String>, handlers: Handlers) -> Self {
Self {
handlers,
run_id: RunId::new(),
turn: AtomicUsize::new(0),
is_streaming,
agent_name,
scratchpad: Scratchpad::default(),
salvaged_patches: std::sync::Mutex::new(HashMap::new()),
entries: std::sync::Mutex::new(Vec::new()),
pending_entries: std::sync::Mutex::new(Vec::new()),
}
}
fn salvage_patch(&self, id: EffectId, kind: EffectKind) {
self.salvaged_patches
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.entry(id)
.or_insert(kind);
}
pub(crate) fn take_salvaged_patch(&self, id: EffectId) -> Option<EffectKind> {
self.salvaged_patches
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.remove(&id)
}
pub(crate) fn seed_entries(&self, entries: &[Aside]) {
self.entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.extend_from_slice(entries);
}
pub(crate) fn drain_pending_entries(&self) -> Vec<Aside> {
std::mem::take(
&mut *self
.pending_entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner),
)
}
pub(crate) fn set_turn(&self, turn: usize) {
self.turn.store(turn, Ordering::Relaxed);
}
#[cfg(any(test, feature = "test-utils"))]
pub(crate) fn set_streaming(&mut self, is_streaming: bool) {
self.is_streaming = is_streaming;
}
#[cfg(any(test, feature = "test-utils"))]
pub(crate) fn set_agent_name(&mut self, name: String) {
self.agent_name = Some(name);
}
pub fn bind<F: rig_core::effect::Family>(
&self,
key: &rig_core::effect::Key<F>,
) -> Result<Handle<F>, ErrorReport> {
self.handlers.bind(key)
}
pub fn index(&self, key: &rig_core::effect::HandlerKey) -> Result<IndexHandle, ErrorReport> {
self.handlers.handle(key)
}
pub fn model(&self, key: &rig_core::effect::HandlerKey) -> Result<ModelHandle, ErrorReport> {
self.handlers.handle(key)
}
pub fn tool(&self, key: &rig_core::effect::HandlerKey) -> Result<ToolHandle, ErrorReport> {
self.handlers.handle(key)
}
pub fn run_id(&self) -> RunId {
self.run_id
}
pub fn turn(&self) -> usize {
self.turn.load(Ordering::Relaxed)
}
pub fn is_streaming(&self) -> bool {
self.is_streaming
}
pub fn agent_name(&self) -> Option<&str> {
self.agent_name.as_deref()
}
pub fn scratchpad(&self) -> &Scratchpad {
&self.scratchpad
}
pub fn append_entry<T: serde::Serialize>(
&self,
kind: impl Into<String>,
value: &T,
) -> Result<(), serde_json::Error> {
let entry = Aside::new(kind, Author::rig(), serde_json::to_value(value)?);
self.entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(entry.clone());
self.pending_entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(entry);
Ok(())
}
pub fn entries(&self, kind: &str) -> Vec<Aside> {
self.entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.iter()
.filter(|entry| entry.kind == kind)
.cloned()
.collect()
}
pub fn last_entry(&self, kind: &str) -> Option<Aside> {
self.entries
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.iter()
.rev()
.find(|entry| entry.kind == kind)
.cloned()
}
}
pub use crate::run::policy::{
InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest,
};
#[derive(Clone, Copy)]
pub struct CompletionCallEvent<'a> {
pub prompt: &'a Message,
pub history: &'a [Arc<Message>],
pub turn: usize,
}
#[derive(Clone, Copy)]
pub struct ModelSelection<'a> {
pub prompt: &'a Message,
pub history: &'a [Arc<Message>],
pub request_patch: Option<&'a RequestPatch>,
pub previous_model: Option<&'a ModelRef>,
pub default_model: &'a ModelRef,
pub selected_model: &'a ModelRef,
}
impl<'a> ModelSelection<'a> {
pub fn new(
prompt: &'a Message,
history: &'a [Arc<Message>],
request_patch: Option<&'a RequestPatch>,
previous_model: Option<&'a ModelRef>,
default_model: &'a ModelRef,
selected_model: &'a ModelRef,
) -> Self {
Self {
prompt,
history,
request_patch,
previous_model,
default_model,
selected_model,
}
}
}
#[derive(Clone, Copy)]
pub struct ModelTurnFinished<'a> {
pub turn: usize,
pub content: &'a Vec<AssistantContent>,
pub usage: Usage,
pub identity: &'a ResponseIdentity,
pub finish_reason: Option<&'a FinishReason>,
pub max_tokens: Option<u64>,
pub raw: &'a serde_json::Value,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ModelTurnAction {
Continue,
Retry(RetryRequest),
Stop(String),
}
impl ModelTurnAction {
pub fn continue_run() -> Self {
Self::Continue
}
pub fn repeat() -> Self {
Self::Retry(RetryRequest::Repeat)
}
pub fn retry_with_feedback(feedback: impl Into<String>) -> Self {
Self::Retry(RetryRequest::Feedback(feedback.into()))
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop(reason.into())
}
}
#[derive(Clone, Copy)]
pub struct TextDelta<'a> {
pub delta: &'a str,
pub aggregated: &'a str,
}
#[derive(Clone, Copy)]
pub struct ReasoningDelta<'a> {
pub part: Part,
pub delta: &'a str,
pub aggregated: &'a str,
}
#[derive(Clone, Copy)]
pub struct ToolCallDelta<'a> {
pub part: Part,
pub tool_name: &'a str,
pub delta: &'a str,
pub aggregated: &'a str,
}
#[derive(Clone, Copy)]
pub struct RunStart<'a> {
pub prompt: &'a Message,
pub history: &'a [Arc<Message>],
}
#[derive(Debug, Clone, PartialEq)]
pub enum RunStartAction {
Continue,
Rewrite(Message),
Stop(String),
}
impl RunStartAction {
pub fn continue_run() -> Self {
Self::Continue
}
pub fn rewrite(prompt: impl Into<Message>) -> Self {
Self::Rewrite(prompt.into())
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop(reason.into())
}
}
#[derive(Clone, Copy)]
pub struct RunSettled<'a> {
pub outcome: SettledOutcome<'a>,
pub messages: Option<&'a [Arc<Message>]>,
}
#[derive(Clone, Copy)]
pub enum SettledOutcome<'a> {
Response(&'a crate::run::response::PromptResponse),
Error(&'a str),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum StepEventKind {
RunStart,
RunSettled,
CompletionCall,
ModelTurnFinished,
InvalidToolCall,
TextDelta,
ReasoningDelta,
ToolCallDelta,
CompletionDispatch,
ToolDispatch,
EmbedDispatch,
RerankDispatch,
RetrieveDispatch,
CustomDispatch,
}
impl StepEventKind {
pub const fn for_family(family: EffectFamily) -> Self {
match family {
EffectFamily::Completion => Self::CompletionDispatch,
EffectFamily::Tool => Self::ToolDispatch,
EffectFamily::Embed => Self::EmbedDispatch,
EffectFamily::Rerank => Self::RerankDispatch,
EffectFamily::Retrieve => Self::RetrieveDispatch,
EffectFamily::Custom => Self::CustomDispatch,
}
}
}
#[derive(Clone, Copy)]
pub struct DispatchEvent<'a> {
pub id: EffectId,
pub kind: &'a EffectKind,
pub turn: usize,
pub call_id: Option<&'a CallId>,
pub context: Option<&'a ToolContext>,
}
#[derive(Debug, Clone)]
pub enum DispatchAction {
Proceed,
Patch(EffectKind),
Deny(ErrorReport),
}
pub(crate) fn validate_dispatch_patch(
current: &EffectKind,
next: &EffectKind,
) -> Result<(), ErrorReport> {
if current.family() != next.family() {
return Err(ErrorReport::new(
ErrorKind::Internal,
format!(
"a hook patched a {} dispatch into a `{}` effect",
current.name(),
next.name()
),
));
}
if let (EffectKind::ToolCall { name: current, .. }, EffectKind::ToolCall { name: next, .. }) =
(current, next)
&& current != next
{
return Err(ErrorReport::new(
ErrorKind::Other,
"a dispatch patch cannot change the tool target",
));
}
Ok(())
}
impl DispatchAction {
pub fn proceed() -> Self {
Self::Proceed
}
pub fn patch(kind: EffectKind) -> Self {
Self::Patch(kind)
}
pub fn deny(report: ErrorReport) -> Self {
Self::Deny(report)
}
pub fn skip(reason: impl Into<String>) -> Self {
Self::Deny(ErrorReport::new(ErrorKind::Other, reason))
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Deny(ErrorReport::new(ErrorKind::Cancelled, reason))
}
pub fn rewrite_tool_args(kind: &EffectKind, args: impl Into<serde_json::Value>) -> Self {
match kind {
EffectKind::ToolCall { name, .. } => Self::Patch(EffectKind::ToolCall {
name: name.clone(),
args: Into::<serde_json::Value>::into(args).to_string(),
}),
_ => Self::Proceed,
}
}
}
impl<'a> DispatchEvent<'a> {
pub fn tool_name(&self) -> Option<&'a str> {
match self.kind {
EffectKind::ToolCall { name, .. } => Some(name),
_ => None,
}
}
pub fn tool_args(&self) -> Option<&'a str> {
match self.kind {
EffectKind::ToolCall { args, .. } => Some(args),
_ => None,
}
}
pub fn tool_context(&self) -> Option<&'a ToolContext> {
self.context
}
pub fn completion_request(&self) -> Option<&'a rig_core::completion::CompletionRequest> {
match self.kind {
EffectKind::Completion { request, .. } => Some(request),
_ => None,
}
}
}
#[derive(Clone, Copy)]
pub struct OutcomeEvent<'a> {
pub id: EffectId,
pub kind: &'a EffectKind,
pub outcome: &'a Result<Answered, ErrorReport>,
pub turn: usize,
pub call_id: Option<&'a CallId>,
pub context: Option<&'a ToolContext>,
}
#[derive(Debug, Clone)]
pub enum OutcomeAction {
Proceed,
Replace(Result<Answered, ErrorReport>),
}
impl OutcomeAction {
pub fn proceed() -> Self {
Self::Proceed
}
pub fn replace(outcome: Result<Answered, ErrorReport>) -> Self {
Self::Replace(outcome)
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Replace(Err(ErrorReport::new(ErrorKind::Cancelled, reason)))
}
pub fn rewrite_tool_output(event: &OutcomeEvent<'_>, output: ToolOutput) -> Self {
match event.outcome {
Ok(Answered::ToolResult { result }) => Self::Replace(Ok(Answered::ToolResult {
result: result.clone().with_output(output),
})),
_ => Self::Proceed,
}
}
pub fn rewrite_tool_result(event: &OutcomeEvent<'_>, text: impl Into<String>) -> Self {
Self::rewrite_tool_output(event, ToolOutput::text(text))
}
}
impl<'a> OutcomeEvent<'a> {
pub fn tool_result(&self) -> Option<&'a ToolResult> {
match self.outcome {
Ok(Answered::ToolResult { result, .. }) => Some(result),
_ => None,
}
}
pub fn tool_context(&self) -> Option<&'a ToolContext> {
self.context
}
pub fn completion(&self) -> Option<&'a rig_core::completion::CompletionResponse> {
match self.outcome {
Ok(Answered::Completion(response)) => Some(response),
_ => None,
}
}
pub fn tool_name(&self) -> Option<&'a str> {
match self.kind {
EffectKind::ToolCall { name, .. } => Some(name),
_ => None,
}
}
pub fn tool_args(&self) -> Option<&'a str> {
match self.kind {
EffectKind::ToolCall { args, .. } => Some(args),
_ => None,
}
}
}
pub use crate::run::patch::RequestPatch;
#[derive(Debug, Clone)]
pub enum ModelSelectionAction {
Continue,
Select(ModelRef),
Stop(String),
}
impl ModelSelectionAction {
pub fn continue_run() -> Self {
Self::Continue
}
pub fn select(model: impl Into<ModelRef>) -> Self {
Self::Select(model.into())
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop(reason.into())
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum CompletionCallAction {
Continue,
Patch(RequestPatch),
Stop(String),
}
impl CompletionCallAction {
pub fn continue_run() -> Self {
Self::Continue
}
pub fn patch(patch: RequestPatch) -> Self {
Self::Patch(patch)
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop(reason.into())
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ObservationAction {
Continue,
Stop(String),
}
impl ObservationAction {
pub fn continue_run() -> Self {
Self::Continue
}
pub fn stop(reason: impl Into<String>) -> Self {
Self::Stop(reason.into())
}
}
pub trait AgentHook: WasmCompatSend + WasmCompatSync {
fn name(&self) -> Option<String> {
None
}
fn on_run_start(
&self,
_ctx: &HookContext,
_event: RunStart<'_>,
) -> impl Future<Output = RunStartAction> + WasmCompatSend {
async { RunStartAction::Continue }
}
fn on_run_settled(
&self,
_ctx: &HookContext,
_event: RunSettled<'_>,
) -> impl Future<Output = ()> + WasmCompatSend {
async {}
}
fn on_model_select(
&self,
_ctx: &HookContext,
_event: ModelSelection<'_>,
) -> ModelSelectionAction {
ModelSelectionAction::Continue
}
fn on_completion_call(
&self,
_ctx: &HookContext,
_event: CompletionCallEvent<'_>,
) -> impl Future<Output = CompletionCallAction> + WasmCompatSend {
async { CompletionCallAction::Continue }
}
fn on_model_turn_finished(
&self,
_ctx: &HookContext,
_event: ModelTurnFinished<'_>,
) -> impl Future<Output = ModelTurnAction> + WasmCompatSend {
async { ModelTurnAction::Continue }
}
fn on_invalid_tool_call(
&self,
_ctx: &HookContext,
_event: &InvalidToolCallContext,
) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend {
async { None }
}
fn on_text_delta(
&self,
_ctx: &HookContext,
_event: TextDelta<'_>,
) -> impl Future<Output = ObservationAction> + WasmCompatSend {
async { ObservationAction::Continue }
}
fn on_reasoning_delta(
&self,
_ctx: &HookContext,
_event: ReasoningDelta<'_>,
) -> impl Future<Output = ObservationAction> + WasmCompatSend {
async { ObservationAction::Continue }
}
fn on_tool_call_delta(
&self,
_ctx: &HookContext,
_event: ToolCallDelta<'_>,
) -> impl Future<Output = ObservationAction> + WasmCompatSend {
async { ObservationAction::Continue }
}
fn on_dispatch(
&self,
_ctx: &HookContext,
_event: DispatchEvent<'_>,
) -> impl Future<Output = DispatchAction> + WasmCompatSend {
async { DispatchAction::Proceed }
}
fn on_outcome(
&self,
_ctx: &HookContext,
_event: OutcomeEvent<'_>,
) -> impl Future<Output = OutcomeAction> + WasmCompatSend {
async { OutcomeAction::Proceed }
}
fn observes(&self, kind: StepEventKind) -> bool {
!matches!(
kind,
StepEventKind::EmbedDispatch
| StepEventKind::RerankDispatch
| StepEventKind::RetrieveDispatch
| StepEventKind::CustomDispatch
)
}
}
impl AgentHook for () {
fn observes(&self, _kind: StepEventKind) -> bool {
false
}
}
macro_rules! for_each_boxed_hook_event {
($m:ident) => {
$m!(
completion_call,
on_completion_call,
CompletionCallEvent,
CompletionCallAction
);
$m!(
model_turn_finished,
on_model_turn_finished,
ModelTurnFinished,
ModelTurnAction
);
$m!(text_delta, on_text_delta, TextDelta, ObservationAction);
$m!(
reasoning_delta,
on_reasoning_delta,
ReasoningDelta,
ObservationAction
);
$m!(
tool_call_delta,
on_tool_call_delta,
ToolCallDelta,
ObservationAction
);
};
}
macro_rules! erased_hook_decl {
($erased:ident, $on:ident, $event:ident, $action:ident) => {
fn $erased<'a>(
&'a self,
ctx: &'a HookContext,
event: $event<'a>,
) -> WasmBoxedFuture<'a, $action>;
};
}
macro_rules! erased_hook_forward {
($erased:ident, $on:ident, $event:ident, $action:ident) => {
fn $erased<'a>(
&'a self,
ctx: &'a HookContext,
event: $event<'a>,
) -> WasmBoxedFuture<'a, $action> {
Box::pin(self.$on(ctx, event))
}
};
}
trait DynAgentHook: WasmCompatSend + WasmCompatSync {
fn run_start<'a>(
&'a self,
ctx: &'a HookContext,
event: RunStart<'a>,
) -> WasmBoxedFuture<'a, RunStartAction>;
fn run_settled<'a>(
&'a self,
ctx: &'a HookContext,
event: RunSettled<'a>,
) -> WasmBoxedFuture<'a, ()>;
fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction;
fn invalid_tool_call<'a>(
&'a self,
ctx: &'a HookContext,
event: &'a InvalidToolCallContext,
) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>>;
fn dispatch<'a>(
&'a self,
ctx: &'a HookContext,
event: DispatchEvent<'a>,
) -> WasmBoxedFuture<'a, DispatchAction>;
fn outcome<'a>(
&'a self,
ctx: &'a HookContext,
event: OutcomeEvent<'a>,
) -> WasmBoxedFuture<'a, OutcomeAction>;
for_each_boxed_hook_event!(erased_hook_decl);
fn observes(&self, kind: StepEventKind) -> bool;
}
impl<H> DynAgentHook for H
where
H: AgentHook,
{
fn run_start<'a>(
&'a self,
ctx: &'a HookContext,
event: RunStart<'a>,
) -> WasmBoxedFuture<'a, RunStartAction> {
Box::pin(self.on_run_start(ctx, event))
}
fn run_settled<'a>(
&'a self,
ctx: &'a HookContext,
event: RunSettled<'a>,
) -> WasmBoxedFuture<'a, ()> {
Box::pin(self.on_run_settled(ctx, event))
}
fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction {
self.on_model_select(ctx, event)
}
fn invalid_tool_call<'a>(
&'a self,
ctx: &'a HookContext,
event: &'a InvalidToolCallContext,
) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>> {
Box::pin(self.on_invalid_tool_call(ctx, event))
}
fn dispatch<'a>(
&'a self,
ctx: &'a HookContext,
event: DispatchEvent<'a>,
) -> WasmBoxedFuture<'a, DispatchAction> {
Box::pin(self.on_dispatch(ctx, event))
}
fn outcome<'a>(
&'a self,
ctx: &'a HookContext,
event: OutcomeEvent<'a>,
) -> WasmBoxedFuture<'a, OutcomeAction> {
Box::pin(self.on_outcome(ctx, event))
}
for_each_boxed_hook_event!(erased_hook_forward);
fn observes(&self, kind: StepEventKind) -> bool {
AgentHook::observes(self, kind)
}
}
#[derive(Clone, Default)]
pub struct HookStack {
hooks: Vec<Arc<dyn DynAgentHook>>,
names: Vec<String>,
}
impl std::fmt::Debug for HookStack {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("HookStack")
.field("len", &self.hooks.len())
.finish()
}
}
fn short_type_name<H>() -> &'static str {
let full = std::any::type_name::<H>();
let generics = full.find('<').unwrap_or(full.len());
let path = &full[..generics];
match path.rfind("::") {
Some(at) => &full[at + 2..],
None => full,
}
}
impl HookStack {
pub fn new() -> Self {
Self::default()
}
pub fn with<H: AgentHook + 'static>(hook: H) -> Self {
let mut stack = Self::new();
stack.push(hook);
stack
}
pub fn push<H: AgentHook + 'static>(&mut self, hook: H) {
match (&hook as &dyn std::any::Any).downcast_ref::<HookStack>() {
Some(nested) => self.names.extend(nested.names.iter().cloned()),
None => self.names.push(
hook.name()
.unwrap_or_else(|| short_type_name::<H>().to_owned()),
),
}
self.hooks.push(Arc::new(hook));
}
pub fn names(&self) -> Vec<String> {
self.names.clone()
}
pub fn is_empty(&self) -> bool {
self.hooks.is_empty()
}
pub fn len(&self) -> usize {
self.hooks.len()
}
}
trait ShortCircuitAction: Sized {
const CONTINUE: Self;
fn is_continue(&self) -> bool;
}
impl ShortCircuitAction for ObservationAction {
const CONTINUE: Self = ObservationAction::Continue;
fn is_continue(&self) -> bool {
matches!(self, ObservationAction::Continue)
}
}
impl ShortCircuitAction for ModelTurnAction {
const CONTINUE: Self = ModelTurnAction::Continue;
fn is_continue(&self) -> bool {
matches!(self, ModelTurnAction::Continue)
}
}
async fn first_non_continue<'a, A, F>(hooks: &'a [Arc<dyn DynAgentHook>], mut dispatch: F) -> A
where
A: ShortCircuitAction,
F: FnMut(&'a dyn DynAgentHook) -> WasmBoxedFuture<'a, A>,
{
for hook in hooks {
let action = dispatch(hook.as_ref()).await;
if !action.is_continue() {
return action;
}
}
A::CONTINUE
}
macro_rules! stack_first_non_continue {
($($on:ident, $erased:ident, $event:ident, $action:ident;)+) => {
$(
async fn $on(&self, ctx: &HookContext, event: $event<'_>) -> $action {
first_non_continue(&self.hooks, |hook| hook.$erased(ctx, event)).await
}
)+
};
}
impl AgentHook for HookStack {
async fn on_run_start(&self, ctx: &HookContext, event: RunStart<'_>) -> RunStartAction {
let mut rewritten: Option<Message> = None;
for hook in &self.hooks {
let current = RunStart {
prompt: rewritten.as_ref().unwrap_or(event.prompt),
..event
};
match hook.run_start(ctx, current).await {
RunStartAction::Continue => {}
RunStartAction::Rewrite(prompt) => rewritten = Some(prompt),
stop @ RunStartAction::Stop(_) => return stop,
}
}
rewritten.map_or(RunStartAction::Continue, RunStartAction::Rewrite)
}
async fn on_run_settled(&self, ctx: &HookContext, event: RunSettled<'_>) {
for hook in &self.hooks {
hook.run_settled(ctx, event).await;
}
}
fn on_model_select(
&self,
ctx: &HookContext,
event: ModelSelection<'_>,
) -> ModelSelectionAction {
let mut selected = None;
for hook in &self.hooks {
let action = {
let selected_model = selected.as_ref().unwrap_or(event.selected_model);
hook.model_select(
ctx,
ModelSelection {
selected_model,
..event
},
)
};
match action {
ModelSelectionAction::Continue => {}
ModelSelectionAction::Select(model) => selected = Some(model),
stop @ ModelSelectionAction::Stop(_) => return stop,
}
}
selected.map_or(ModelSelectionAction::Continue, ModelSelectionAction::Select)
}
async fn on_completion_call(
&self,
ctx: &HookContext,
event: CompletionCallEvent<'_>,
) -> CompletionCallAction {
let mut merged: Option<RequestPatch> = None;
for hook in &self.hooks {
match hook.completion_call(ctx, event).await {
CompletionCallAction::Continue => {}
CompletionCallAction::Patch(patch) => {
merged = Some(match merged {
None => patch,
Some(value) => value.merge(patch),
});
}
stop @ CompletionCallAction::Stop(_) => return stop,
}
}
match merged {
Some(patch) if !patch.is_empty() => CompletionCallAction::Patch(patch),
_ => CompletionCallAction::Continue,
}
}
stack_first_non_continue! {
on_model_turn_finished, model_turn_finished, ModelTurnFinished, ModelTurnAction;
on_text_delta, text_delta, TextDelta, ObservationAction;
on_reasoning_delta, reasoning_delta, ReasoningDelta, ObservationAction;
on_tool_call_delta, tool_call_delta, ToolCallDelta, ObservationAction;
}
async fn on_invalid_tool_call(
&self,
ctx: &HookContext,
event: &InvalidToolCallContext,
) -> Option<InvalidToolCallAction> {
for hook in &self.hooks {
if let Some(action) = hook.invalid_tool_call(ctx, event).await {
return Some(action);
}
}
None
}
async fn on_dispatch(&self, ctx: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
let kind = StepEventKind::for_family(event.kind.family());
let mut patched: Option<EffectKind> = None;
for hook in &self.hooks {
if !hook.observes(kind) {
continue;
}
let current = DispatchEvent {
kind: patched.as_ref().unwrap_or(event.kind),
..event
};
match hook.dispatch(ctx, current).await {
DispatchAction::Proceed => {}
DispatchAction::Patch(next) => {
if let Err(report) = validate_dispatch_patch(current.kind, &next) {
if let Some(kind) = patched {
ctx.salvage_patch(event.id, kind);
}
return DispatchAction::Deny(report);
}
patched = Some(next);
}
deny @ DispatchAction::Deny(_) => {
if let Some(kind) = patched {
ctx.salvage_patch(event.id, kind);
}
return deny;
}
}
}
patched.map_or(DispatchAction::Proceed, DispatchAction::Patch)
}
async fn on_outcome(&self, ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
let kind = StepEventKind::for_family(event.kind.family());
let mut replaced: Option<Result<Answered, ErrorReport>> = None;
for hook in &self.hooks {
if !hook.observes(kind) {
continue;
}
let current = OutcomeEvent {
outcome: replaced.as_ref().unwrap_or(event.outcome),
..event
};
match hook.outcome(ctx, current).await {
OutcomeAction::Proceed => {}
OutcomeAction::Replace(next) => {
if matches!(&next, Err(report) if report.kind == ErrorKind::Cancelled) {
return OutcomeAction::Replace(next);
}
replaced = Some(next);
}
}
}
replaced.map_or(OutcomeAction::Proceed, OutcomeAction::Replace)
}
fn observes(&self, kind: StepEventKind) -> bool {
self.hooks.iter().any(|hook| hook.observes(kind))
}
}
#[cfg(test)]
mod tests;