car-ffi-common 0.28.0

Shared logic for FFI bindings (NAPI, PyO3) — JSON wrappers for verify, multi-agent, scheduler
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
117
118

//! Proxies for the daemon's `declagents.*` namespace (in-daemon declarative
//! agents). Thin [`DaemonClient`] calls.

use serde_json::{json, Value};

use crate::proxy::DaemonClient;

fn to_string(v: Value) -> Result<String, String> {
    serde_json::to_string(&v).map_err(|e| e.to_string())
}

/// `declagents.list` — registered declarative agents.
pub async fn list(client: &DaemonClient) -> Result<String, String> {
    client
        .call("declagents.list", json!({}))
        .await
        .and_then(to_string)
}

/// `declagents.get` — one agent's spec.
pub async fn get(client: &DaemonClient, id: &str) -> Result<String, String> {
    client
        .call("declagents.get", json!({ "id": id }))
        .await
        .and_then(to_string)
}

/// `declagents.remove` — unregister an agent.
pub async fn remove(client: &DaemonClient, id: &str) -> Result<String, String> {
    client
        .call("declagents.remove", json!({ "id": id }))
        .await
        .and_then(to_string)
}

/// `declagents.set_enabled` — enable/disable an agent.
pub async fn set_enabled(client: &DaemonClient, id: &str, enabled: bool) -> Result<String, String> {
    client
        .call(
            "declagents.set_enabled",
            json!({ "id": id, "enabled": enabled }),
        )
        .await
        .and_then(to_string)
}

/// `declagents.invoke` — run an agent on an input, in-daemon. Returns
/// `{ output, turns, tool_calls, error? }`.
pub async fn invoke(client: &DaemonClient, id: &str, input: &str) -> Result<String, String> {
    client
        .call("declagents.invoke", json!({ "id": id, "input": input }))
        .await
        .and_then(to_string)
}

/// `declagents.route` — pick the agent whose capability best matches `need`
/// (capability-similarity routing). Returns `{ chosen, candidates, next_visited,
/// invoked, result? }`. With `invoke: true`, the top agent is run on `need` and
/// its `{ output, turns, tool_calls, error? }` lands in `result`.
///
/// This binding covers the network-entry case. Multi-hop Forward chaining (the
/// `from`/`visited` params) is WS-only — drive it over the raw JSON-RPC method.
pub async fn route(client: &DaemonClient, need: &str, invoke: bool) -> Result<String, String> {
    client
        .call(
            "declagents.route",
            json!({ "need": need, "invoke": invoke }),
        )
        .await
        .and_then(to_string)
}

/// `declagents.route_split` — decompose `need` into subtasks and route each to
/// its best-matching agent. Returns `{ subtasks: [{ subtask, chosen, score,
/// result? }], count, invoked }`. `max_subtasks` caps the split (clamped to
/// [1, 10]; None = default 5). With `invoke: true`, each subtask's chosen agent
/// runs on that subtask.
pub async fn route_split(
    client: &DaemonClient,
    need: &str,
    invoke: bool,
    max_subtasks: Option<u32>,
    decomposition_mode: Option<&str>,
    sad_hints: Option<u32>,
    sad_iterations: Option<u32>,
    sad_convergence_jaccard: Option<f64>,
) -> Result<String, String> {
    let mut params = json!({ "need": need, "invoke": invoke });
    if let Some(m) = max_subtasks {
        params["max_subtasks"] = json!(m);
    }
    if let Some(mode) = decomposition_mode {
        params["decomposition_mode"] = json!(mode);
    }
    if let Some(h) = sad_hints {
        params["sad_hints"] = json!(h);
    }
    if let Some(i) = sad_iterations {
        params["sad_iterations"] = json!(i);
    }
    if let Some(j) = sad_convergence_jaccard {
        params["sad_convergence_jaccard"] = json!(j);
    }
    client
        .call("declagents.route_split", params)
        .await
        .and_then(to_string)
}

/// `declagents.routing_stats` — read-only view of the learned routing topology.
/// Returns `{ agents: { id: { successes, failures, ema_success_rate } }, edges:
/// { from: { to: weight } } }`.
pub async fn routing_stats(client: &DaemonClient) -> Result<String, String> {
    client
        .call("declagents.routing_stats", json!({}))
        .await
        .and_then(to_string)
}