///|
/// What a middleware is handed about the run it is taking part in: the agent's identity, the
/// thread it belongs to, the step it is on, and the state as of this node.
///
/// The state is a snapshot — a middleware that wants to change it returns updates, so every
/// change goes through the graph and lands in the checkpoint like a node's own write.
pub(all) struct RunContext {
name : String
model : String
thread : String
step : Int32
state : AgentState
/// The answer a resumed run was given, when the node is running again after an interrupt.
answer : Json?
/// The agent as built: provider, model, tool registry, the hooks. A middleware that needs to
/// call the model itself (a summariser, a tool selector) reaches it through here.
runtime : Runtime
/// The handover a tool asked for during this node, if any.
handover : @ref.Ref[String?]
/// Updates a middleware wants the node to write. The node returns them as steps once the
/// call it was wrapping has finished, so a hook can leave something in the state without a
/// second channel to the graph.
pending : Array[Update]
}
///|
/// One model call about to be made.
pub(all) struct ModelCall {
request : @moonmuse.Request
}
///|
/// What a model call came to. `Halted` is a middleware refusing to spend the call, carrying
/// the text the run ends with — the shape a call limit takes.
pub(all) enum ModelOutcome {
Replied(@moonmuse.Reply)
/// The call did not produce a reply. `retryable` is the provider's own judgement — a rate
/// limit or a gateway error is worth another attempt, a malformed request is not.
Failed(reason~ : String, retryable~ : Bool)
/// A middleware refused to spend the call; the run ends with this text as its answer.
Halted(String)
}
///|
/// One tool call about to be made.
pub(all) struct ToolCall {
part : @moonmuse.Part
}
///|
/// What a tool call came to. `Failed` records the reason as an error result, which is what the
/// model reads and what a retry policy looks at.
pub(all) enum ToolOutcome {
Done(String)
Failed(String)
/// The call cannot run until the run is answered: the node stops on this value, the answer
/// arrives on resumption, and the node runs again.
Suspend(Json)
}
///|
/// A hook into a run, between the graph and the provider.
///
/// Four places to act: before the run starts, around each model call, around each tool call,
/// and after the run ends. The around-hooks take the next step as a function, so a middleware
/// can retry it, replace it, or skip it — and the pipeline nesting is the composition order,
/// first registered outermost.
///
/// A middleware may also install tools, which is how a feature that is best expressed as
/// something the model calls (a todo list, a shell, a file search) joins a run.
pub(open) trait Middleware {
fn name(Self) -> String
fn install(Self, Tools) -> Unit
async fn before_agent(Self, RunContext) -> Array[Update]
async fn wrap_model(
Self,
RunContext,
ModelCall,
async (ModelCall) -> ModelOutcome,
) -> ModelOutcome
async fn wrap_tool(
Self,
RunContext,
ToolCall,
async (ToolCall) -> ToolOutcome,
) -> ToolOutcome
async fn after_agent(Self, RunContext, AgentState) -> Array[Update]
}
///|
/// A middleware that changes nothing, for a caller that wants one hook and no others.
pub struct Passthrough {
label : String
}
///|
/// A pass-through middleware under `name`.
pub fn Passthrough::new(name : String) -> Passthrough {
{ label: name, }
}
///|
/// The name it was built with.
pub fn Passthrough::name(self : Passthrough) -> String {
self.label
}
///|
pub extend Passthrough with Middleware::{
install,
before_agent,
wrap_model,
wrap_tool,
after_agent,
}
///|
pub impl Middleware for Passthrough with fn name(self) {
self.label
}
///|
pub impl Middleware for Passthrough with fn install(_self, _toolbox) {
()
}
///|
pub impl Middleware for Passthrough with fn before_agent(_self, _context) {
[]
}
///|
pub impl Middleware for Passthrough with fn wrap_model(
_self,
_context,
call,
next,
) {
next(call)
}
///|
pub impl Middleware for Passthrough with fn wrap_tool(
_self,
_context,
call,
next,
) {
next(call)
}
///|
pub impl Middleware for Passthrough with fn after_agent(_self, _context, _state) {
[]
}