openmsg 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -13
- package/package.json +3 -3
- package/src/adapters/claude.mjs +2 -2
- package/src/adapters/codex.mjs +2 -2
- package/src/adapters/opencode.mjs +2 -2
- package/src/canonical.mjs +30 -0
- package/src/cli.mjs +702 -23
- package/src/deliver.mjs +24 -0
- package/src/device.mjs +211 -0
- package/src/directory.mjs +194 -0
- package/src/dirsync.mjs +224 -0
- package/src/gateway.mjs +556 -0
- package/src/identity.mjs +174 -0
- package/src/inbound.mjs +89 -0
- package/src/invite.mjs +102 -0
- package/src/limits.mjs +63 -0
- package/src/mailbox.mjs +6 -2
- package/src/outbox.mjs +47 -0
- package/src/permissions.mjs +56 -0
- package/src/published.mjs +77 -0
- package/src/registry.mjs +17 -0
- package/src/relay.mjs +446 -0
- package/src/relaylink.mjs +248 -0
- package/src/remote.mjs +347 -0
- package/src/seal.mjs +70 -0
- package/src/selfregistry.mjs +8 -2
- package/src/settings.mjs +31 -0
- package/src/wsframe.mjs +284 -0
- package/docs/spec/openmsg-0.1.md +0 -281
- package/docs/spec/openmsg-0.2-draft.md +0 -259
package/src/wsframe.mjs
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
// A small WebSocket, for the relay. It speaks the part of RFC 6455 that
|
|
2
|
+
// openmsg needs: the handshake, a text message, a ping, and a close.
|
|
3
|
+
//
|
|
4
|
+
// Both sides are here, and openmsg keeps no dependency. Node holds a
|
|
5
|
+
// WebSocket client, and that client refused a handshake that follows the
|
|
6
|
+
// standard, from this server and from a raw server that writes the same
|
|
7
|
+
// bytes. The cause stays unknown, so openmsg carries its own client.
|
|
8
|
+
//
|
|
9
|
+
// The frames follow RFC 6455. A client masks every frame that it sends, and a
|
|
10
|
+
// server masks none. A server that uses another library therefore works with
|
|
11
|
+
// this client.
|
|
12
|
+
import crypto from "node:crypto";
|
|
13
|
+
import net from "node:net";
|
|
14
|
+
import tls from "node:tls";
|
|
15
|
+
import { EventEmitter } from "node:events";
|
|
16
|
+
|
|
17
|
+
const GUID = "258EAFA5-E914-47DA-95CA-5AB0DC85B11F";
|
|
18
|
+
export const MAX_MESSAGE = 1024 * 1024;
|
|
19
|
+
|
|
20
|
+
const OP = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa };
|
|
21
|
+
|
|
22
|
+
export function accepts(request) {
|
|
23
|
+
return (
|
|
24
|
+
(request.headers.upgrade ?? "").toLowerCase() === "websocket" &&
|
|
25
|
+
typeof request.headers["sec-websocket-key"] === "string"
|
|
26
|
+
);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// The answer of the handshake. The key of the client and one fixed text give
|
|
30
|
+
// the value that the client compares.
|
|
31
|
+
export function handshake(socket, request) {
|
|
32
|
+
const accept = crypto
|
|
33
|
+
.createHash("sha1")
|
|
34
|
+
.update(request.headers["sec-websocket-key"] + GUID)
|
|
35
|
+
.digest("base64");
|
|
36
|
+
socket.write(
|
|
37
|
+
"HTTP/1.1 101 Switching Protocols\r\n" +
|
|
38
|
+
"Upgrade: websocket\r\n" +
|
|
39
|
+
"Connection: Upgrade\r\n" +
|
|
40
|
+
`Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
|
|
41
|
+
);
|
|
42
|
+
return new Connection(socket);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export class Connection extends EventEmitter {
|
|
46
|
+
// A server reads masked frames and writes plain ones. A client does the
|
|
47
|
+
// opposite. RFC 6455 gives no choice on either side.
|
|
48
|
+
constructor(socket, role = "server") {
|
|
49
|
+
super();
|
|
50
|
+
this.role = role;
|
|
51
|
+
this.socket = socket;
|
|
52
|
+
this.buffer = Buffer.alloc(0);
|
|
53
|
+
this.parts = [];
|
|
54
|
+
this.partsOpcode = null;
|
|
55
|
+
this.closed = false;
|
|
56
|
+
socket.on("data", (chunk) => this.read(chunk));
|
|
57
|
+
// "end" arrives when the other side sends FIN. A process that stops gives
|
|
58
|
+
// FIN, and without this line the connection looks alive until the next
|
|
59
|
+
// write fails.
|
|
60
|
+
socket.on("end", () => this.end());
|
|
61
|
+
socket.on("close", () => this.end());
|
|
62
|
+
socket.on("error", () => this.end());
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
read(chunk) {
|
|
66
|
+
this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
|
|
67
|
+
// A short buffer holds no whole frame yet. The next chunk continues it.
|
|
68
|
+
while (!this.closed) {
|
|
69
|
+
const frame = parse(this.buffer, this.role === "server");
|
|
70
|
+
if (!frame) return;
|
|
71
|
+
this.buffer = this.buffer.subarray(frame.size);
|
|
72
|
+
try {
|
|
73
|
+
this.handle(frame);
|
|
74
|
+
} catch (e) {
|
|
75
|
+
this.fail(1002, e.message);
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
handle(frame) {
|
|
82
|
+
if (frame.opcode === OP.close) {
|
|
83
|
+
this.write(OP.close, Buffer.alloc(0));
|
|
84
|
+
this.socket.end();
|
|
85
|
+
this.end();
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
if (frame.opcode === OP.ping) {
|
|
89
|
+
this.write(OP.pong, frame.payload);
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
if (frame.opcode === OP.pong) return;
|
|
93
|
+
|
|
94
|
+
if (frame.opcode === OP.continuation) {
|
|
95
|
+
if (this.partsOpcode === null) throw new Error("a continuation frame with no first frame");
|
|
96
|
+
} else {
|
|
97
|
+
if (this.partsOpcode !== null) throw new Error("a new message inside a message");
|
|
98
|
+
this.partsOpcode = frame.opcode;
|
|
99
|
+
}
|
|
100
|
+
this.parts.push(frame.payload);
|
|
101
|
+
const size = this.parts.reduce((n, p) => n + p.length, 0);
|
|
102
|
+
if (size > MAX_MESSAGE) throw new Error("the message is too big");
|
|
103
|
+
if (!frame.fin) return;
|
|
104
|
+
|
|
105
|
+
const body = Buffer.concat(this.parts);
|
|
106
|
+
const opcode = this.partsOpcode;
|
|
107
|
+
this.parts = [];
|
|
108
|
+
this.partsOpcode = null;
|
|
109
|
+
if (opcode === OP.text) this.emit("message", body.toString("utf8"));
|
|
110
|
+
else this.emit("binary", body);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// It gives false when the connection is gone. A caller that must know
|
|
114
|
+
// whether the other side got the text reads this answer.
|
|
115
|
+
send(text) {
|
|
116
|
+
if (this.closed || !this.socket.writable) return false;
|
|
117
|
+
return this.write(OP.text, Buffer.from(text, "utf8"));
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
ping() {
|
|
121
|
+
if (!this.closed) this.write(OP.ping, Buffer.alloc(0));
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
write(opcode, payload) {
|
|
125
|
+
const mask = this.role === "client";
|
|
126
|
+
const length = payload.length;
|
|
127
|
+
const flag = mask ? 0x80 : 0x00;
|
|
128
|
+
let header;
|
|
129
|
+
if (length < 126) {
|
|
130
|
+
header = Buffer.from([0x80 | opcode, flag | length]);
|
|
131
|
+
} else if (length <= 0xffff) {
|
|
132
|
+
header = Buffer.alloc(4);
|
|
133
|
+
header[0] = 0x80 | opcode;
|
|
134
|
+
header[1] = flag | 126;
|
|
135
|
+
header.writeUInt16BE(length, 2);
|
|
136
|
+
} else {
|
|
137
|
+
header = Buffer.alloc(10);
|
|
138
|
+
header[0] = 0x80 | opcode;
|
|
139
|
+
header[1] = flag | 127;
|
|
140
|
+
header.writeBigUInt64BE(BigInt(length), 2);
|
|
141
|
+
}
|
|
142
|
+
let body = payload;
|
|
143
|
+
if (mask) {
|
|
144
|
+
const key = crypto.randomBytes(4);
|
|
145
|
+
body = Buffer.allocUnsafe(length);
|
|
146
|
+
for (let i = 0; i < length; i += 1) body[i] = payload[i] ^ key[i & 3];
|
|
147
|
+
header = Buffer.concat([header, key]);
|
|
148
|
+
}
|
|
149
|
+
try {
|
|
150
|
+
this.socket.write(Buffer.concat([header, body]));
|
|
151
|
+
return true;
|
|
152
|
+
} catch {
|
|
153
|
+
this.end();
|
|
154
|
+
return false;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
fail(code, reason) {
|
|
159
|
+
if (this.closed) return;
|
|
160
|
+
const payload = Buffer.alloc(2 + Buffer.byteLength(reason));
|
|
161
|
+
payload.writeUInt16BE(code, 0);
|
|
162
|
+
payload.write(reason, 2);
|
|
163
|
+
this.write(OP.close, payload);
|
|
164
|
+
this.socket.end();
|
|
165
|
+
this.end();
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
close() {
|
|
169
|
+
if (this.closed) return;
|
|
170
|
+
this.write(OP.close, Buffer.alloc(0));
|
|
171
|
+
this.socket.end();
|
|
172
|
+
this.end();
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
end() {
|
|
176
|
+
if (this.closed) return;
|
|
177
|
+
this.closed = true;
|
|
178
|
+
this.emit("close");
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// One frame, or null when the buffer holds less than one frame.
|
|
183
|
+
function parse(buffer, expectMask) {
|
|
184
|
+
if (buffer.length < 2) return null;
|
|
185
|
+
const first = buffer[0];
|
|
186
|
+
const second = buffer[1];
|
|
187
|
+
const fin = (first & 0x80) !== 0;
|
|
188
|
+
const opcode = first & 0x0f;
|
|
189
|
+
const masked = (second & 0x80) !== 0;
|
|
190
|
+
let length = second & 0x7f;
|
|
191
|
+
let offset = 2;
|
|
192
|
+
if (length === 126) {
|
|
193
|
+
if (buffer.length < offset + 2) return null;
|
|
194
|
+
length = buffer.readUInt16BE(offset);
|
|
195
|
+
offset += 2;
|
|
196
|
+
} else if (length === 127) {
|
|
197
|
+
if (buffer.length < offset + 8) return null;
|
|
198
|
+
const big = buffer.readBigUInt64BE(offset);
|
|
199
|
+
if (big > BigInt(MAX_MESSAGE)) throw new Error("the frame is too big");
|
|
200
|
+
length = Number(big);
|
|
201
|
+
offset += 8;
|
|
202
|
+
}
|
|
203
|
+
if (length > MAX_MESSAGE) throw new Error("the frame is too big");
|
|
204
|
+
if (expectMask && !masked) throw new Error("a frame from a client must carry a mask");
|
|
205
|
+
if (!expectMask && masked) throw new Error("a frame from a server must carry no mask");
|
|
206
|
+
if (buffer.length < offset + (masked ? 4 : 0) + length) return null;
|
|
207
|
+
let payload;
|
|
208
|
+
if (masked) {
|
|
209
|
+
const mask = buffer.subarray(offset, offset + 4);
|
|
210
|
+
offset += 4;
|
|
211
|
+
payload = Buffer.allocUnsafe(length);
|
|
212
|
+
for (let i = 0; i < length; i += 1) payload[i] = buffer[offset + i] ^ mask[i & 3];
|
|
213
|
+
} else {
|
|
214
|
+
payload = Buffer.from(buffer.subarray(offset, offset + length));
|
|
215
|
+
}
|
|
216
|
+
return { fin, opcode, payload, size: offset + length };
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// --- the client ------------------------------------------------------------
|
|
220
|
+
|
|
221
|
+
// It opens a connection and it gives back a Connection. The answer of the
|
|
222
|
+
// server must hold the value that the key of this client gives, or the
|
|
223
|
+
// handshake fails.
|
|
224
|
+
// `tlsOptions` reaches node:tls. A team with its own certificate passes `ca`,
|
|
225
|
+
// and then the client trusts that certificate and no other one.
|
|
226
|
+
export function connect(url, { timeoutMs = 10_000, tls: tlsOptions = {} } = {}) {
|
|
227
|
+
const address = new URL(url);
|
|
228
|
+
const secure = address.protocol === "wss:";
|
|
229
|
+
const port = Number(address.port || (secure ? 443 : 80));
|
|
230
|
+
const key = crypto.randomBytes(16).toString("base64");
|
|
231
|
+
const accept = crypto.createHash("sha1").update(key + GUID).digest("base64");
|
|
232
|
+
|
|
233
|
+
return new Promise((resolve, reject) => {
|
|
234
|
+
const socket = secure
|
|
235
|
+
? tls.connect({ host: address.hostname, port, servername: address.hostname, ...tlsOptions })
|
|
236
|
+
: net.createConnection({ host: address.hostname, port });
|
|
237
|
+
const fail = (e) => {
|
|
238
|
+
socket.destroy();
|
|
239
|
+
reject(new Error(`the relay at ${url} did not answer: ${e.message}`));
|
|
240
|
+
};
|
|
241
|
+
const timer = setTimeout(() => fail(new Error("timeout")), timeoutMs);
|
|
242
|
+
socket.once("error", fail);
|
|
243
|
+
socket.on(secure ? "secureConnect" : "connect", () => {
|
|
244
|
+
socket.write(
|
|
245
|
+
`GET ${address.pathname || "/"} HTTP/1.1\r\n` +
|
|
246
|
+
`Host: ${address.host}\r\n` +
|
|
247
|
+
"Upgrade: websocket\r\n" +
|
|
248
|
+
"Connection: Upgrade\r\n" +
|
|
249
|
+
`Sec-WebSocket-Key: ${key}\r\n` +
|
|
250
|
+
"Sec-WebSocket-Version: 13\r\n\r\n",
|
|
251
|
+
);
|
|
252
|
+
});
|
|
253
|
+
let head = Buffer.alloc(0);
|
|
254
|
+
const onData = (chunk) => {
|
|
255
|
+
head = Buffer.concat([head, chunk]);
|
|
256
|
+
const end = head.indexOf("\r\n\r\n");
|
|
257
|
+
if (end === -1) {
|
|
258
|
+
if (head.length > 8192) fail(new Error("the answer of the handshake is too long"));
|
|
259
|
+
return;
|
|
260
|
+
}
|
|
261
|
+
const headers = head.subarray(0, end).toString("utf8");
|
|
262
|
+
socket.off("data", onData);
|
|
263
|
+
clearTimeout(timer);
|
|
264
|
+
socket.off("error", fail);
|
|
265
|
+
if (!/^HTTP\/1\.1 101/.test(headers)) {
|
|
266
|
+
socket.destroy();
|
|
267
|
+
reject(new Error(`the relay at ${url} answered "${headers.split("\r\n")[0]}"`));
|
|
268
|
+
return;
|
|
269
|
+
}
|
|
270
|
+
const given = headers.match(/sec-websocket-accept: (.+)/i)?.[1]?.trim();
|
|
271
|
+
if (given !== accept) {
|
|
272
|
+
socket.destroy();
|
|
273
|
+
reject(new Error(`the relay at ${url} answered with a wrong handshake value`));
|
|
274
|
+
return;
|
|
275
|
+
}
|
|
276
|
+
const connection = new Connection(socket, "client");
|
|
277
|
+
// The first frames can arrive in the same packet as the handshake.
|
|
278
|
+
const rest = head.subarray(end + 4);
|
|
279
|
+
if (rest.length > 0) connection.read(rest);
|
|
280
|
+
resolve(connection);
|
|
281
|
+
};
|
|
282
|
+
socket.on("data", onData);
|
|
283
|
+
});
|
|
284
|
+
}
|
package/docs/spec/openmsg-0.1.md
DELETED
|
@@ -1,281 +0,0 @@
|
|
|
1
|
-
# openmsg protocol, version 0.1
|
|
2
|
-
|
|
3
|
-
Status: draft. Date: 2026-09-19.
|
|
4
|
-
|
|
5
|
-
openmsg moves a text message from one AI coding agent to another on the same
|
|
6
|
-
machine. The message goes into a session that already runs, with its context.
|
|
7
|
-
|
|
8
|
-
This document defines the message format, the addresses, the rules for an
|
|
9
|
-
adapter, and the rules for trust. A program that follows this document can talk
|
|
10
|
-
to any other program that follows it.
|
|
11
|
-
|
|
12
|
-
## 1. Scope
|
|
13
|
-
|
|
14
|
-
In scope:
|
|
15
|
-
|
|
16
|
-
- One message with text, from one agent to one agent.
|
|
17
|
-
- Agents from different vendors, for example Claude Code and Codex.
|
|
18
|
-
- Agents on one machine, under one operating-system user.
|
|
19
|
-
- Discovery of the sessions that run now.
|
|
20
|
-
|
|
21
|
-
Not in scope for version 0.1:
|
|
22
|
-
|
|
23
|
-
- Messages between machines. Section 10 gives the path to A2A on HTTP.
|
|
24
|
-
- Messages between two people. Version 0.1 has one owner for all agents.
|
|
25
|
-
- Files, images, or other parts that are not text.
|
|
26
|
-
- A shared task list, a work queue, or a lock on a file.
|
|
27
|
-
|
|
28
|
-
## 2. Terms
|
|
29
|
-
|
|
30
|
-
| Term | Meaning |
|
|
31
|
-
|---|---|
|
|
32
|
-
| Agent | A program with a model that reads messages and does work, for example Claude Code. |
|
|
33
|
-
| Session | One conversation of an agent, with its own context. A session is the target of a message. |
|
|
34
|
-
| Address | The name of a session in openmsg, for example `codex:api-worker`. |
|
|
35
|
-
| Envelope | The JSON object that holds the message and its metadata. |
|
|
36
|
-
| Adapter | The code that knows how to find and reach the sessions of one vendor. |
|
|
37
|
-
| Delivery | The act of putting a message into a session that runs. |
|
|
38
|
-
| Mailbox | The file that keeps the messages of one address. |
|
|
39
|
-
|
|
40
|
-
## 3. Addresses
|
|
41
|
-
|
|
42
|
-
An address has two parts, divided by a colon:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
<vendor>:<name>
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
- `vendor` is a lowercase name of the agent program: `claude`, `codex`,
|
|
49
|
-
`opencode`, `gemini`, `cursor`.
|
|
50
|
-
- `name` is the name of the session. It comes from the vendor when the vendor
|
|
51
|
-
gives one. If the vendor gives no name, the adapter makes one from the
|
|
52
|
-
directory of the session and the last four characters of the session id.
|
|
53
|
-
|
|
54
|
-
Rules:
|
|
55
|
-
|
|
56
|
-
1. An address must be unique among the sessions that run now.
|
|
57
|
-
2. A sender can give a name without the vendor. The implementation then looks
|
|
58
|
-
in all vendors.
|
|
59
|
-
3. If more than one session answers to the name, the implementation must refuse
|
|
60
|
-
the message and must show the addresses that match.
|
|
61
|
-
4. An implementation must accept a full session id in place of the name.
|
|
62
|
-
|
|
63
|
-
## 4. The envelope
|
|
64
|
-
|
|
65
|
-
The envelope uses the field names of the A2A `Message` object. The extra fields
|
|
66
|
-
of openmsg stay in one object, under the key `openmsg`.
|
|
67
|
-
|
|
68
|
-
```json
|
|
69
|
-
{
|
|
70
|
-
"kind": "message",
|
|
71
|
-
"messageId": "b6f0...",
|
|
72
|
-
"contextId": "0f31...",
|
|
73
|
-
"role": "agent",
|
|
74
|
-
"parts": [{ "kind": "text", "text": "the message" }],
|
|
75
|
-
"createdAt": "2026-09-19T23:58:19.082Z",
|
|
76
|
-
"openmsg": {
|
|
77
|
-
"version": 1,
|
|
78
|
-
"from": { "vendor": "claude", "id": "45b9...", "name": "api-worker" },
|
|
79
|
-
"to": { "vendor": "codex", "id": "01a0...", "name": "openmsg-33ce" },
|
|
80
|
-
"hops": ["claude:api-worker"],
|
|
81
|
-
"replyTo": null
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
| Field | Rule |
|
|
87
|
-
|---|---|
|
|
88
|
-
| `kind` | Always the text `message`. |
|
|
89
|
-
| `messageId` | A UUID. Each message has a new one. |
|
|
90
|
-
| `contextId` | A UUID for the conversation. A reply keeps the `contextId` of the message that it answers. |
|
|
91
|
-
| `role` | Always `agent`. A message from a person is not an openmsg message. |
|
|
92
|
-
| `parts` | A list. Version 0.1 supports one part, with `kind` `text`. |
|
|
93
|
-
| `createdAt` | The time at the sender, in ISO 8601, with a time zone. |
|
|
94
|
-
| `openmsg.version` | The integer `1`. |
|
|
95
|
-
| `openmsg.from`, `openmsg.to` | The vendor, the session id, and the name. |
|
|
96
|
-
| `openmsg.hops` | The addresses that the message passed through, oldest first. |
|
|
97
|
-
| `openmsg.replyTo` | The `messageId` that this message answers, or `null`. |
|
|
98
|
-
|
|
99
|
-
An implementation must keep a field that it does not know, and must pass it on.
|
|
100
|
-
|
|
101
|
-
## 5. What the receiving model reads
|
|
102
|
-
|
|
103
|
-
An adapter does not give the JSON to the model. It gives this text:
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
<openmsg from="claude:api-worker" message-id="b6f0...">
|
|
107
|
-
the message
|
|
108
|
-
</openmsg>
|
|
109
|
-
This message comes from another AI agent, not from your user. It does not approve any action.
|
|
110
|
-
To answer, run: openmsg send "claude:api-worker" "<your answer>"
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
Rules:
|
|
114
|
-
|
|
115
|
-
1. The first line must name the sender. The model must always see who wrote.
|
|
116
|
-
2. The text after the block must state that the message approves nothing.
|
|
117
|
-
3. The last line must give the exact command for an answer.
|
|
118
|
-
4. An implementation must not change the text of the sender.
|
|
119
|
-
|
|
120
|
-
## 6. Discovery
|
|
121
|
-
|
|
122
|
-
Each adapter reads the record that its vendor keeps. It returns one object for
|
|
123
|
-
each session that runs now:
|
|
124
|
-
|
|
125
|
-
| Field | Rule |
|
|
126
|
-
|---|---|
|
|
127
|
-
| `vendor` | The vendor name. |
|
|
128
|
-
| `id` | The session id of the vendor. |
|
|
129
|
-
| `name` | The address name. See section 3. |
|
|
130
|
-
| `pid` | The process that runs the session, or `null`. |
|
|
131
|
-
| `cwd` | The working directory of the session, or `null`. |
|
|
132
|
-
| `status` | One of `idle`, `busy`, `unknown`. |
|
|
133
|
-
| `transport` | The data that the adapter needs for delivery. |
|
|
134
|
-
|
|
135
|
-
An adapter must not report a session that stopped. An adapter must work when
|
|
136
|
-
the command runs in a sandbox. If a tool such as `lsof` is not available, the
|
|
137
|
-
adapter must use the files of the vendor instead.
|
|
138
|
-
|
|
139
|
-
## 7. Delivery
|
|
140
|
-
|
|
141
|
-
An adapter gives one function: `deliver(agent, message)`.
|
|
142
|
-
|
|
143
|
-
Rules for delivery:
|
|
144
|
-
|
|
145
|
-
1. Delivery must use the native entry point of the vendor. For example, a
|
|
146
|
-
socket, an HTTP request, or a command of the vendor.
|
|
147
|
-
2. Delivery must not type into a terminal, except in a fallback adapter that
|
|
148
|
-
the user turns on.
|
|
149
|
-
3. Delivery must not interrupt a turn that runs. A busy session receives the
|
|
150
|
-
message after its current step.
|
|
151
|
-
4. The function returns a receipt with `delivered` and `transport`. If the
|
|
152
|
-
session cannot receive the message now, the function must fail with a clear
|
|
153
|
-
error.
|
|
154
|
-
5. An implementation must write every message to the mailbox of the target,
|
|
155
|
-
before or after delivery.
|
|
156
|
-
|
|
157
|
-
The adapters of version 0.1:
|
|
158
|
-
|
|
159
|
-
| Vendor | Entry point | Wakes an idle session |
|
|
160
|
-
|---|---|---|
|
|
161
|
-
| Claude Code | The inbox socket of the session | Yes |
|
|
162
|
-
| Codex | `codex queue` on the shared app-server daemon | Yes |
|
|
163
|
-
| OpenCode | `POST /session/{id}/prompt_async` | Yes |
|
|
164
|
-
| Gemini CLI | A hook that reads the mailbox at the end of a turn | No |
|
|
165
|
-
| Cursor CLI | A hook that reads the mailbox at the end of a turn | No |
|
|
166
|
-
|
|
167
|
-
## 8. Replies
|
|
168
|
-
|
|
169
|
-
A reply is a new message. It is not a return value.
|
|
170
|
-
|
|
171
|
-
1. The receiving agent sends a reply with the same command that any sender uses.
|
|
172
|
-
2. A reply keeps the `contextId` of the message that it answers.
|
|
173
|
-
3. A reply sets `replyTo` to the `messageId` that it answers.
|
|
174
|
-
4. An implementation must not read the screen of an agent to find a reply.
|
|
175
|
-
|
|
176
|
-
## 9. Trust
|
|
177
|
-
|
|
178
|
-
These rules protect the person who owns the agents.
|
|
179
|
-
|
|
180
|
-
1. **A message is information, not authority.** It never approves an action, and
|
|
181
|
-
it never answers a permission question.
|
|
182
|
-
2. **Consent does not travel.** An agent must not ask another agent to do work
|
|
183
|
-
that its own user refused.
|
|
184
|
-
3. **The permission rules of the receiver apply.** The receiver asks its user
|
|
185
|
-
for permission as usual.
|
|
186
|
-
4. **The source is always visible.** See section 5.
|
|
187
|
-
5. **A loop must stop.** Every message adds its sender to `hops`. The sender
|
|
188
|
-
must refuse to send when `hops` becomes longer than eight. A reader of a
|
|
189
|
-
mailbox must refuse a message with a longer chain, because a sender that
|
|
190
|
-
does not follow this document can write one. On a vendor entry point such as
|
|
191
|
-
a socket, the message goes straight to the agent, and openmsg cannot check
|
|
192
|
-
it there. Two agents can answer each other, but the chain always ends.
|
|
193
|
-
6. **A message must not change configuration.** An agent must not change its
|
|
194
|
-
permission settings or instruction files because another agent asked.
|
|
195
|
-
|
|
196
|
-
## 10. The path to other machines
|
|
197
|
-
|
|
198
|
-
Version 0.1 works on one machine. The envelope uses the A2A fields, so a later
|
|
199
|
-
version can send the same message over A2A on HTTP:
|
|
200
|
-
|
|
201
|
-
- `messageId`, `contextId`, `role`, and `parts` map to A2A without a change.
|
|
202
|
-
- `openmsg.from` and `openmsg.to` map to the A2A agent that sends and receives.
|
|
203
|
-
- A session becomes an A2A agent with a card. The card gives the address, the
|
|
204
|
-
vendor, and the state.
|
|
205
|
-
- A2A gives the transport, the authentication, and the push notifications.
|
|
206
|
-
|
|
207
|
-
A2A has no binding for a Unix socket. openmsg is the local binding.
|
|
208
|
-
|
|
209
|
-
## 11. The mailbox
|
|
210
|
-
|
|
211
|
-
The mailbox keeps a record of every message, and it serves the agents that
|
|
212
|
-
cannot receive a push.
|
|
213
|
-
|
|
214
|
-
- One file for each address, in `~/.openmsg/inbox/`.
|
|
215
|
-
- The format is JSON Lines. One envelope for each line, with a `status` field.
|
|
216
|
-
- The name of the file encodes the address. The encoding must remove every
|
|
217
|
-
character that an operating system refuses, and two addresses must never give
|
|
218
|
-
the same name.
|
|
219
|
-
- `status` is one of:
|
|
220
|
-
- `queued`: the message waits for an agent that reads the mailbox.
|
|
221
|
-
- `delivered`: an adapter pushed the message into the live session.
|
|
222
|
-
- `read`: the agent read the message with `openmsg inbox`.
|
|
223
|
-
|
|
224
|
-
### 11.1 What a reader returns
|
|
225
|
-
|
|
226
|
-
`openmsg inbox` serves an agent and a hook. Every line goes to the standard
|
|
227
|
-
output, because a hook can read that stream alone.
|
|
228
|
-
|
|
229
|
-
With `--json`, the output is one object:
|
|
230
|
-
|
|
231
|
-
```json
|
|
232
|
-
{
|
|
233
|
-
"messages": [{ "kind": "message", "...": "the envelopes" }],
|
|
234
|
-
"refused": [{ "messageId": "...", "from": "codex:x", "hops": 50, "reason": "more than 8 hops" }]
|
|
235
|
-
}
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
A reader marks only the messages in `messages` as read. A refused message keeps
|
|
239
|
-
its state, so the next read reports it again.
|
|
240
|
-
|
|
241
|
-
## 12. Identity of the sender
|
|
242
|
-
|
|
243
|
-
An implementation finds the sender in this order:
|
|
244
|
-
|
|
245
|
-
1. The variable `OPENMSG_SELF`, when the user sets it.
|
|
246
|
-
2. The variable of the vendor. Claude Code gives
|
|
247
|
-
`CLAUDE_CODE_MESSAGING_SOCKET`. Codex gives `CODEX_THREAD_ID`.
|
|
248
|
-
3. The process tree. If a parent process is an agent, the implementation uses
|
|
249
|
-
the session of that process.
|
|
250
|
-
4. The working directory. If one session runs in this directory, and the vendor
|
|
251
|
-
is known, the implementation uses that session.
|
|
252
|
-
|
|
253
|
-
If two sessions match, the implementation must refuse to send, and must tell the
|
|
254
|
-
user to set `OPENMSG_SELF`.
|
|
255
|
-
|
|
256
|
-
## 13. Conformance
|
|
257
|
-
|
|
258
|
-
An implementation of version 0.1 must:
|
|
259
|
-
|
|
260
|
-
1. Read and write the envelope of section 4.
|
|
261
|
-
2. Render a message as section 5 defines.
|
|
262
|
-
3. Give `list`, `send`, `inbox`, and `whoami`.
|
|
263
|
-
4. Keep the mailbox of section 11.
|
|
264
|
-
5. Obey the trust rules of section 9.
|
|
265
|
-
|
|
266
|
-
State of this implementation, 2026-09-19:
|
|
267
|
-
|
|
268
|
-
| Rule | State |
|
|
269
|
-
|---|---|
|
|
270
|
-
| Envelope, rendering, addresses | Done |
|
|
271
|
-
| Claude Code and Codex adapters | Done, tested with live sessions |
|
|
272
|
-
| OpenCode adapter | Delivery tested against a live server. A reply needs a model account |
|
|
273
|
-
| Cursor and Gemini adapters | Written as a hook, tested with fixtures. A live test needs an account |
|
|
274
|
-
| `replyTo` and the `contextId` of a reply | Done. `openmsg send ... --reply-to <id>` keeps the conversation. |
|
|
275
|
-
| Hop limit | Done. A reply adds one hop, and the chain stops after eight. |
|
|
276
|
-
| Status `delivered` and `read` in the mailbox | **Partly done.** The sender writes `sent` only. |
|
|
277
|
-
|
|
278
|
-
## 14. Version
|
|
279
|
-
|
|
280
|
-
This document is version 0.1. `openmsg.version` is the integer `1`. A change
|
|
281
|
-
that breaks a reader gets a new integer.
|