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.
@@ -1,259 +0,0 @@
1
- # openmsg protocol, version 0.2, draft: agents of different people
2
-
3
- Status: draft, not implemented. Date: 2026-09-19.
4
-
5
- Version 0.1 moves a message between agents of one person on one machine. This
6
- draft adds agents of different people, on different machines, that work on one
7
- project.
8
-
9
- Example: two people work on one repository at the same time. One of them sees a
10
- fault in the work of the other. The agent of the first person sends a message to
11
- the agent of the second person, while that agent works.
12
-
13
- This document extends `openmsg-0.1.md`. Every rule of 0.1 still applies.
14
-
15
- A review of this design by a Codex session produced many of the rules below.
16
-
17
- ## 1. Model
18
-
19
- | Term | Meaning |
20
- |---|---|
21
- | Owner | The person who runs the agents. An owner has one identity in a team. |
22
- | Gateway | One process for each owner. It publishes the sessions that the owner selects, and it receives messages for them. |
23
- | Project | The shared work. A project has an opaque id that the team agrees on. |
24
- | Directory | The list of owners in a project, with their public keys and their endpoints. |
25
- | Relay | A server that carries messages between gateways. |
26
-
27
- The gateway is the only part that the network reaches. A vendor socket, a vendor
28
- port, and a vendor token stay on the machine of the owner. The gateway hands a
29
- message to the local adapter of 0.1 for the last step.
30
-
31
- ## 2. Addresses
32
-
33
- A person reads an alias. The protocol delivers to an identifier.
34
-
35
- ```
36
- alias: claude:api-worker@alice
37
- target: { owner: <owner id>, project: <project id>, session: <session id>, epoch: <number> }
38
- ```
39
-
40
- Rules:
41
-
42
- 1. A sender resolves an alias to a target before it sends.
43
- 2. Delivery uses the target only. An alias that moved to another session must
44
- never receive the message.
45
- 3. The epoch changes when a session restarts. A message for an old epoch is
46
- refused, not delivered.
47
- 4. A gateway publishes presence to a person, and signed routing data to an
48
- authorized gateway. See section 9. It must not publish the working
49
- directory, the socket path, the token, or the local registry object.
50
-
51
- ## 3. Identity
52
-
53
- 1. Each owner has a signing key and a separate encryption key. Both use an
54
- established algorithm.
55
- 2. Each device or session that sends holds a delegation from the owner key. A
56
- receiver verifies the delegation as well as the owner.
57
- 3. A person joins a project through an invitation. The two sides verify a
58
- fingerprint out of band.
59
- 4. A git author email is a label for a person. It is never proof of identity.
60
- 5. The directory holds a rotation record and a revocation list. A receiver must
61
- refuse a message from a revoked key, and must recheck at the moment of
62
- delivery.
63
-
64
- ## 4. Transport
65
-
66
- 1. The first transport is one relay for each team, and every gateway keeps an
67
- outbound connection to it. No laptop needs an open port. A direct mesh, for
68
- example over a private network, comes later.
69
- 2. The connection uses TLS, and the gateway authenticates with its key.
70
- 3. If the team needs a relay that cannot read the work, the message body is
71
- sealed for the receiving owner, with the encryption key. Then the relay
72
- carries bytes that it cannot read.
73
- 4. If the team accepts a relay that reads the body, the product must say so in
74
- plain words. A promise of privacy without sealing is false.
75
-
76
- ## 5. Authentication of a message
77
-
78
- 1. The sender signs a canonical form of the envelope. The signature covers
79
- every field that carries meaning: the version, `from`, the project, the
80
- target, `messageId`, `contextId`, `replyTo`, `createdAt`, the expiry,
81
- `hops`, `workspace`, and the parts. It excludes the signature itself and the
82
- receipt data that a receiver adds locally.
83
- 2. The receiver binds the authenticated sender to the `from` field. If the two
84
- do not match, the receiver refuses the message.
85
- 3. A gateway must not rewrite a signed field. It can attach verified data beside
86
- the envelope, in its own object.
87
- 4. The receiver validates the signature, the delegation, the membership, and the
88
- expiry, before the message reaches the model.
89
- 5. A delegation names its scope: the owner, the project, the devices that can
90
- sign, and the sessions that can receive. A receiver refuses a message that
91
- falls outside the scope of the delegation.
92
- 6. Where a rule of this document and a rule of 0.1 disagree, this document
93
- applies.
94
-
95
- ## 6. Authorization
96
-
97
- 1. A message never expands authority. This rule of 0.1 holds across people.
98
- 2. The owner of the receiving agent sets a standing permission for each identity
99
- and project: `accept`, `hold`, or `refuse`. The value applies to one project,
100
- not to everything.
101
- 3. A message from an unknown identity is held outside the context of the model.
102
- The model does not read it until the owner accepts the sender.
103
- 4. A message can ask for work. The receiving agent does the work only inside the
104
- permissions that its owner already gave it. A wording rule such as
105
- "information only" cannot hold a boundary, because a warning also starts an
106
- investigation. Where the runtime can limit the tools, it must.
107
- 5. The receiver checks the authorization again at the moment of delivery,
108
- because a queue can delay a message after the check.
109
- 6. The receiver holds its own limits: a rate limit for each sender, a limit on
110
- the turns that remote messages start, and a limit on the size of the queue.
111
- The `hops` list of the sender is not enough.
112
-
113
- ## 7. The envelope, added fields
114
-
115
- ```json
116
- {
117
- "openmsg": {
118
- "version": 2,
119
- "project": { "id": "opaque-id", "label": "web-app" },
120
- "target": { "owner": "o_8f13c0e4", "project": "p_47a91b", "session": "01a0...", "epoch": 3 },
121
- "expiresAt": "2026-09-19T23:59:00.000Z",
122
- "workspace": { "branch": "main", "commit": "9f2c...", "dirty": false }
123
- }
124
- }
125
- ```
126
-
127
- 1. `project.id` is opaque. A raw git remote URL must not travel, because it can
128
- hold a credential or the name of a private host. The label is a short name
129
- that the team chooses.
130
- 2. `workspace` is a claim of the sender. It describes the checkout of the
131
- sender, and it is never evidence about the checkout of the receiver. The
132
- receiving agent must read it as "the other person saw this".
133
- 3. `expiresAt` is a deadline. After it passes, the receiver refuses the message,
134
- whatever the state of the target.
135
-
136
- ## 8. States
137
-
138
- A message holds one state. The states of 0.1 are not enough, because a write to
139
- a socket is not a read by a model.
140
-
141
- | State | Meaning |
142
- |---|---|
143
- | `queued` | The sender holds the message. The target is not reachable yet. |
144
- | `held` | The receiver has it, and the owner must accept the sender first. |
145
- | `adapter-accepted` | The local adapter took the message. Whether the model read it is unknown. |
146
- | `agent-acknowledged` | The agent read the message. |
147
- | `replied` | The agent answered. |
148
- | `refused` | A rule stopped the message. The reason is recorded. |
149
- | `expired` | The deadline passed. |
150
-
151
- Rules:
152
-
153
- 1. A message reaches `agent-acknowledged` only through an acknowledgement event
154
- from the agent, for example a hook at the end of a turn, or a read of the
155
- mailbox. A receipt from a transport never proves that a model read a message.
156
- 2. The receiver writes the message to a durable store before it acknowledges.
157
- 3. A retry carries the same `messageId`. The receiver removes a duplicate by the
158
- authenticated sender and the `messageId`.
159
- 4. A conflicting duplicate holds the same `messageId` and the same authenticated
160
- sender, with different content. The receiver refuses the new arrival, keeps
161
- the record of the first message, and reports the event. A receiver must never
162
- rewrite the history of a delivery that already happened.
163
- 5. Retries are bounded.
164
- 6. An expiry stops an injection that did not happen yet. It does not undo work
165
- that an agent already started.
166
- 7. openmsg does not promise that a message runs exactly one time. A crash
167
- between delivery and acknowledgement leaves a doubt that no protocol removes.
168
- The receiving agent must therefore treat a repeated message as possible.
169
-
170
- ## 9. Delivery
171
-
172
- 1. The gateway of the receiver gives the message to the local adapter of 0.1.
173
- 2. The adapters do not change. The last step is the same as for one person.
174
- 3. Only the sessions that the owner selects are published. The default is that
175
- nothing is published.
176
- 4. A published session has two descriptions, and they are not the same thing:
177
- - **Presence**, which a person reads: the alias and the status.
178
- - **Routing data**, which a gateway reads: the owner id, the project id, the
179
- session id, the epoch, and the endpoint. It is signed, and an authorized
180
- peer alone receives it.
181
- 5. Neither description carries the working directory, a socket path, a token, or
182
- a raw repository URL.
183
-
184
- ## 10. Relation to A2A
185
-
186
- 1. openmsg 0.1 uses the field names of A2A. Equal names are not conformance.
187
- 2. This draft pins A2A version 1.0, and a later document gives the mapping field
188
- by field, with tests.
189
- 3. A2A has an option to sign an agent card with JWS. That option is separate
190
- from authentication and from authorization. The keys, the delegations, and
191
- the signed envelope of this document are choices of openmsg, and A2A does not
192
- supply them.
193
-
194
- ## 11. Acceptance demonstration
195
-
196
- A version 0.2 is done when this demonstration passes. A Codex review proposed
197
- this list.
198
-
199
- 1. Two owners, one project, one session published by each side.
200
- 2. An invitation, verified by fingerprint, before the first message.
201
- 3. A message that arrives while the receiving agent is busy.
202
- 4. A receiver that is offline, and that gets the message after it reconnects.
203
- 5. A retry with the same `messageId` that does not deliver a second copy.
204
- 6. A sender whose key was revoked, and whose message is refused.
205
- 7. A message for a session that restarted, refused by the epoch.
206
- 8. A limit on replies that stops a loop between two people.
207
- 9. A sender that the owner has not accepted, whose message stays held and
208
- outside the context of the model.
209
- 10. A message with a changed byte, refused by the signature.
210
- 11. A message that expires while it waits, and never reaches the model.
211
- 12. Two messages with one `messageId` and different content.
212
- 13. A key revoked after the message entered the queue.
213
- 14. A crash between injection and acknowledgement, where the state stays
214
- ambiguous and the receiver says so.
215
-
216
- This list is a smoke test. A release needs more than a pass here.
217
-
218
- ## 12. Answers to the open questions
219
-
220
- A Codex review gave these answers. They are the plan of record.
221
-
222
- 1. **The directory.** The relay holds it, and a reader authenticates. Each
223
- record of membership and each rotation is signed, and every gateway keeps a
224
- local copy. A change in a repository must never give access, because a
225
- person who can commit is not therefore a member.
226
- 2. **Storage for an offline receiver.** Both sides hold the message. The relay
227
- keeps it in a durable store of bounded size, and the sender keeps it in an
228
- outbox until the receiver gives a durable receipt.
229
- 3. **A held message.** The person sees the verified sender and project, and the
230
- full text on demand, as plain text that cannot act. No model writes a
231
- summary of a message that no model is allowed to read.
232
- 4. **The relay.** One transport. A team hosts its own relay first. A public
233
- relay comes later, and only with sealed messages.
234
-
235
- ## 13. Encryption: the decision
236
-
237
- **openmsg seals every message end to end. The relay cannot read a message.**
238
- The owner of the project made this decision on 2026-09-19.
239
-
240
- What follows from it:
241
-
242
- 1. Each owner holds a signing key and a separate encryption key. The sender
243
- seals the parts of the message for the encryption key of the receiver.
244
- 2. The relay stores the sealed bytes and the data that it needs to route them:
245
- the sender, the receiver, the project, the time, and the size.
246
- 3. The relay learns who writes to whom, when, and in which project. This design
247
- does not hide that. A product must not claim that it does.
248
- 4. A person joins through an invitation, and the two sides verify a fingerprint
249
- before the first message. This step is necessary, and a product must not
250
- skip it for speed.
251
- 5. A lost key means a lost history. The relay cannot give the text back.
252
- 6. A user interface decrypts in the browser or on the machine of the owner. The
253
- relay cannot search the text, and it cannot show it.
254
- 7. A hosted relay stays honest under this rule, because the operator holds no
255
- readable code.
256
-
257
- ## 14. Version
258
-
259
- This draft is version 0.2. `openmsg.version` is the integer `2`.