agent-base 0.4.0

A lightweight Agent Runtime Kernel for building AI agents in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use async_trait::async_trait;

// Re-export from agent-types (single source of truth).
pub use agent_types::{GuardCtx, GuardDecision};

/// React Loop Guard trait — single unified entry point.
///
/// Runtime builds GuardCtx (with scene hints), guard decides what to do.
/// The guard has full control: it can trust the hints or re-detect.
#[async_trait]
pub trait ReactLoopGuard: Send + Sync {
    /// Unified entry point — guard judges the scene and returns a decision.
    async fn on_turn(&self, ctx: &GuardCtx) -> GuardDecision;

    /// Callback when model calls a tool (new)
    ///
    /// Default implementation: returns Complete (let other logic continue)
    ///
    /// Usage:
    /// - DefaultGuard can return RestoreThinking here
    /// - Other guards can record tool call history
    ///
    /// Note: This callback is called before tool execution, Guard cannot prevent tool execution
    async fn on_tool_call(&self, _ctx: &GuardCtx) -> GuardDecision {
        GuardDecision::Complete
    }
}

/// Default guard — fails on degenerate states, completes on normal flow.
///
/// This is the default guard injected when no custom guard is set.
/// It provides basic safety: reasoning-only and empty responses fail,
/// text-only responses complete normally.
pub struct NoopGuard;

#[async_trait]
impl ReactLoopGuard for NoopGuard {
    async fn on_turn(&self, ctx: &GuardCtx) -> GuardDecision {
        if ctx.is_reasoning_only || ctx.is_empty_response {
            GuardDecision::Fail {
                error: if ctx.is_reasoning_only {
                    "model produced only reasoning, no output".to_string()
                } else {
                    "model returned empty response".to_string()
                },
            }
        } else {
            GuardDecision::Complete
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use agent_types::{FinishReason, SessionId};

    #[tokio::test]
    async fn test_noop_guard_returns_complete() {
        let guard = NoopGuard;
        let ctx = GuardCtx {
            session_id: SessionId {
                id: 1,
                external_id: None,
            },
            turn_count: 1,
            user_input: "test".to_string(),
            model_response: "response".to_string(),
            finish_reason: FinishReason::Stop,
            available_tools: vec![],
            reasoning_only_strikes: 0,
            empty_response_strikes: 0,
            run_has_tool_calls: false,
            all_user_inputs: vec!["test".to_string()],
            is_reasoning_only: false,
            is_empty_response: false,
            is_text_only: false,
            thinking_disabled: false,
            original_thinking_enabled: true,
            remaining_turns: 50,
        };

        assert!(matches!(guard.on_turn(&ctx).await, GuardDecision::Complete));
    }

    #[tokio::test]
    async fn test_noop_guard_handles_degenerate_states() {
        let guard = NoopGuard;

        // reasoning-only → Fail
        let ctx = GuardCtx {
            session_id: SessionId::new(1),
            turn_count: 1,
            user_input: "test".to_string(),
            model_response: "".to_string(),
            finish_reason: FinishReason::Stop,
            available_tools: vec![],
            reasoning_only_strikes: 1,
            empty_response_strikes: 0,
            run_has_tool_calls: false,
            all_user_inputs: vec!["test".to_string()],
            is_reasoning_only: true,
            is_empty_response: false,
            is_text_only: false,
            thinking_disabled: false,
            original_thinking_enabled: true,
            remaining_turns: 50,
        };
        assert!(matches!(
            guard.on_turn(&ctx).await,
            GuardDecision::Fail { .. }
        ));

        // empty response → Fail
        let mut ctx2 = ctx.clone();
        ctx2.is_reasoning_only = false;
        ctx2.is_empty_response = true;
        assert!(matches!(
            guard.on_turn(&ctx2).await,
            GuardDecision::Fail { .. }
        ));

        // text-only → Complete
        let mut ctx3 = ctx.clone();
        ctx3.is_reasoning_only = false;
        ctx3.is_empty_response = false;
        ctx3.is_text_only = true;
        assert!(matches!(
            guard.on_turn(&ctx3).await,
            GuardDecision::Complete
        ));

        // no flags → Complete
        let mut ctx4 = ctx.clone();
        ctx4.is_reasoning_only = false;
        ctx4.is_text_only = false;
        assert!(matches!(
            guard.on_turn(&ctx4).await,
            GuardDecision::Complete
        ));
    }
}