machi-protocol 1.0.0

Wire-agnostic protocol types for the Machi agent runtime kernel
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

//! Stable tracing span names and field keys for OpenTelemetry-friendly hosts.

/// Session lifetime span.
pub const SPAN_SESSION: &str = "machi.session";
/// Single turn span.
pub const SPAN_TURN: &str = "machi.turn";
/// One LLM sample call.
pub const SPAN_SAMPLE: &str = "machi.sample";
/// One tool execution.
pub const SPAN_TOOL: &str = "machi.tool";
/// Dispatched tool batch.
pub const SPAN_TOOL_BATCH: &str = "machi.tool.batch";
/// Nested agent spawn.
pub const SPAN_SPAWN: &str = "machi.spawn";
/// Workflow run.
pub const SPAN_WORKFLOW: &str = "machi.workflow";
/// One workflow host request.
pub const SPAN_WORKFLOW_HOST: &str = "machi.workflow.host";
/// Compaction pass.
pub const SPAN_COMPACT: &str = "machi.compact";

/// Canonical field names (string constants for hosts and tests).
pub mod field {
    /// Session id.
    pub const SESSION_ID: &str = "machi.session_id";
    /// Agent id.
    pub const AGENT_ID: &str = "machi.agent_id";
    /// Agent name.
    pub const AGENT_NAME: &str = "machi.agent_name";
    /// Run / turn id.
    pub const RUN_ID: &str = "machi.run_id";
    /// Step index within a turn.
    pub const STEP: &str = "machi.step";
    /// Tool name.
    pub const TOOL_NAME: &str = "machi.tool_name";
    /// Model id.
    pub const MODEL: &str = "machi.model";
    /// Input tokens.
    pub const USAGE_INPUT: &str = "machi.usage.input_tokens";
    /// Output tokens.
    pub const USAGE_OUTPUT: &str = "machi.usage.output_tokens";
    /// Workflow run id.
    pub const WORKFLOW_RUN_ID: &str = "machi.workflow.run_id";
    /// Workflow journal sequence.
    pub const WORKFLOW_SEQ: &str = "machi.workflow.seq";
}

/// All required span names (contract test surface).
///
/// **Rename = break:** CI asserts [`span_catalogue_snapshot`].
#[must_use]
pub fn required_span_names() -> &'static [&'static str] {
    &[
        SPAN_SESSION,
        SPAN_TURN,
        SPAN_SAMPLE,
        SPAN_TOOL,
        SPAN_TOOL_BATCH,
        SPAN_SPAWN,
        SPAN_WORKFLOW,
        SPAN_WORKFLOW_HOST,
        SPAN_COMPACT,
    ]
}

/// Exact newline-joined span catalogue for CI golden comparison.
#[must_use]
pub fn span_catalogue_snapshot() -> String {
    required_span_names().join("\n")
}

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

    const SPAN_CATALOGUE_GOLDEN: &str = "\
machi.session
machi.turn
machi.sample
machi.tool
machi.tool.batch
machi.spawn
machi.workflow
machi.workflow.host
machi.compact";

    #[test]
    fn span_names_are_machi_prefixed_and_unique() {
        let names = required_span_names();
        assert_eq!(names.len(), 9, "expected nine spans");
        let mut seen = std::collections::BTreeSet::new();
        for name in names {
            assert!(
                name.starts_with("machi."),
                "span {name} must start with machi."
            );
            assert!(seen.insert(*name), "duplicate span {name}");
        }
    }

    #[test]
    fn span_catalogue_snapshot_matches_golden() {
        assert_eq!(
            span_catalogue_snapshot(),
            SPAN_CATALOGUE_GOLDEN,
            "span catalogue changed — update golden only with deliberate contract change"
        );
    }

    #[test]
    fn field_keys_are_stable() {
        assert_eq!(field::SESSION_ID, "machi.session_id");
        assert_eq!(field::TOOL_NAME, "machi.tool_name");
        assert_eq!(field::WORKFLOW_SEQ, "machi.workflow.seq");
    }
}