update

src/type.jl

@@ -355,24 +355,32 @@ docstring
 mutable struct yiemAgent <: agent             # High-level agent wrapper
   _state::agentState                          # Current state (prompt, model, messages, tools, etc.)
   
-  inputChannel::Channel                       # user sends prompt message to agent. 
-                                              # if agent is idle, it process user message right away. 
-                                              # if agent is running, it process user message after 
-                                              # the current tool call finished.
-
-  followUpChannel::Channel                    # Buffers messages the user sends while the agent is busy.
-                                              # Processed after all inputChannel messages are handled
-                                              # and the agent is idle (not using a tool call).
-
-  outputChannel::Channel                      # agent sends response message to user after processing
-                                              # all user messages in inputChannel and all followUp messages.
+  # user sends prompt message to agent. if agent is idle, it process user message right away. 
+  # if agent is running, it process user message after  the current tool call finished.
+  inputChannel::Channel                        
+                                              
+  # Buffers messages the user sends while the agent is busy. Processed after all inputChannel 
+  # messages are handled and the agent is idle (not using a tool call).
+  followUpChannel::Channel                    
 
+  # agent sends response message to user after processing all user messages in inputChannel 
+  # and all followUp messages.
+  outputChannel::Channel                     
+                                              
   _task::Union{Task, Nothing}                 # Background task running the agent loop
 
   formatMsgForLLM::Function                   # Convert agent messages to LLM message format
-  preprocessMessages ::Union{Function, Nothing}  # Preprocess/transform messages before sending to LLM
-  beforeToolCall::Union{Function, Nothing}    # Callback invoked before executing a tool call
-  afterToolCall::Union{Function, Nothing}     # Callback invoked after executing a tool call
+
+  # Preprocess/transform messages and context (modify, filter, prune, inject, reorder, add context)
+  # for a single LLM call in _process_message()'s loop returns new Vector{agentMessage}
+  preprocessContext ::Union{Function, Nothing}   
+                                              
+  # Callback invoked before executing a tool call (ask for user permission/confirmation/abort, etc..)
+  beforeToolCall::Union{Function, Nothing}    
+  
+  # Callback invoked after executing a tool call to sanitize tools output so the output is ready 
+  # to be converted into toolResults message
+  afterToolCall::Union{Function, Nothing}     
   prepareNextTurn::Union{Function, Nothing}   # Callback to prepare the next conversation turn
   prepareNextTurnWithContext::Union{Function, Nothing}  # Same but receives context
   sessionId::Union{String, Nothing}           # Optional session identifier
@@ -392,7 +400,7 @@ on `inputChannel` and `followUpChannel` channels concurrently.
 - `tools::Vector{agentTool}`: Available tools (default: empty)
 - `messages::Vector{agentMessage}`: Initial conversation messages (default: empty)
 - `formatMsgForLLM::Function`: Convert agent messages to LLM message format (default: `defaultformatMsgForLLM`)
-- `preprocessMessages::Union{Function, Nothing}`: Preprocess/transform messages before sending to LLM (default: `nothing`)
+- `preprocessContext::Union{Function, Nothing}`: Preprocess/transform messages before sending to LLM (default: `nothing`)
 - `beforeToolCall::Union{Function, Nothing}`: Callback invoked before executing a tool call (default: `nothing`)
 - `afterToolCall::Union{Function, Nothing}`: Callback invoked after executing a tool call (default: `nothing`)
 - `prepareNextTurn::Union{Function, Nothing}`: Callback to prepare the next conversation turn (default: `nothing`)
@@ -416,7 +424,7 @@ function yiemAgent(
     tools::Vector{agentTool}=agentTool[],
     messages::Vector{agentMessage}=agentMessage[],
     formatMsgForLLM::Function=defaultformatMsgForLLM,
-    preprocessMessages::Union{Function, Nothing}=nothing,
+    preprocessContext::Union{Function, Nothing}=nothing,
     beforeToolCall::Union{Function, Nothing}=nothing,
     afterToolCall::Union{Function, Nothing}=nothing,
     prepareNextTurn::Union{Function, Nothing}=nothing,
@@ -438,7 +446,7 @@ function yiemAgent(
     outputChannel,
     nothing,  # placeholder — replaced below
     formatMsgForLLM,
-    preprocessMessages,
+    preprocessContext,
     beforeToolCall,
     afterToolCall,
     prepareNextTurn,