///|
/// What a run broadcasts: one variant per boundary worth observing. The stream is data so it
/// can be rendered as log lines, counted in tests, or translated into OpenTelemetry spans
/// without the observer reaching into the graph.
pub(all) enum Event {
AgentStarted(name~ : String)
AgentFinished(name~ : String, text~ : String)
AgentFailed(name~ : String, reason~ : String)
ModelStarted(name~ : String, model~ : String)
ModelFinished(name~ : String, usage~ : @moonmuse.Usage)
ToolStarted(name~ : String, call_id~ : String)
ToolFinished(name~ : String, call_id~ : String, failed~ : Bool)
HandedOver(from~ : String, to~ : String)
NodeStarted(name~ : String)
NodeFinished(name~ : String)
}
///|
/// The subscriber a run reports to. Every run has one; the default drops what it is told.
pub type Listener = (Event) -> Unit
///|
/// Hooks over an agent run: observers that watch, and interceptors that rewrite the value in
/// flight. Every registration chains after what was registered before, so several handlers
/// fire and several interceptors compose left to right.
///
/// The interceptors are the only way to change what is sent, what comes back and what a tool
/// receives, which keeps a run's conversation and a hook's edits in one place. Hooks are
/// synchronous; anything that has to await belongs in middleware, whose hooks are async.
pub struct EventHandler {
mut listener : Listener
mut on_agent_starting : (String) -> Unit
mut on_agent_completed : (String) -> Unit
mut on_agent_execution_failed : (String) -> Unit
mut on_strategy_starting : (String) -> Unit
mut on_strategy_completed : (String, String) -> Unit
mut on_llm_call_starting : (@moonmuse.Request) -> @moonmuse.Request
mut on_llm_call_completed : (@moonmuse.Reply) -> @moonmuse.Reply
mut on_llm_streaming_starting : (@moonmuse.Request) -> Unit
mut on_llm_streaming_frame : (String) -> Unit
mut on_llm_streaming_completed : (@moonmuse.Reply) -> Unit
mut on_tool_call_starting : (String, Json) -> Json
mut on_tool_call_completed : (String, String) -> String
mut on_tool_call_failed : (String, String) -> Unit
mut on_tool_validation_failed : (String, Json, String) -> Unit
mut on_node_execution_starting : (String) -> Unit
mut on_node_execution_completed : (String) -> Unit
mut on_node_execution_failed : (String, String) -> Unit
mut on_subgraph_execution_starting : (String) -> Unit
mut on_subgraph_execution_completed : (String, String) -> Unit
}
///|
/// A handler with every observer a no-op and every interceptor the identity.
pub fn EventHandler::new() -> EventHandler {
{
listener: _event => (),
on_agent_starting: _name => (),
on_agent_completed: _text => (),
on_agent_execution_failed: _reason => (),
on_strategy_starting: _strategy => (),
on_strategy_completed: (_strategy, _text) => (),
on_llm_call_starting: request => request,
on_llm_call_completed: reply => reply,
on_llm_streaming_starting: _request => (),
on_llm_streaming_frame: _chunk => (),
on_llm_streaming_completed: _reply => (),
on_tool_call_starting: (_tool, args) => args,
on_tool_call_completed: (_tool, content) => content,
on_tool_call_failed: (_tool, _reason) => (),
on_tool_validation_failed: (_tool, _args, _reason) => (),
on_node_execution_starting: _node => (),
on_node_execution_completed: _node => (),
on_node_execution_failed: (_node, _reason) => (),
on_subgraph_execution_starting: _name => (),
on_subgraph_execution_completed: (_name, _text) => (),
}
}
///|
/// Subscribe to the run's event stream. Chains.
pub fn EventHandler::observe(
self : EventHandler,
listener : (Event) -> Unit,
) -> EventHandler {
let previous = self.listener
self.listener = event => {
previous(event)
listener(event)
}
self
}
///|
/// Report one event to the subscriber.
pub fn EventHandler::report(self : EventHandler, event : Event) -> Unit {
(self.listener)(event)
}
///|
/// Observe the agent starting, with the text it was given. Chains.
pub fn EventHandler::on_agent_starting(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_agent_starting
self.on_agent_starting = name => {
previous(name)
handler(name)
}
self
}
///|
/// Observe the agent completing, with its answer. Chains.
pub fn EventHandler::on_agent_completed(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_agent_completed
self.on_agent_completed = text => {
previous(text)
handler(text)
}
self
}
///|
/// Observe a run ending without an answer, with the reason. Chains.
pub fn EventHandler::on_agent_execution_failed(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_agent_execution_failed
self.on_agent_execution_failed = reason => {
previous(reason)
handler(reason)
}
self
}
///|
/// Observe the strategy starting, by name. Chains.
pub fn EventHandler::on_strategy_starting(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_strategy_starting
self.on_strategy_starting = strategy => {
previous(strategy)
handler(strategy)
}
self
}
///|
/// Observe the strategy completing, with its name and the answer. Chains.
pub fn EventHandler::on_strategy_completed(
self : EventHandler,
handler : (String, String) -> Unit,
) -> EventHandler {
let previous = self.on_strategy_completed
self.on_strategy_completed = (strategy, text) => {
previous(strategy, text)
handler(strategy, text)
}
self
}
///|
/// Rewrite a request just before it is sent: what comes back is what the provider receives,
/// while the conversation the run keeps is untouched. Chains.
pub fn EventHandler::intercept_llm_call_starting(
self : EventHandler,
handler : (@moonmuse.Request) -> @moonmuse.Request,
) -> EventHandler {
let previous = self.on_llm_call_starting
self.on_llm_call_starting = request => handler(previous(request))
self
}
///|
/// Observe each request just before it is sent, as the interceptors left it. Chains, and
/// changes nothing in flight.
pub fn EventHandler::on_llm_call_starting(
self : EventHandler,
handler : (@moonmuse.Request) -> Unit,
) -> EventHandler {
self.intercept_llm_call_starting(request => {
handler(request)
request
})
}
///|
/// Rewrite a reply: what comes back is what the graph routes on and what the conversation
/// records. Chains.
pub fn EventHandler::intercept_llm_call_completed(
self : EventHandler,
handler : (@moonmuse.Reply) -> @moonmuse.Reply,
) -> EventHandler {
let previous = self.on_llm_call_completed
self.on_llm_call_completed = reply => handler(previous(reply))
self
}
///|
/// Observe each reply. Chains, and changes nothing in flight.
pub fn EventHandler::on_llm_call_completed(
self : EventHandler,
handler : (@moonmuse.Reply) -> Unit,
) -> EventHandler {
self.intercept_llm_call_completed(reply => {
handler(reply)
reply
})
}
///|
/// Observe a streamed request starting. Chains.
pub fn EventHandler::on_llm_streaming_starting(
self : EventHandler,
handler : (@moonmuse.Request) -> Unit,
) -> EventHandler {
let previous = self.on_llm_streaming_starting
self.on_llm_streaming_starting = request => {
previous(request)
handler(request)
}
self
}
///|
/// Observe each text delta off a streamed reply. Chains.
pub fn EventHandler::on_llm_streaming_frame(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_llm_streaming_frame
self.on_llm_streaming_frame = chunk => {
previous(chunk)
handler(chunk)
}
self
}
///|
/// Observe a streamed reply once the stream ended. Chains.
pub fn EventHandler::on_llm_streaming_completed(
self : EventHandler,
handler : (@moonmuse.Reply) -> Unit,
) -> EventHandler {
let previous = self.on_llm_streaming_completed
self.on_llm_streaming_completed = reply => {
previous(reply)
handler(reply)
}
self
}
///|
/// Rewrite a tool call's arguments before the tool runs. Chains.
pub fn EventHandler::intercept_tool_call_starting(
self : EventHandler,
handler : (String, Json) -> Json,
) -> EventHandler {
let previous = self.on_tool_call_starting
self.on_tool_call_starting = (tool, args) => {
handler(tool, previous(tool, args))
}
self
}
///|
/// Observe each tool call before it runs. Chains, and changes nothing in flight.
pub fn EventHandler::on_tool_call_starting(
self : EventHandler,
handler : (String, Json) -> Unit,
) -> EventHandler {
self.intercept_tool_call_starting((tool, args) => {
handler(tool, args)
args
})
}
///|
/// Rewrite a tool's result — where a long output is truncated or a secret redacted before the
/// model reads it. Chains.
pub fn EventHandler::intercept_tool_call_completed(
self : EventHandler,
handler : (String, String) -> String,
) -> EventHandler {
let previous = self.on_tool_call_completed
self.on_tool_call_completed = (tool, content) => {
handler(tool, previous(tool, content))
}
self
}
///|
/// Observe each tool result. Chains, and changes nothing in flight.
pub fn EventHandler::on_tool_call_completed(
self : EventHandler,
handler : (String, String) -> Unit,
) -> EventHandler {
self.intercept_tool_call_completed((tool, content) => {
handler(tool, content)
content
})
}
///|
/// Observe a call that produced no result — the tool raised, or the model named one that does
/// not exist — with the reason that goes back to the model. Chains.
pub fn EventHandler::on_tool_call_failed(
self : EventHandler,
handler : (String, String) -> Unit,
) -> EventHandler {
let previous = self.on_tool_call_failed
self.on_tool_call_failed = (tool, reason) => {
previous(tool, reason)
handler(tool, reason)
}
self
}
///|
/// Observe arguments rejected before the tool ran. Chains.
pub fn EventHandler::on_tool_validation_failed(
self : EventHandler,
handler : (String, Json, String) -> Unit,
) -> EventHandler {
let previous = self.on_tool_validation_failed
self.on_tool_validation_failed = (tool, args, reason) => {
previous(tool, args, reason)
handler(tool, args, reason)
}
self
}
///|
/// Observe each node before it runs. Chains.
pub fn EventHandler::on_node_execution_starting(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_node_execution_starting
self.on_node_execution_starting = node => {
previous(node)
handler(node)
}
self
}
///|
/// Observe each node after it runs. Chains.
pub fn EventHandler::on_node_execution_completed(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_node_execution_completed
self.on_node_execution_completed = node => {
previous(node)
handler(node)
}
self
}
///|
/// Observe a node that raised; the error still ends the run. Chains.
pub fn EventHandler::on_node_execution_failed(
self : EventHandler,
handler : (String, String) -> Unit,
) -> EventHandler {
let previous = self.on_node_execution_failed
self.on_node_execution_failed = (node, reason) => {
previous(node, reason)
handler(node, reason)
}
self
}
///|
/// Observe a nested strategy before it is walked. Chains.
pub fn EventHandler::on_subgraph_execution_starting(
self : EventHandler,
handler : (String) -> Unit,
) -> EventHandler {
let previous = self.on_subgraph_execution_starting
self.on_subgraph_execution_starting = name => {
previous(name)
handler(name)
}
self
}
///|
/// Observe a nested strategy after it finished, with its answer. Chains.
pub fn EventHandler::on_subgraph_execution_completed(
self : EventHandler,
handler : (String, String) -> Unit,
) -> EventHandler {
let previous = self.on_subgraph_execution_completed
self.on_subgraph_execution_completed = (name, text) => {
previous(name, text)
handler(name, text)
}
self
}