Building on itWrite a client
Write a client
Connect to the app endpoint, pair a device, list chats, send a prompt, and receive replies, in about seventy lines of JavaScript.
This page is for anyone building another client of Vendetta’s app endpointApp endpoint. The private address your devices connect to. It listens on loopback until you publish it.: a watch app, a desktop widget, a bot of your own. It covers the first hour; App protocol is the full contract.
The web client and the iPhone app are clients of the same endpoint, so anything they do, yours can.
The endpoint
Section titled “The endpoint”The app plugin serves one WebSocket, /v1, on a loopback address: 127.0.0.1:8743 unless [plugins.app] listen names another. Whoever runs Vendetta publishes it with TLS, so a device connects to an address such as:
wss://workstation.example.ts.net:8743/v1On the computer itself, ws://127.0.0.1:8743/v1 works without a proxy.
Every frame is a JSON text message. The server sends each frame of 2 KiB or more as a binary message instead: the same JSON, deflated (RFC 1951, no header). A client must handle both.
A client
Section titled “A client”Save this as client.mjs. It needs Node 22 or newer, or Bun, and nothing else:
// A minimal client of the app endpoint. Run with Node 22+ or Bun:
// node client.mjs wss://workstation.example.ts.net:8743/v1 PAIRING-CODE
import { inflateRawSync } from "node:zlib";
import { readFileSync, writeFileSync, existsSync } from "node:fs";
const [url, code] = process.argv.slice(2);
const saved = existsSync("device.json") ? JSON.parse(readFileSync("device.json", "utf8")) : {};
const topics = new Map();
const socket = new WebSocket(url);
socket.binaryType = "arraybuffer";
const send = (frame) => socket.send(JSON.stringify(frame));
socket.onopen = () => {
// The first frame, within 10 seconds: a pairing code once, the token ever after.
if (saved.token) send({ type: "hello", token: saved.token, epoch: saved.epoch, cursor: String(saved.seq ?? 0) });
else send({ type: "pair", code, device_name: "Example client" });
};
socket.onmessage = ({ data }) => {
// Frames of 2 KiB or more arrive binary: the JSON, raw-deflated.
const text = typeof data === "string" ? data : inflateRawSync(Buffer.from(data)).toString();
const frame = JSON.parse(text);
for (const event of frame.type === "events" ? frame.events : [frame]) apply(event);
if (frame.seq) remember({ seq: frame.seq });
};
function remember(values) {
Object.assign(saved, values);
writeFileSync("device.json", JSON.stringify(saved), { mode: 0o600 });
}
function apply(frame) {
switch (frame.type) {
case "paired": // Shown once: keep the token private.
return remember({ token: frame.token });
case "snapshot":
remember({ epoch: frame.epoch });
topics.clear();
for (const topic of frame.topics) topics.set(topic.id, topic);
for (const topic of topics.values()) console.log(topic.state, topic.title);
return prompt();
case "welcome":
return console.log("caught up from", saved.seq);
case "topic":
return topics.set(frame.topic.id, frame.topic);
case "topic_deleted":
return topics.delete(frame.topic);
case "message":
case "edit":
if (frame.message.from === "agent" && frame.message.format === "markdown")
console.log(topics.get(frame.message.topic)?.title, "\n", frame.message.text);
return;
case "sent":
return console.log("sent as", frame.id);
case "send_failed":
return console.log("not sent:", frame.message);
case "error":
return console.log("refused:", frame.code);
}
}
// Send one prompt to the first idle chat.
function prompt() {
const idle = [...topics.values()].find((topic) => topic.state === "idle");
if (idle) send({ type: "send", client_id: crypto.randomUUID(), topic: idle.id, text: "What changed today?" });
}Get a pairing code on the computer that runs Vendetta, then run the client with it:
vendetta app pair
node client.mjs wss://workstation.example.ts.net:8743/v1 CODEThe first run pairs and writes device.json. Later runs need no code:
node client.mjs wss://workstation.example.ts.net:8743/v1In a browser, the same code works with DecompressionStream("deflate-raw") in place of node:zlib, and the token kept wherever the page keeps its secrets.
Connect and pair
Section titled “Connect and pair”The first frame must arrive within 10 seconds, and is one of two:
| Frame | Reply |
|---|---|
{"type":"pair","code":"…","device_name":"…"} |
{"type":"paired","device":"…","token":"…"}, then a snapshot |
{"type":"hello","token":"…","epoch":"…","cursor":"…"} |
welcome, then the events missed, or a snapshot |
A pairing code works once and lasts 10 minutes. The token is shown once; the server keeps only its SHA-256 digest. A failure replies {"type":"error","code":"unauthorized"|"pairing"|"busy"} and closes.
vendetta app devices lists paired devices, and vendetta app revoke removes one.
Stay in step
Section titled “Stay in step”A snapshot carries epoch, seq, the projects as groups, the chats as topics, and recent messages. Every later change is an event with a higher seq. Several at once arrive as one events {seq, events} frame.
Keep the last epoch and seq, and send them in the next hello. The server replays what was missed, or sends a new snapshot when it restarted or its log no longer reaches the cursor. Merge a snapshot into what the client holds by message id.
Some frames carry no seq and are not replayed, such as ui, the plugins’ contributions.
The server pings every 20 seconds and closes a connection that sends nothing for 70. A WebSocket library that answers pings keeps the connection open.
List chats
Section titled “List chats”Each topic is one agent’s chat:
| Field | Holds |
|---|---|
id |
What requests name the chat by |
title |
The agent’s name |
state |
running, idle, question, approval, starting, unknown, or exited |
group |
Its project |
master, manager |
Whether it is the Master, or leads a team |
muted, kept, ephemeral |
What the owner set on it |
A topic event replaces a chat; topic_deleted removes one.
{"type":"send","client_id":"7c1f…","topic":"42","text":"What changed today?"}client_id is the client’s own id for the message. The reply is sent {client_id, id} or send_failed {client_id, message}. An outcome {topic, id, outcome} event then says accepted or rejected; a refused message’s reason follows in a second outcome.
An accepted prompt’s receipt moves from waiting to read, or to dropped when the agent will never read it. Each change arrives as an edit.
A message the server took carries the client_id it was sent with. When a send gets no reply, reconnect and look for that id before sending the text again.
Receive
Section titled “Receive”| Event | Means |
|---|---|
message {message} |
A new message |
edit {message} |
A full message that replaces the one with its id |
progress {…} |
A running turn grew; see Synchronization for how to apply it |
messages {messages} |
A chat’s history from its transcript, added at once |
A message has id, topic, from (agent or owner), ts, kind, text, and format. Final replies are markdown, and nothing else is. A running turn is one progress message that the server keeps changing.
A question arrives as a message with format: "question" and buttons. Answer by pressing one:
{"type":"press","topic":"42","message":"1017","data":"…"}data is the button’s own data, sent back unchanged. A press is accepted only for a button currently on that exact message.
Where to go next
Section titled “Where to go next”- Photos, videos, audio, and uploads: Photos, videos, and audio.
- Starting, stopping, and resuming agents: the
agentsrequest, under Agents. - Schedules, tasks, and the queue: their sections in the same page.
- Types:
crates/app-wire/src/lib.rsdefines every payload and generates the web client’sweb/src/kit/wire.tsand the iOS kit’sWire.swift. - Fixtures:
fixtures/app/holds frame sequences with the state a client must reach. - A scripted endpoint to develop against:
bun mock/server.tsinweb/.