holon 0.14.1

A headless, event-driven runtime for long-lived agents
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

use anyhow::Result;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::{
    runtime::RuntimeHandle,
    tool::spec::typed_spec,
    types::{
        EnqueueResult, MessageBody, MessageDeliverySurface, MessageEnvelope, MessageKind,
        MessageOrigin, Priority, ToolCapabilityFamily, TrustLevel,
    },
};

use super::{serialize_success, BuiltinToolDefinition};
use crate::tool::helpers::{parse_tool_args, validate_non_empty};

pub(crate) const NAME: &str = "Enqueue";

#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
#[allow(dead_code)]
pub(crate) enum EnqueuePriority {
    // TODO: remove `interrupt` alias after older prompt/tool-call contexts have migrated.
    #[serde(alias = "interrupt")]
    Interject,
    Next,
    Normal,
    Background,
}

#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub(crate) struct EnqueueArgs {
    pub(crate) text: String,
    pub(crate) priority: Option<EnqueuePriority>,
}

pub(crate) fn definition() -> Result<BuiltinToolDefinition> {
    Ok(BuiltinToolDefinition {
        family: ToolCapabilityFamily::CoreAgent,
        spec: typed_spec::<EnqueueArgs>(
            NAME,
            "Enqueue a follow-up message into the current agent.",
        )?,
    })
}

pub(crate) async fn execute(
    runtime: &RuntimeHandle,
    agent_id: &str,
    trust: &TrustLevel,
    input: &Value,
) -> Result<crate::tool::ToolResult> {
    let args: EnqueueArgs = parse_tool_args(NAME, input)?;
    let text = validate_non_empty(args.text, NAME, "text")?;
    let priority = match args.priority.unwrap_or(EnqueuePriority::Next) {
        EnqueuePriority::Interject => Priority::Interject,
        EnqueuePriority::Next => Priority::Next,
        EnqueuePriority::Normal => Priority::Normal,
        EnqueuePriority::Background => Priority::Background,
    };
    let message = MessageEnvelope::new(
        agent_id.to_string(),
        MessageKind::InternalFollowup,
        MessageOrigin::System {
            subsystem: "tool_enqueue".into(),
        },
        trust.clone(),
        priority.clone(),
        MessageBody::Text { text: text.clone() },
    )
    .with_admission(
        MessageDeliverySurface::RuntimeSystem,
        crate::types::AdmissionContext::RuntimeOwned,
    );
    runtime.enqueue(message).await?;
    serialize_success(
        NAME,
        &EnqueueResult {
            enqueued: true,
            priority,
            follow_up_text: text.clone(),
            summary_text: Some(format!("enqueued follow-up: {text}")),
        },
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn legacy_interrupt_priority_deserializes_as_interject() {
        let args: EnqueueArgs = serde_json::from_value(serde_json::json!({
            "text": "follow up",
            "priority": "interrupt"
        }))
        .unwrap();

        assert!(matches!(args.priority, Some(EnqueuePriority::Interject)));
    }
}