thrall 0.0.1

thrall: the foot — a tool-execution client for a yog server
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

//! **The advertised element** (yog's `docs/REMOTE.md` §5.1): the three facts a
//! tool host presents about one tool, and the one spelling of them.
//!
//! ```json
//! {"name": "Bash", "description": "run a command",
//!  "input_schema": {"type": "object",
//!                   "properties": {"command": {"type": "string"}}}}
//! ```
//!
//! - **`name` is a single path component.** It is the handle the far end's load
//!   act addresses one tool by, and a name carrying a separator is a name that
//!   addresses a filesystem.
//! - **`description` is one string**, this host's own words.
//! - **`input_schema` is the JSON Schema, verbatim.** Neither validated nor
//!   rewritten — it is this box's statement to a model, and narrowing it here
//!   would be thrall inventing a contract it does not own. It is also why the
//!   config document is JSON: any other syntax would make the operator
//!   transcribe a schema.
//!
//! **Nothing else.** No version, no enable flag, no per-workspace list — each
//! would be a fact stored on one side and checkable on neither.
//!
//! **One spelling, spent in both directions.** [`encode`] is what the
//! advertisement puts on the wire and [`of_one`] is what reads an element back;
//! the operator's document ([`config`](crate::config)) is read by the very same
//! decoder, because a presented element and a configured one spelled twice
//! drift within a week.

use serde_json::{Value, json};

use crate::json::str_of;

/// One advertised tool: the three facts, and the schema as the value it
/// arrived as.
///
/// **[`Eq`] is written rather than derived**, because [`Value`] is not `Eq` —
/// it holds `f64`, whose `NaN` is the one value equality is not reflexive over.
/// A schema that came through a JSON decoder cannot hold one: the grammar has
/// no `NaN` literal and `serde_json` will not emit one. So equality here is
/// reflexive by construction, and saying so is what lets the whole surface keep
/// the `Eq` its round-trip is asserted with.
#[derive(Debug, Clone, PartialEq)]
pub struct Tool {
    /// The tool's name, a single path component.
    pub name: String,
    /// What it does, in this host's own words.
    pub description: String,
    /// Its JSON Schema, verbatim.
    pub input_schema: Value,
}

impl Eq for Tool {}

/// A set as JSON — the array the advertisement carries.
pub fn encode(tools: &[Tool]) -> Value {
    Value::Array(tools.iter().map(one).collect())
}

/// One element, spelled once.
pub fn one(t: &Tool) -> Value {
    json!({ "name": t.name, "description": t.description,
            "input_schema": t.input_schema })
}

/// One element, read back — [`one`]'s inverse, and the decoder the operator's
/// document spends on its own first three keys.
pub fn of_one(row: &Value) -> Result<Tool, String> {
    let o = row.as_object().ok_or("tool: not a JSON object")?;
    Ok(Tool {
        name: str_of(o, "name").map_err(|e| format!("tool: {e}"))?,
        description: str_of(o, "description").map_err(|e| format!("tool: {e}"))?,
        input_schema: o
            .get("input_schema")
            .cloned()
            .ok_or("tool: missing field \"input_schema\"")?,
    })
}

/// Refuse a set that cannot be addressed (REMOTE §5.1): a name that is not a
/// single path component, or two elements wearing one name. Both name the
/// offending token — a decline an operator can act on.
///
/// **A collision across hosts is legal and ordinary** — two boxes both offering
/// `Bash` — and disambiguating them belongs to the act at the far end that
/// loads one. What cannot stand is a collision *inside* this box's set, because
/// then no name addresses one tool here.
pub fn validate(tools: &[Tool]) -> Result<(), String> {
    let mut seen = std::collections::BTreeSet::new();
    for tool in tools {
        if !is_component(&tool.name) {
            return Err(format!("unusable tool name {:?}", tool.name));
        }
        if !seen.insert(tool.name.clone()) {
            return Err(format!("duplicate tool name {:?}", tool.name));
        }
    }
    Ok(())
}

/// Whether `name` is a single path component: something that names one thing
/// and cannot walk anywhere.
fn is_component(name: &str) -> bool {
    !name.is_empty()
        && name != "."
        && name != ".."
        && !name.contains('/')
        && !name.contains('\\')
        && !name.contains('\0')
}

#[cfg(test)]
mod tests;