openmsg 0.1.0 → 0.3.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 +83 -5
- package/src/adapters/opencode.mjs +2 -2
- package/src/canonical.mjs +30 -0
- package/src/cli.mjs +702 -23
- package/src/deliver.mjs +32 -0
- package/src/device.mjs +211 -0
- package/src/directory.mjs +194 -0
- package/src/dirsync.mjs +224 -0
- package/src/envelope.mjs +51 -8
- 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 +13 -3
- 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 +352 -0
- package/src/seal.mjs +70 -0
- package/src/selfregistry.mjs +8 -2
- package/src/settings.mjs +31 -0
- package/src/wsframe.mjs +288 -0
- package/docs/spec/openmsg-0.1.md +0 -281
- package/docs/spec/openmsg-0.2-draft.md +0 -259
package/README.md
CHANGED
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
# openmsg
|
|
2
2
|
|
|
3
|
-
Messages between AI coding agents of different vendors, on one machine
|
|
3
|
+
Messages between AI coding agents of different vendors, on one machine or
|
|
4
|
+
between two people.
|
|
4
5
|
|
|
5
6
|
A Claude Code session can send a message to a Codex session. An OpenCode session
|
|
6
7
|
can answer a Claude Code session. The message goes into the session that already
|
|
7
8
|
runs, with its context, and not into a new process.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
Two people who work on one project can do the same across their machines. Those
|
|
11
|
+
messages are sealed end to end, and the server that carries them cannot read
|
|
12
|
+
one.
|
|
13
|
+
|
|
14
|
+
Status: version 0.2 is on npm. Version 0.1, between the agents of one
|
|
15
|
+
person, works and is tested with live sessions. Version 0.2, between two
|
|
16
|
+
people, passes the fourteen acceptance cases of its specification, and the
|
|
17
|
+
live tests on one machine. No team has run it across the internet yet.
|
|
10
18
|
|
|
11
19
|
## How it works
|
|
12
20
|
|
|
@@ -34,6 +42,47 @@ An address is `<vendor>:<name>`, for example `claude:api-worker`.
|
|
|
34
42
|
A reply is a new message. The receiving agent answers with `openmsg send`. No
|
|
35
43
|
program reads the screen of another program.
|
|
36
44
|
|
|
45
|
+
## The agents of another person
|
|
46
|
+
|
|
47
|
+
Version 0.2 adds one more step: an address with an owner, such as
|
|
48
|
+
`claude:api-worker@alice`.
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
openmsg id create --label alice # a signing key and a sealing key
|
|
52
|
+
openmsg invite create --project web # a token for the other person
|
|
53
|
+
openmsg invite accept <token> --fingerprint "A1B2 ..."
|
|
54
|
+
openmsg publish claude:api-worker # let the project reach this session
|
|
55
|
+
openmsg gateway start --relay <url> # the one process that the network reaches
|
|
56
|
+
openmsg send claude:reviewer@bob "the migration drops a column"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
What holds:
|
|
60
|
+
|
|
61
|
+
- **Nothing is published by default.** A session is reachable after
|
|
62
|
+
`openmsg publish`, and only in the project that the owner names.
|
|
63
|
+
- **A new sender waits.** The first message of a person stays outside the
|
|
64
|
+
model until the owner runs `openmsg accept`. Membership of a project is not
|
|
65
|
+
permission to write into a session.
|
|
66
|
+
- **Every message is sealed end to end.** The relay carries bytes that it
|
|
67
|
+
cannot read. It learns who writes to whom, when, and in which project,
|
|
68
|
+
because it needs that to route. The product does not pretend otherwise.
|
|
69
|
+
The relay speaks TLS, and it refuses to listen on any address but this
|
|
70
|
+
machine without a certificate.
|
|
71
|
+
- **A signature proves the person, and a fingerprint proves the key.** Two
|
|
72
|
+
people compare a fingerprint out of band before the first message.
|
|
73
|
+
- **Each machine holds its own key.** The owner key stays on one machine and
|
|
74
|
+
signs a delegation for the others. One stolen machine costs one delegation,
|
|
75
|
+
and the identity of that person holds. Several machines of one person work
|
|
76
|
+
at the same time, and a message is sealed for the machine that holds the
|
|
77
|
+
session.
|
|
78
|
+
- **A message never carries authority.** The receiving agent works inside the
|
|
79
|
+
permissions that its own user already gave it.
|
|
80
|
+
|
|
81
|
+
The states of a message are `queued`, `held`, `adapter-accepted`,
|
|
82
|
+
`agent-acknowledged`, `replied`, `refused`, and `expired`. A write to a socket
|
|
83
|
+
is not a read by a model: only an event from the agent gives
|
|
84
|
+
`agent-acknowledged`.
|
|
85
|
+
|
|
37
86
|
## Message format
|
|
38
87
|
|
|
39
88
|
The envelope uses the field names of the A2A standard (`messageId`, `contextId`,
|
|
@@ -58,9 +107,11 @@ git clone https://github.com/marciob/openmsg.git && cd openmsg
|
|
|
58
107
|
node src/cli.mjs list
|
|
59
108
|
```
|
|
60
109
|
|
|
61
|
-
Node 22 or later. No dependencies
|
|
110
|
+
Node 22 or later. No dependencies, and none for the relay either: the
|
|
111
|
+
WebSocket of `src/wsframe.mjs` is both sides of RFC 6455 in one small file.
|
|
62
112
|
|
|
63
|
-
Run the tests with `node --test`.
|
|
113
|
+
Run the tests with `node --test`. Seventy-eight of them, and they need no
|
|
114
|
+
account: they run two gateways and a relay on this machine, as two people.
|
|
64
115
|
|
|
65
116
|
An agent with no push entry point needs its hook:
|
|
66
117
|
|
|
@@ -68,18 +119,30 @@ An agent with no push entry point needs its hook:
|
|
|
68
119
|
openmsg install --hooks
|
|
69
120
|
```
|
|
70
121
|
|
|
71
|
-
##
|
|
122
|
+
## How each vendor lets a message in
|
|
123
|
+
|
|
124
|
+
[`research/2026-09-19-transport-research.md`](https://github.com/marciob/openmsg/blob/main/research/2026-09-19-transport-research.md)
|
|
125
|
+
is the work that produced this design. It tests every way one program can put a message into a running
|
|
126
|
+
agent: typing into the terminal of another program, the native entry point of
|
|
127
|
+
each vendor, subprocess calls, mailboxes, A2A, and ACP. Each claim carries a
|
|
128
|
+
label: `[local]` for a fact that a test on one Mac verified, `[docs]` for a
|
|
129
|
+
fact from the vendor, and `[not verified]` for a fact from a source without a
|
|
130
|
+
test.
|
|
72
131
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
132
|
+
The short answer: typing into a terminal is possible and bad, and each of the
|
|
133
|
+
four main agents has an official way to take a message while it runs.
|
|
134
|
+
|
|
135
|
+
## Spec
|
|
77
136
|
|
|
78
|
-
|
|
137
|
+
- [`spec/openmsg-0.1.md`](https://github.com/marciob/openmsg/blob/main/spec/openmsg-0.1.md):
|
|
138
|
+
the protocol for the agents of one person on one machine.
|
|
139
|
+
- [`spec/openmsg-0.2-draft.md`](https://github.com/marciob/openmsg/blob/main/spec/openmsg-0.2-draft.md):
|
|
140
|
+
the agents of different people on one project. The identity of an owner,
|
|
141
|
+
the sealed envelope, the gateway, the relay, the seven states of a message,
|
|
142
|
+
and the trust rules. Every rule of 0.1 still holds.
|
|
79
143
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
mailboxes, A2A, and ACP.
|
|
144
|
+
The code implements both, and the fourteen acceptance cases of section 11 of
|
|
145
|
+
0.2 pass as tests.
|
|
83
146
|
|
|
84
147
|
## License
|
|
85
148
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "openmsg",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Messages between AI coding agents of different vendors, on one machine.",
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Messages between AI coding agents of different vendors, on one machine or between two people, sealed end to end.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"openmsg": "src/cli.mjs"
|
|
@@ -11,7 +11,6 @@
|
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
13
|
"src",
|
|
14
|
-
"docs/spec",
|
|
15
14
|
"README.md",
|
|
16
15
|
"LICENSE"
|
|
17
16
|
],
|
|
@@ -34,6 +33,7 @@
|
|
|
34
33
|
"gemini-cli",
|
|
35
34
|
"agent-communication",
|
|
36
35
|
"a2a",
|
|
36
|
+
"end-to-end-encryption",
|
|
37
37
|
"cli",
|
|
38
38
|
"interoperability"
|
|
39
39
|
],
|
package/src/adapters/claude.mjs
CHANGED
|
@@ -7,14 +7,14 @@
|
|
|
7
7
|
import net from "node:net";
|
|
8
8
|
import { render } from "../envelope.mjs";
|
|
9
9
|
|
|
10
|
-
export async function deliver(agent, message, { token } = {}) {
|
|
10
|
+
export async function deliver(agent, message, { token, text = null } = {}) {
|
|
11
11
|
const socketPath = agent.transport.path;
|
|
12
12
|
const lines = [];
|
|
13
13
|
if (token) lines.push(JSON.stringify({ type: "auth", token }));
|
|
14
14
|
lines.push(
|
|
15
15
|
JSON.stringify({
|
|
16
16
|
type: "user",
|
|
17
|
-
message: { role: "user", content: render(message) },
|
|
17
|
+
message: { role: "user", content: text ?? render(message) },
|
|
18
18
|
}),
|
|
19
19
|
);
|
|
20
20
|
|
package/src/adapters/codex.mjs
CHANGED
|
@@ -1,26 +1,104 @@
|
|
|
1
1
|
// Adapter: Codex CLI.
|
|
2
2
|
// The Codex user interface runs on an app-server. When the shared daemon runs,
|
|
3
|
-
// every session connects to it, and
|
|
4
|
-
//
|
|
3
|
+
// every session connects to it, and a message goes into the queue of a session.
|
|
4
|
+
// Codex reads the message at the end of its current turn.
|
|
5
5
|
// The daemon must run before the user starts Codex.
|
|
6
|
+
//
|
|
7
|
+
// The first path is the socket of the daemon: WebSocket over a Unix socket, and
|
|
8
|
+
// JSON-RPC inside. It lets the message mark the text of the sender as a text
|
|
9
|
+
// element, which Codex draws in its accent color. A text element is only for
|
|
10
|
+
// the display: the model reads the text and not the element.
|
|
11
|
+
// Source: openai/codex, codex-rs/tui/src/session_queue_commands.rs and
|
|
12
|
+
// codex-rs/core/src/session/mod.rs ("UI-only `text_elements`").
|
|
13
|
+
// That protocol is internal to Codex. When the socket path fails before the
|
|
14
|
+
// message leaves, the adapter uses `codex queue`, which is public.
|
|
6
15
|
import { execFile } from "node:child_process";
|
|
7
16
|
import { promisify } from "node:util";
|
|
17
|
+
import { randomUUID } from "node:crypto";
|
|
18
|
+
import os from "node:os";
|
|
19
|
+
import path from "node:path";
|
|
8
20
|
import { render } from "../envelope.mjs";
|
|
21
|
+
import * as ws from "../wsframe.mjs";
|
|
9
22
|
|
|
10
23
|
const run = promisify(execFile);
|
|
24
|
+
const RPC_TIMEOUT_MS = 5000;
|
|
11
25
|
|
|
12
|
-
|
|
26
|
+
function socketPath() {
|
|
27
|
+
const home = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
|
|
28
|
+
return path.join(home, "app-server-control", "app-server-control.sock");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export async function deliver(agent, message, { text = null, highlight = null } = {}) {
|
|
32
|
+
const body = text ?? render(message);
|
|
33
|
+
const out = await queueOverSocket(agent.id, body, highlight);
|
|
34
|
+
if (out) return out;
|
|
35
|
+
return queueOverCli(agent.id, body);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// It gives null when nothing went into the queue, so the caller can use the
|
|
39
|
+
// command line. A failure after the queue request left is an error: the message
|
|
40
|
+
// can be in the queue, and a second path would deliver it two times.
|
|
41
|
+
export async function queueOverSocket(threadId, text, highlight, { socket = socketPath(), timeoutMs = RPC_TIMEOUT_MS } = {}) {
|
|
42
|
+
let conn;
|
|
43
|
+
try {
|
|
44
|
+
conn = await ws.connect("ws://localhost/rpc", { socketPath: socket, timeoutMs });
|
|
45
|
+
} catch {
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
const waiting = new Map();
|
|
49
|
+
let next = 0;
|
|
50
|
+
conn.on("message", (raw) => {
|
|
51
|
+
let m;
|
|
52
|
+
try { m = JSON.parse(raw); } catch { return; }
|
|
53
|
+
if (m.id !== undefined && waiting.has(m.id)) waiting.get(m.id)(m);
|
|
54
|
+
});
|
|
55
|
+
conn.on("close", () => { for (const done of waiting.values()) done({ closed: true }); });
|
|
56
|
+
const call = (method, params) => new Promise((resolve) => {
|
|
57
|
+
const id = ++next;
|
|
58
|
+
const timer = setTimeout(() => done({ timeout: true }), timeoutMs);
|
|
59
|
+
const done = (m) => { clearTimeout(timer); waiting.delete(id); resolve(m); };
|
|
60
|
+
waiting.set(id, done);
|
|
61
|
+
conn.send(JSON.stringify({ id, method, params }));
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
try {
|
|
65
|
+
const init = await call("initialize", {
|
|
66
|
+
clientInfo: { name: "openmsg", title: null, version: "0.2" },
|
|
67
|
+
capabilities: { experimentalApi: true, requestAttestation: false },
|
|
68
|
+
});
|
|
69
|
+
if (!init.result) return null;
|
|
70
|
+
conn.send(JSON.stringify({ method: "initialized" }));
|
|
71
|
+
|
|
72
|
+
const elements = highlight && highlight.end > highlight.start
|
|
73
|
+
? [{ byteRange: highlight, placeholder: null }]
|
|
74
|
+
: [];
|
|
75
|
+
const out = await call("thread/queue/add", {
|
|
76
|
+
threadId,
|
|
77
|
+
input: [{ type: "text", text, text_elements: elements }],
|
|
78
|
+
clientUserMessageId: randomUUID(),
|
|
79
|
+
});
|
|
80
|
+
// An answer with an error says that the queue took nothing.
|
|
81
|
+
if (out.error) return null;
|
|
82
|
+
if (!out.result) throw new Error(`the codex daemon gave no answer for thread ${threadId}. The message can be in its queue.`);
|
|
83
|
+
const id = out.result.queuedSubmission?.id;
|
|
84
|
+
return { delivered: true, transport: "codex-socket", detail: `Queued message ${id} for thread ${threadId}.` };
|
|
85
|
+
} finally {
|
|
86
|
+
conn.close();
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
async function queueOverCli(threadId, text) {
|
|
13
91
|
try {
|
|
14
92
|
const { stdout } = await run(
|
|
15
93
|
"codex",
|
|
16
|
-
["queue", "--thread",
|
|
94
|
+
["queue", "--thread", threadId, "--message", text],
|
|
17
95
|
{ timeout: 15000 },
|
|
18
96
|
);
|
|
19
97
|
return { delivered: true, transport: "codex-queue", detail: stdout.trim() };
|
|
20
98
|
} catch (e) {
|
|
21
99
|
const out = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim() || e.message;
|
|
22
100
|
if (out.includes("no rollout found")) {
|
|
23
|
-
throw new Error(`codex thread ${
|
|
101
|
+
throw new Error(`codex thread ${threadId} has no turns yet. Send one prompt in that session first.`);
|
|
24
102
|
}
|
|
25
103
|
throw new Error(`codex queue failed: ${out.slice(0, 300)}`);
|
|
26
104
|
}
|
|
@@ -4,12 +4,12 @@
|
|
|
4
4
|
// Source: https://opencode.ai/docs/server/
|
|
5
5
|
import { render } from "../envelope.mjs";
|
|
6
6
|
|
|
7
|
-
export async function deliver(agent, message) {
|
|
7
|
+
export async function deliver(agent, message, { text = null } = {}) {
|
|
8
8
|
const url = `${agent.transport.base}/session/${agent.id}/prompt_async`;
|
|
9
9
|
const res = await fetch(url, {
|
|
10
10
|
method: "POST",
|
|
11
11
|
headers: { "content-type": "application/json" },
|
|
12
|
-
body: JSON.stringify({ parts: [{ type: "text", text: render(message) }] }),
|
|
12
|
+
body: JSON.stringify({ parts: [{ type: "text", text: text ?? render(message) }] }),
|
|
13
13
|
signal: AbortSignal.timeout(5000),
|
|
14
14
|
});
|
|
15
15
|
if (!res.ok) throw new Error(`opencode ${res.status}: ${(await res.text()).slice(0, 200)}`);
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// One text form for one object. A signature covers these bytes, so the sender
|
|
2
|
+
// and the receiver must build the same text from the same data.
|
|
3
|
+
//
|
|
4
|
+
// The rules: an object writes its keys in order of the code units of the name,
|
|
5
|
+
// an array keeps its order, and a key with the value `undefined` disappears.
|
|
6
|
+
|
|
7
|
+
export function canonical(value) {
|
|
8
|
+
return write(value);
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export function canonicalBytes(value) {
|
|
12
|
+
return Buffer.from(canonical(value), "utf8");
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function write(v) {
|
|
16
|
+
if (v === null) return "null";
|
|
17
|
+
const type = typeof v;
|
|
18
|
+
if (type === "boolean") return v ? "true" : "false";
|
|
19
|
+
if (type === "number") {
|
|
20
|
+
if (!Number.isFinite(v)) throw new Error("canonical form: a number must be finite");
|
|
21
|
+
return JSON.stringify(v);
|
|
22
|
+
}
|
|
23
|
+
if (type === "string") return JSON.stringify(v);
|
|
24
|
+
if (Array.isArray(v)) return `[${v.map(write).join(",")}]`;
|
|
25
|
+
if (type === "object") {
|
|
26
|
+
const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
|
|
27
|
+
return `{${keys.map((k) => `${JSON.stringify(k)}:${write(v[k])}`).join(",")}}`;
|
|
28
|
+
}
|
|
29
|
+
throw new Error(`canonical form: a value of type ${type} has no text form`);
|
|
30
|
+
}
|