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 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
- Status: early work. The Claude Code path works. See "State" below.
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
- ## Spec
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
- - `docs/spec/openmsg-0.1.md`: the protocol for the agents of one person on one
74
- machine. This is what the code implements.
75
- - `docs/spec/openmsg-0.2-draft.md`: a draft for the agents of different people
76
- on one project. Not implemented.
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
- ## Research
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
- `docs/research/2026-09-19-transport-research.md` gives the full comparison of the
81
- options, with sources: terminal typing, native entry points, subprocess calls,
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.1.0",
4
- "description": "Messages between AI coding agents of different vendors, on one machine.",
3
+ "version": "0.2.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
  ],
@@ -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
 
@@ -9,11 +9,11 @@ import { render } from "../envelope.mjs";
9
9
 
10
10
  const run = promisify(execFile);
11
11
 
12
- export async function deliver(agent, message) {
12
+ export async function deliver(agent, message, { text = null } = {}) {
13
13
  try {
14
14
  const { stdout } = await run(
15
15
  "codex",
16
- ["queue", "--thread", agent.id, "--message", render(message)],
16
+ ["queue", "--thread", agent.id, "--message", text ?? render(message)],
17
17
  { timeout: 15000 },
18
18
  );
19
19
  return { delivered: true, transport: "codex-queue", detail: stdout.trim() };
@@ -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
+ }