axterminator 0.8.0

macOS GUI testing framework with background testing, sub-millisecond element access, and self-healing locators
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

//! Canonical tool annotations for every Phase 1 and Phase 2 tool.
//!
//! Each constant captures the semantic hints defined in MCP 2025-11-05 §6.3.
//! Centralising them here ensures the CLI help text and MCP `tools/list` response
//! stay consistent with the design document.
//!
//! ## Annotation semantics
//!
//! | Constant | `readOnly` | `destructive` | `idempotent` | `openWorld` |
//! |----------|-----------|--------------|-------------|------------|
//! | [`READ_ONLY`] | ✓ | — | ✓ | — |
//! | [`CONNECT`] | — | — | ✓ | — |
//! | [`ACTION`] | — | — | — | — |
//! | [`DESTRUCTIVE`] | — | ✓ | — | — |
//! | [`OPEN_WORLD`] | — | ✓ | — | ✓ |

use crate::mcp::protocol::ToolAnnotations;

/// Read-only, idempotent, bounded — safe to call any number of times.
///
/// Use for: `ax_find`, `ax_get_value`, `ax_screenshot`, `ax_list_windows`,
/// `ax_get_tree`, `ax_is_accessible`, `ax_list_apps`.
pub const READ_ONLY: ToolAnnotations = ToolAnnotations {
    read_only: true,
    destructive: false,
    idempotent: true,
    open_world: false,
};

/// State-changing but idempotent — connecting twice is safe.
///
/// Use for: `ax_connect`.
pub const CONNECT: ToolAnnotations = ToolAnnotations {
    read_only: false,
    destructive: false,
    idempotent: true,
    open_world: false,
};

/// State-changing, not idempotent — clicking twice may click twice.
///
/// Use for: `ax_click`, `ax_click_at`, `ax_scroll`, `ax_wait_idle`.
pub const ACTION: ToolAnnotations = ToolAnnotations {
    read_only: false,
    destructive: false,
    idempotent: false,
    open_world: false,
};

/// Destructive action (e.g., typing overwrites existing text).
///
/// Use for: `ax_type`, `ax_set_value`.
pub const DESTRUCTIVE: ToolAnnotations = ToolAnnotations {
    read_only: false,
    destructive: true,
    idempotent: false,
    open_world: false,
};

/// Open-world action that interacts with external services (e.g. a VLM).
///
/// Use for: `ax_find_visual` — reads the screen and may call an external AI API.
/// The `openWorldHint` signals to the MCP client that results are non-deterministic
/// and may have network or cost implications.
pub const OPEN_WORLD: ToolAnnotations = ToolAnnotations {
    read_only: true,
    destructive: false,
    idempotent: true,
    open_world: true,
};

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

    #[test]
    fn read_only_annotations_are_safe() {
        assert!(READ_ONLY.read_only);
        assert!(!READ_ONLY.destructive);
        assert!(READ_ONLY.idempotent);
        assert!(!READ_ONLY.open_world);
    }

    #[test]
    fn connect_annotations_are_not_read_only() {
        assert!(!CONNECT.read_only);
        assert!(CONNECT.idempotent);
        assert!(!CONNECT.destructive);
        assert!(!CONNECT.open_world);
    }

    #[test]
    fn action_is_not_idempotent() {
        assert!(!ACTION.idempotent);
        assert!(!ACTION.read_only);
        assert!(!ACTION.open_world);
    }

    #[test]
    fn destructive_annotations_flag_correctly() {
        assert!(DESTRUCTIVE.destructive);
        assert!(!DESTRUCTIVE.idempotent);
        assert!(!DESTRUCTIVE.open_world);
    }

    #[test]
    fn open_world_sets_open_world_flag() {
        // GIVEN: OPEN_WORLD constant
        // WHEN: inspected
        // THEN: open_world is true, read_only is true (visual find is non-mutating)
        assert!(OPEN_WORLD.open_world);
        assert!(OPEN_WORLD.read_only);
        assert!(!OPEN_WORLD.destructive);
    }
}