meerkat-core 0.1.0

Core agent logic for Meerkat (no I/O deps)
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

//! Hook integration helpers for agent lifecycle and loop points.

use crate::agent::{Agent, AgentLlmClient, AgentSessionStore, AgentToolDispatcher};
use crate::error::AgentError;
use crate::event::AgentEvent;
use crate::hooks::{HookDecision, HookEngineError, HookExecutionReport, HookInvocation};
use tokio::sync::mpsc;

impl<C, T, S> Agent<C, T, S>
where
    C: AgentLlmClient + ?Sized + 'static,
    T: AgentToolDispatcher + ?Sized + 'static,
    S: AgentSessionStore + ?Sized + 'static,
{
    pub(super) async fn execute_hooks(
        &self,
        invocation: HookInvocation,
        event_tx: Option<&mpsc::Sender<AgentEvent>>,
    ) -> Result<HookExecutionReport, AgentError> {
        let Some(hook_engine) = &self.hook_engine else {
            return Ok(HookExecutionReport::empty());
        };

        if let Some(tx) = event_tx {
            let planned = hook_engine
                .matching_hooks(&invocation, Some(&self.hook_run_overrides))
                .map_err(Self::map_hook_engine_error)?;
            for hook_id in planned {
                let _ = tx
                    .send(AgentEvent::HookStarted {
                        hook_id: hook_id.to_string(),
                        point: invocation.point,
                    })
                    .await;
            }
        }

        let report = hook_engine
            .execute(invocation.clone(), Some(&self.hook_run_overrides))
            .await
            .map_err(Self::map_hook_engine_error)?;

        if let Some(tx) = event_tx {
            for outcome in &report.outcomes {
                if let Some(error) = &outcome.error {
                    let _ = tx
                        .send(AgentEvent::HookFailed {
                            hook_id: outcome.hook_id.to_string(),
                            point: outcome.point,
                            error: error.clone(),
                        })
                        .await;
                } else {
                    let _ = tx
                        .send(AgentEvent::HookCompleted {
                            hook_id: outcome.hook_id.to_string(),
                            point: outcome.point,
                            duration_ms: outcome.duration_ms.unwrap_or(0),
                        })
                        .await;
                }
            }

            if let Some(HookDecision::Deny {
                hook_id,
                reason_code,
                message,
                payload,
            }) = &report.decision
            {
                let _ = tx
                    .send(AgentEvent::HookDenied {
                        hook_id: hook_id.to_string(),
                        point: invocation.point,
                        reason_code: *reason_code,
                        message: message.clone(),
                        payload: payload.clone(),
                    })
                    .await;
            }

            for envelope in &report.published_patches {
                let _ = tx
                    .send(AgentEvent::HookPatchPublished {
                        hook_id: envelope.hook_id.to_string(),
                        point: envelope.point,
                        envelope: envelope.clone(),
                    })
                    .await;
            }
        }

        Ok(report)
    }

    fn map_hook_engine_error(err: HookEngineError) -> AgentError {
        match err {
            HookEngineError::InvalidConfiguration(reason) => {
                AgentError::HookConfigInvalid { reason }
            }
            HookEngineError::Timeout {
                hook_id,
                timeout_ms,
            } => AgentError::HookTimeout {
                hook_id: hook_id.to_string(),
                timeout_ms,
            },
            HookEngineError::ExecutionFailed { hook_id, reason } => {
                AgentError::HookExecutionFailed {
                    hook_id: hook_id.to_string(),
                    reason,
                }
            }
        }
    }
}