praxo-core-0.7.0: src/Praxo/Agent.hs
module Praxo.Agent (AgentError(..), ToolCall(..), Action(..), Interrupt(..), InterruptDecision(..), InterruptHandler, InterruptApproval, interruptApprove, interruptEdit, interruptReject, interruptRespond, Message(..), Response(..), AgentOptions(..), RunResult(..), runAgent) where
import Data.Maybe (isNothing)
import Praxo.Json (Json(..), encodeJson)
interruptApprove :: String
interruptApprove = "approve"
interruptEdit :: String
interruptEdit = "edit"
interruptReject :: String
interruptReject = "reject"
interruptRespond :: String
interruptRespond = "respond"
data AgentError = AgentError { errorCode :: String, errorMessage :: String } deriving (Eq, Show)
data ToolCall = ToolCall { toolCallId :: String, toolCallName :: String, toolCallArguments :: Json } deriving (Eq, Show)
data Action = Action { actionKind :: String, actionSessionId :: String, actionToolName :: String, actionArguments :: Json } deriving (Eq, Show)
data Interrupt = Interrupt { interruptRunId :: String, interruptSessionId :: String, interruptCall :: ToolCall } deriving (Eq, Show)
data InterruptDecision = InterruptDecision { interruptAction :: String, interruptArguments :: Maybe Json, interruptResponse :: String, interruptReason :: String } deriving (Eq, Show)
type InterruptHandler = Interrupt -> IO InterruptDecision
type InterruptApproval = Interrupt -> IO Bool
data Message = Message { messageRole :: String, messageContent :: String, messageToolCalls :: [ToolCall], messageToolCallId :: String } deriving (Eq, Show)
data Response = Response { responseContent :: String, responseToolCalls :: [ToolCall], inputTokens :: Integer, outputTokens :: Integer } deriving (Eq, Show)
data AgentOptions = AgentOptions { generate :: [Message] -> IO (Either AgentError Response), invoke :: ToolCall -> IO (Either AgentError Json), emit :: String -> IO (Either AgentError ()), maxSteps :: Int, maxTokens :: Integer, policy :: Maybe (Action -> Bool), allowedTools :: [String], requirePolicy :: Bool, requireToolScope :: Bool, runId :: String, sessionId :: String, interruptOn :: [String], onInterruptDecision :: Maybe InterruptHandler, onInterrupt :: Maybe InterruptApproval, beforeTool :: Maybe (ToolCall -> IO (Either AgentError ToolCall)) }
data RunResult = RunResult { runOutput :: String, runSteps :: Int, runInputTokens :: Integer, runOutputTokens :: Integer, runMessages :: [Message] } deriving (Eq, Show)
data InterruptOutcome = InterruptOutcome
{ outcomeSkip :: Bool
, outcomeResponse :: String
, outcomeCall :: ToolCall
, outcomeEdited :: Bool
}
ensureAllowed :: Either AgentError () -> IO (Either AgentError a) -> IO (Either AgentError a)
ensureAllowed (Left err) _ = pure (Left err)
ensureAllowed (Right ()) action = action
runAgent :: AgentOptions -> [Message] -> String -> IO (Either AgentError RunResult)
runAgent options history prompt =
case validateOptions options of
Just err -> pure (Left err)
Nothing -> do
started <- emit options "run.started"
case started of
Left err -> pure (Left err)
Right () -> do
result <- loop 1 0 0 (history ++ [Message "user" prompt [] ""])
case result of
Left err -> do
_ <- emit options "run.failed"
pure (Left err)
Right value -> do
completed <- emit options "run.completed"
case completed of
Left err -> do
_ <- emit options "run.failed"
pure (Left err)
Right () -> pure (Right value)
where
limit = if maxSteps options > 0 then maxSteps options else 8
validateOptions opts
| requirePolicy opts && isNothing (policy opts) =
Just (AgentError "AGENT_INVALID_OPTIONS" "agent: require policy: policy is required")
| requireToolScope opts && null (allowedTools opts) =
Just (AgentError "AGENT_INVALID_OPTIONS" "agent: require tool scope: allowedTools must not be empty")
| otherwise = Nothing
authorize kind call = case policy options of
Nothing -> Right ()
Just hook ->
if hook (Action kind (sessionId options) (toolCallName call) (toolCallArguments call))
then Right ()
else Left (AgentError "AGENT_POLICY_DENIED" ("agent: " ++ kind ++ " denied"))
checkTool call
| not (null (allowedTools options)) && toolCallName call `notElem` allowedTools options =
Left (AgentError "AGENT_TOOL_NOT_ALLOWED" ("agent: tool " ++ toolCallName call ++ " is not allowed"))
| otherwise = authorize "tool.invoke" call
loop step usedIn usedOut messages
| step > limit = pure (Left (AgentError "AGENT_MAX_STEPS" "agent: maximum steps exceeded"))
| otherwise = ensureAllowed (authorize "model.generate" (ToolCall "" "" JNull)) $ do
generated <- generate options messages
case generated of
Left err -> pure (Left err)
Right response | inputTokens response < 0 || outputTokens response < 0 ->
pure (Left (AgentError "AGENT_INVALID_USAGE" "agent: token usage must be non-negative"))
Right response -> do
let totalIn = usedIn + inputTokens response
totalOut = usedOut + outputTokens response
next = messages ++ [Message "assistant" (responseContent response) (responseToolCalls response) ""]
if maxTokens options > 0 && totalIn + totalOut > maxTokens options
then pure (Left (AgentError "AGENT_MAX_TOKENS" "agent: maximum tokens exceeded"))
else if null (responseToolCalls response)
then pure (Right (RunResult (responseContent response) step totalIn totalOut next))
else do
result <- tools next (responseToolCalls response)
case result of
Left err -> pure (Left err)
Right updated -> loop (step + 1) totalIn totalOut updated
tools messages [] = pure (Right messages)
tools messages (call:rest) = case checkTool call of
Left err -> pure (Left err)
Right () -> do
prepared <- applyBeforeTool call
case prepared of
Left err -> pure (Left err)
Right active -> do
interrupted <- applyInterrupt active
case interrupted of
Left err -> pure (Left err)
Right outcome
| outcomeSkip outcome -> finishSkipped messages outcome rest
| otherwise -> do
let final = outcomeCall outcome
recheck = if outcomeEdited outcome || final /= call
then checkTool final
else Right ()
ensureAllowed recheck $ do
event <- emit options "tool.call"
case event of
Left err -> pure (Left err)
Right () -> do
result <- invoke options final
case result of
Left err -> pure (Left err)
Right value -> case encodeJson value of
Left detail -> pure (Left (AgentError "TOOL_RESULT" detail))
Right content -> tools (messages ++ [Message "tool" content [] (toolCallId final)]) rest
finishSkipped messages outcome rest =
case encodeJson (JString (outcomeResponse outcome)) of
Left detail -> pure (Left (AgentError "TOOL_RESULT" detail))
Right content -> tools (messages ++ [Message "tool" content [] (toolCallId (outcomeCall outcome))]) rest
applyBeforeTool call = case beforeTool options of
Nothing -> pure (Right call)
Just handler -> handler call
applyInterrupt call
| toolCallName call `notElem` interruptOn options =
pure (Right (InterruptOutcome False "" call False))
| isNothing (onInterruptDecision options) && isNothing (onInterrupt options) =
pure (Left (AgentError "AGENT_INTERRUPT_UNHANDLED"
("agent: approval handler not configured: " ++ toolCallName call)))
| otherwise = do
event <- emit options "tool.interrupt"
case event of
Left err -> pure (Left err)
Right () -> do
let pending = Interrupt (runId options) (sessionId options) call
case onInterruptDecision options of
Just handler -> fmap (applyDecision call) (handler pending)
Nothing -> case onInterrupt options of
Just approval -> do
approved <- approval pending
pure $ if approved
then Right (InterruptOutcome False "" call False)
else Left (AgentError "AGENT_APPROVAL_DENIED"
("agent: tool call denied by approval: " ++ toolCallName call))
Nothing -> pure (Left (AgentError "AGENT_INTERRUPT_UNHANDLED"
("agent: approval handler not configured: " ++ toolCallName call)))
applyDecision call decision
| interruptAction decision == interruptApprove =
Right (InterruptOutcome False "" call False)
| interruptAction decision == interruptEdit =
case interruptArguments decision of
Nothing -> Left (AgentError "AGENT_INTERRUPT_DECISION_INVALID" "agent: edit requires arguments")
Just arguments -> Right (InterruptOutcome False ""
(call { toolCallArguments = arguments }) True)
| interruptAction decision == interruptReject =
Left (AgentError "AGENT_APPROVAL_DENIED"
("agent: tool call denied by approval: " ++ toolCallName call ++ ": "
++ interruptReason decision))
| interruptAction decision == interruptRespond =
Right (InterruptOutcome True (interruptResponse decision) call False)
| otherwise =
Left (AgentError "AGENT_INTERRUPT_DECISION_INVALID"
("agent: invalid interrupt decision: " ++ show (interruptAction decision)))