Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
//! Wire shape snapshot (docs/reference/compatibility.md).
use super::*;
/// Snapshot of what clients decode: field paths and JSON types of `hello` and the event
/// stream after a full turn. Values aren't kept, only the shape.
const WIRE_SHAPE: &str = "tests/fixtures/wire-shape.json";
/// Re-records the snapshot (refused while a field is removed or retyped without a new `minApp`).
const UPDATE_ENV: &str = "CODYNC_UPDATE_WIRE_SHAPE";
/// Depends on the machine (installed harnesses, displays, addresses, local usage), not the code.
const MACHINE_DEPENDENT: [&str; 4] = ["backends", "screen", "urls", "usage"];
fn json_type(v: &Value) -> &'static str {
match v {
Value::Null => "null",
Value::Bool(_) => "bool",
Value::Number(_) => "number",
Value::String(_) => "string",
Value::Array(_) => "array",
Value::Object(_) => "object",
}
}
/// Every field path under `v` with its type; array elements merge under `[]`.
fn shape(v: &Value, path: &str, out: &mut std::collections::BTreeMap<String, String>) {
out.insert(path.to_owned(), json_type(v).to_owned());
match v {
Value::Object(map) => {
for (k, child) in map {
if !MACHINE_DEPENDENT.contains(&k.as_str()) {
shape(child, &format!("{path}.{k}"), out);
}
}
}
Value::Array(items) => {
for item in items {
shape(item, &format!("{path}[]"), out);
}
}
_ => {}
}
}
/// The shape of a stream event, keyed by its type (and an entry's kind: their data differ).
fn event_shape(ev: &Value, out: &mut std::collections::BTreeMap<String, String>) {
let ty = ev["type"].as_str().unwrap_or("?");
let key = match ev["entry"]["kind"].as_str() {
Some(kind) if ty == "entry" => format!("event:entry({kind})"),
_ => format!("event:{ty}"),
};
shape(ev, &key, out);
}
/// What changed between the recorded and the current shape: (breaking, additions).
/// A field that was `null` on either side can't be judged by its type.
fn shape_diff(
recorded: &std::collections::BTreeMap<String, String>,
current: &std::collections::BTreeMap<String, String>,
) -> (Vec<String>, Vec<String>) {
let mut breaking = vec![];
for (path, ty) in recorded {
match current.get(path) {
None => breaking.push(format!("removed {path} ({ty})")),
Some(now) if now != ty && now != "null" && ty != "null" => {
breaking.push(format!("retyped {path}: {ty} → {now}"));
}
Some(_) => {}
}
}
let added = current
.iter()
.filter(|(path, ty)| recorded.get(*path).is_none_or(|old| old == "null" && *ty != "null"))
.map(|(path, ty)| format!("{path} ({ty})"))
.collect();
(breaking, added)
}
#[test]
fn shape_diff_tells_breaking_from_additive() {
let map = |pairs: &[(&str, &str)]| pairs.iter().map(|(k, v)| ((*k).to_owned(), (*v).to_owned())).collect();
let recorded = map(&[("a", "object"), ("a.x", "string"), ("a.y", "null"), ("a.z", "number")]);
let current = map(&[("a", "object"), ("a.x", "number"), ("a.y", "string"), ("a.w", "bool")]);
let (breaking, added) = shape_diff(&recorded, ¤t);
assert_eq!(breaking, ["retyped a.x: string → number", "removed a.z (number)"]);
assert_eq!(added, ["a.w (bool)", "a.y (string)"]);
}
/// Reads the event stream's catch-up until it goes quiet.
async fn catch_up(host: &Host) -> Vec<Value> {
let res = reqwest::Client::new()
.get(format!("{}/events?since=0&client=test", host.base))
.bearer_auth(&host.token)
.send()
.await
.unwrap();
let mut body = res.bytes_stream();
let (mut buf, mut events) = (String::new(), vec![]);
while let Ok(Some(Ok(chunk))) = tokio::time::timeout(Duration::from_millis(1500), body.next()).await {
buf.push_str(&String::from_utf8_lossy(&chunk));
while let Some(i) = buf.find('\n') {
let line: String = buf.drain(..=i).collect();
if let Some(data) = line.trim_end().strip_prefix("data:")
&& let Ok(v) = serde_json::from_str::<Value>(data.trim_start())
// A live usage refresh lands whenever the agents' usage poll finishes (later on a
// busy machine); its shape is `hello.usage`'s.
&& v["type"] != "usage"
{
events.push(v);
}
}
}
events
}
/// Older apps read what the host sends: a removed or retyped field breaks them. This fails
/// until the field is kept, or `MIN_APP` is raised the two-release way and the snapshot
/// re-recorded. New fields only need recording (`CODYNC_UPDATE_WIRE_SHAPE=1`).
#[tokio::test]
async fn wire_shape_matches_the_snapshot() {
if Command::new(common::python()).arg("--version").output().is_err() {
eprintln!("skipping: Python not available");
return;
}
let host = start_host().await;
let agent = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fake_agent.py");
let bot = host
.call(
"createBot",
json!({
"name": "Tester", "backend": "custom", "command": common::python_agent(&agent),
"cwd": host.home.to_string_lossy(), "permission": "ask",
}),
)
.await["bot"]["id"]
.as_str()
.unwrap()
.to_owned();
host.call("send", json!({"botId": bot, "text": "go", "clientNonce": "n1"})).await;
let card = host.wait_for(&bot, |e| e["kind"] == "permission" && e["data"]["status"] == "pending").await;
// A queued message taken back: its `removed`.
let waiting = host.call("send", json!({"botId": bot, "text": "never mind", "clientNonce": "n3"})).await;
host.call("unqueue", json!({"botId": bot, "entryId": waiting["entry"]["id"]})).await;
host.call("respondPermission", json!({"entryId": card["id"], "optionId": "allow"})).await;
host.wait_for(&bot, |e| e["kind"] == "agent" && e["data"]["final"] == true).await;
// A bot another bot created: its `createdBy`.
let lead = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/team_agent.py");
let lead = host
.call(
"createBot",
json!({"name": "Lead", "backend": "custom", "command": common::python_agent(&lead), "connectors": [],
"permission": "auto", "manageTeam": true}),
)
.await["bot"]["id"]
.as_str()
.unwrap()
.to_owned();
host.call("send", json!({"botId": lead, "text": "MANAGE create_bot {\"name\": \"Made\"}", "clientNonce": "n2"}))
.await;
let made = host.wait_for(&lead, |e| e["kind"] == "agent" && e["data"]["final"] == true).await;
assert!(made["data"]["text"].as_str().unwrap().starts_with("Done: "), "{made}");
// A running dev server: its `devServers`.
let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
let arguments = json!({"command": common::port_server(port), "name": "web"});
let server =
host.call("chatCall", json!({"botId": lead, "name": "start_dev_server", "arguments": arguments})).await;
assert_eq!(server["ports"][0]["port"], port, "{server}");
// A bot in a roster section: its `section`.
host.call("updateBot", json!({"id": bot, "section": "Work"})).await;
let hello = host.call("hello", json!({})).await;
let min_app = hello["minApp"].as_str().unwrap().to_owned();
let mut current = std::collections::BTreeMap::new();
shape(&hello, "hello", &mut current);
for ev in catch_up(&host).await {
event_shape(&ev, &mut current);
}
assert!(current.keys().any(|k| k.starts_with("event:entry(tool)")), "the turn's entries are missing");
let file = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(WIRE_SHAPE);
let recorded: Value = std::fs::read_to_string(&file).map_or(Value::Null, |s| serde_json::from_str(&s).unwrap());
let recorded_shapes: std::collections::BTreeMap<String, String> =
serde_json::from_value(recorded["shapes"].clone()).unwrap_or_default();
let (breaking, added) = shape_diff(&recorded_shapes, ¤t);
let floor_raised = recorded["minApp"].as_str() != Some(min_app.as_str());
assert!(
breaking.is_empty() || floor_raised,
"Older apps would break: {breaking:#?}\nKeep these fields, or follow the two-release rule \
in docs/reference/compatibility.md: raise MIN_APP (host/src/compat.rs) once that iPhone \
version is live, then re-record with {UPDATE_ENV}=1 cargo test --test e2e wire_shape"
);
if std::env::var_os(UPDATE_ENV).is_some() {
let json = json!({"minApp": min_app, "shapes": current});
std::fs::write(&file, serde_json::to_string_pretty(&json).unwrap() + "\n").unwrap();
return;
}
assert!(
breaking.is_empty() && added.is_empty() && !floor_raised,
"The wire shape changed.\nAdded: {added:#?}\nRemoved or retyped (minApp was raised): {breaking:#?}\n\
Record it with {UPDATE_ENV}=1 cargo test --test e2e wire_shape"
);
}