Skip to content

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.

test(host): fail when the wire shape older apps decode changes

leepokaie5e17a862f97
diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md
index 33223e08..25bdd7d4 100644
--- a/docs/reference/compatibility.md
+++ b/docs/reference/compatibility.md
@@ -53,13 +53,35 @@ that stays undecodable after the one rewind, or a `hello` whose other fields can
The iPhone part of this release must actually ship (it changes `kit/`, so `Submit iOS`
includes it).
2. After that iPhone version is **live on the App Store**, a later host release drops the
- old form and sets `MIN_APP` to the version from step 1.
+ old form, sets `MIN_APP` to the version from step 1, and re-records the wire shape
+ snapshot (below).
Raising `MIN_APP` before the App Store has that version locks every iPhone out with no
update to install.
- **Raise `minHost`** only when the client's core flows need something older hosts lack. An
optional feature that needs a newer host hides its control instead.
- Floors never exceed the release that ships them (unit tests in both crates check this).
+
+### Wire shape snapshot
+
+`wire_shape_matches_the_snapshot` (`host/tests/e2e.rs`) runs a full turn against a real host
+(fake agent: user message, narration, tool call with a diff, plan, permission, final reply),
+then records every field path and JSON type of `hello` and the event stream's catch-up (bot
+and entry events, entries per kind) in `host/tests/fixtures/wire-shape.json`, together with
+the host's `minApp`.
+
+| Change | Test |
+|---|---|
+| Nothing on the wire | Passes |
+| New field | Fails until recorded: `CODYNC_UPDATE_WIRE_SHAPE=1 cargo test --test e2e wire_shape`, no decision needed |
+| Field removed, renamed or retyped | Fails, and recording is refused, until `MIN_APP` differs from the recorded one; then record |
+
+So a breaking change can't land by accident: it either keeps the old field or raises the
+floor, and the floor is raised only by the two-release rule above. `null` fields match any
+type. Not covered: subtrees that depend on the machine rather than the code (`backends`,
+`screen`, `urls`, `usage`), fields the sample turn doesn't produce (thread replies, group
+chats, routines and other method responses), and what the host accepts in requests. Changes
+there still follow the rule by review.
- The encrypted channel's handshake version (`v` in its `hello`, rejected with
`unsupportedVersion`, close code 4400) is separate: the host must keep accepting every `v`
a supported client sends.
diff --git a/host/tests/e2e.rs b/host/tests/e2e.rs
index 46a2f4d5..865e7f5e 100644
--- a/host/tests/e2e.rs
+++ b/host/tests/e2e.rs
@@ -361,3 +361,173 @@ async fn personal_workspaces_are_unique_persistent_and_optional() {
assert_eq!(group["bot"]["cwd"], "");
assert_eq!(group["bot"]["managedWorkspace"], false);
}
+
+// ---------- wire shape snapshot (docs/reference/compatibility.md) ----------
+
+/// 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, &current);
+ 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())
+ {
+ 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("python3").arg("--version").output().is_err() {
+ eprintln!("skipping: python3 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": format!("python3 '{}'", agent.display()),
+ "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;
+ host.call("respondPermission", json!({"entryId": card["id"], "optionId": "allow"})).await;
+ host.wait_for(&bot, |e| e["kind"] == "agent" && e["data"]["final"] == true).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, &current);
+ 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"
+ );
+}
diff --git a/host/tests/fixtures/wire-shape.json b/host/tests/fixtures/wire-shape.json
new file mode 100644
index 00000000..8b23c687
--- /dev/null
+++ b/host/tests/fixtures/wire-shape.json
@@ -0,0 +1,170 @@
+{
+ "minApp": "2.3.0",
+ "shapes": {
+ "event:bot": "object",
+ "event:bot.bot": "object",
+ "event:bot.bot.activity": "string",
+ "event:bot.bot.autoName": "bool",
+ "event:bot.bot.avatarColor": "string",
+ "event:bot.bot.avatarShape": "string",
+ "event:bot.bot.backend": "string",
+ "event:bot.bot.command": "string",
+ "event:bot.bot.computer": "bool",
+ "event:bot.bot.connectors": "array",
+ "event:bot.bot.createdAt": "number",
+ "event:bot.bot.cwd": "string",
+ "event:bot.bot.deleted": "bool",
+ "event:bot.bot.description": "string",
+ "event:bot.bot.hidden": "bool",
+ "event:bot.bot.id": "string",
+ "event:bot.bot.kind": "string",
+ "event:bot.bot.lastAt": "number",
+ "event:bot.bot.lastMessage": "string",
+ "event:bot.bot.managedWorkspace": "bool",
+ "event:bot.bot.members": "array",
+ "event:bot.bot.model": "null",
+ "event:bot.bot.name": "string",
+ "event:bot.bot.notify": "null",
+ "event:bot.bot.permission": "string",
+ "event:bot.bot.pinned": "bool",
+ "event:bot.bot.rev": "number",
+ "event:bot.bot.skills": "array",
+ "event:bot.bot.startedAt": "null",
+ "event:bot.bot.status": "string",
+ "event:bot.bot.unread": "number",
+ "event:bot.bot.workingChat": "null",
+ "event:bot.bot.workingThread": "null",
+ "event:bot.rev": "number",
+ "event:bot.type": "string",
+ "event:entry(agent)": "object",
+ "event:entry(agent).entry": "object",
+ "event:entry(agent).entry.botId": "string",
+ "event:entry(agent).entry.createdAt": "number",
+ "event:entry(agent).entry.data": "object",
+ "event:entry(agent).entry.data.author": "string",
+ "event:entry(agent).entry.data.final": "bool",
+ "event:entry(agent).entry.data.text": "string",
+ "event:entry(agent).entry.id": "string",
+ "event:entry(agent).entry.kind": "string",
+ "event:entry(agent).entry.rev": "number",
+ "event:entry(agent).entry.seq": "number",
+ "event:entry(agent).entry.threadId": "null",
+ "event:entry(agent).entry.turn": "number",
+ "event:entry(agent).entry.updatedAt": "number",
+ "event:entry(agent).rev": "number",
+ "event:entry(agent).type": "string",
+ "event:entry(permission)": "object",
+ "event:entry(permission).entry": "object",
+ "event:entry(permission).entry.botId": "string",
+ "event:entry(permission).entry.createdAt": "number",
+ "event:entry(permission).entry.data": "object",
+ "event:entry(permission).entry.data.author": "string",
+ "event:entry(permission).entry.data.command": "string",
+ "event:entry(permission).entry.data.cwd": "string",
+ "event:entry(permission).entry.data.detail": "string",
+ "event:entry(permission).entry.data.diffs": "array",
+ "event:entry(permission).entry.data.options": "array",
+ "event:entry(permission).entry.data.options[]": "object",
+ "event:entry(permission).entry.data.options[].kind": "string",
+ "event:entry(permission).entry.data.options[].name": "string",
+ "event:entry(permission).entry.data.options[].optionId": "string",
+ "event:entry(permission).entry.data.selected": "string",
+ "event:entry(permission).entry.data.status": "string",
+ "event:entry(permission).entry.data.title": "string",
+ "event:entry(permission).entry.data.toolKind": "string",
+ "event:entry(permission).entry.id": "string",
+ "event:entry(permission).entry.kind": "string",
+ "event:entry(permission).entry.rev": "number",
+ "event:entry(permission).entry.seq": "number",
+ "event:entry(permission).entry.threadId": "null",
+ "event:entry(permission).entry.turn": "number",
+ "event:entry(permission).entry.updatedAt": "number",
+ "event:entry(permission).rev": "number",
+ "event:entry(permission).type": "string",
+ "event:entry(plan)": "object",
+ "event:entry(plan).entry": "object",
+ "event:entry(plan).entry.botId": "string",
+ "event:entry(plan).entry.createdAt": "number",
+ "event:entry(plan).entry.data": "object",
+ "event:entry(plan).entry.data.author": "string",
+ "event:entry(plan).entry.data.entries": "array",
+ "event:entry(plan).entry.data.entries[]": "object",
+ "event:entry(plan).entry.data.entries[].content": "string",
+ "event:entry(plan).entry.data.entries[].priority": "string",
+ "event:entry(plan).entry.data.entries[].status": "string",
+ "event:entry(plan).entry.id": "string",
+ "event:entry(plan).entry.kind": "string",
+ "event:entry(plan).entry.rev": "number",
+ "event:entry(plan).entry.seq": "number",
+ "event:entry(plan).entry.threadId": "null",
+ "event:entry(plan).entry.turn": "number",
+ "event:entry(plan).entry.updatedAt": "number",
+ "event:entry(plan).rev": "number",
+ "event:entry(plan).type": "string",
+ "event:entry(tool)": "object",
+ "event:entry(tool).entry": "object",
+ "event:entry(tool).entry.botId": "string",
+ "event:entry(tool).entry.createdAt": "number",
+ "event:entry(tool).entry.data": "object",
+ "event:entry(tool).entry.data.author": "string",
+ "event:entry(tool).entry.data.diffs": "array",
+ "event:entry(tool).entry.data.diffs[]": "object",
+ "event:entry(tool).entry.data.diffs[].added": "number",
+ "event:entry(tool).entry.data.diffs[].isNew": "bool",
+ "event:entry(tool).entry.data.diffs[].patch": "string",
+ "event:entry(tool).entry.data.diffs[].path": "string",
+ "event:entry(tool).entry.data.diffs[].removed": "number",
+ "event:entry(tool).entry.data.diffs[].startLine": "number",
+ "event:entry(tool).entry.data.locations": "null",
+ "event:entry(tool).entry.data.output": "string",
+ "event:entry(tool).entry.data.status": "string",
+ "event:entry(tool).entry.data.title": "string",
+ "event:entry(tool).entry.data.toolCallId": "string",
+ "event:entry(tool).entry.data.toolKind": "string",
+ "event:entry(tool).entry.id": "string",
+ "event:entry(tool).entry.kind": "string",
+ "event:entry(tool).entry.rev": "number",
+ "event:entry(tool).entry.seq": "number",
+ "event:entry(tool).entry.threadId": "null",
+ "event:entry(tool).entry.turn": "number",
+ "event:entry(tool).entry.updatedAt": "number",
+ "event:entry(tool).rev": "number",
+ "event:entry(tool).type": "string",
+ "event:entry(user)": "object",
+ "event:entry(user).entry": "object",
+ "event:entry(user).entry.botId": "string",
+ "event:entry(user).entry.createdAt": "number",
+ "event:entry(user).entry.data": "object",
+ "event:entry(user).entry.data.attachments": "array",
+ "event:entry(user).entry.data.clientNonce": "string",
+ "event:entry(user).entry.data.status": "string",
+ "event:entry(user).entry.data.text": "string",
+ "event:entry(user).entry.id": "string",
+ "event:entry(user).entry.kind": "string",
+ "event:entry(user).entry.rev": "number",
+ "event:entry(user).entry.seq": "number",
+ "event:entry(user).entry.threadId": "null",
+ "event:entry(user).entry.turn": "number",
+ "event:entry(user).entry.updatedAt": "number",
+ "event:entry(user).rev": "number",
+ "event:entry(user).type": "string",
+ "event:hello": "object",
+ "event:hello.computerId": "string",
+ "event:hello.hostId": "string",
+ "event:hello.rev": "number",
+ "event:hello.type": "string",
+ "hello": "object",
+ "hello.boxKey": "string",
+ "hello.cloud": "null",
+ "hello.computerId": "string",
+ "hello.device": "string",
+ "hello.home": "string",
+ "hello.hostId": "string",
+ "hello.minApp": "string",
+ "hello.name": "string",
+ "hello.os": "string",
+ "hello.rev": "number",
+ "hello.signKey": "string",
+ "hello.version": "string"
+ }
+}