@narumitw/pi-chat 0.0.0 → 0.1.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
@@ -14,15 +14,19 @@ output.
14
14
  ## ✨ Features
15
15
 
16
16
  - Creates random private rooms shared through bearer invite codes.
17
- - Joins guessable public rooms by lowercase slug.
17
+ - Browses currently discovered public rooms by estimated active participants, or joins a known
18
+ lowercase slug directly.
18
19
  - Shows every nickname with a stable public-key fingerprint such as
19
20
  `Mika~7K2P-9D4M-HQ3T`.
21
+ - Relays signed chat and presence events through a sparse P2P gossip overlay and suppresses duplicate
22
+ display and forwarding inside a bounded deduplication window.
20
23
  - Keeps an adaptive joined-room dock visible above the Pi editor with explicit input-target status.
21
24
  - Opens a focused, scrollable full-size chat composer with multiline IME support.
22
- - Preserves chat drafts when returning to Pi or when no direct peer can accept a message.
25
+ - Preserves chat drafts when returning to Pi or when no direct neighbor can accept a message.
23
26
  - Restores a remembered room and the last intentional chat/Pi surface when Pi restarts.
24
- - Uses authenticated direct streams and an invite-derived private-room handshake.
25
- - Limits peers, frames, messages, transcript entries, reconnect work, and per-peer message rates.
27
+ - Uses authenticated direct streams, origin signatures, and an invite-derived private-room handshake.
28
+ - Limits neighbors, participants, frames, messages, hops, catalogs, transcript entries, reconnect
29
+ work, and per-neighbor/per-origin message rates.
26
30
  - Keeps identity settings local with private permissions and atomic publication.
27
31
  - Cleans up discovery, sockets, timers, status, and widgets on leave, reload, session replacement,
28
32
  or shutdown.
@@ -63,12 +67,14 @@ Run:
63
67
 
64
68
  Then choose one of these actions:
65
69
 
70
+ - **Browse public rooms** queries a best-effort P2P directory, sorts discovered rooms by estimated
71
+ active participants and then slug, and keeps Refresh plus manual slug entry available.
66
72
  - **Join public room** accepts a lowercase slug such as `pi-dev`, remembers it after the public-room
67
73
  warning is confirmed, and opens the chat composer.
68
74
  - **Join with invite** accepts a private-room invite, then offers **Join and remember**, **Join once**,
69
75
  or **Cancel** before networking starts.
70
- - **Create private room** generates a random `pichat:v1:…` bearer invite and uses the same explicit
71
- persistence choice.
76
+ - **Create private room** generates a random `pichat:v2:…` bearer invite and uses the same explicit
77
+ persistence choice. Existing `pichat:v1` invite text remains accepted as v2 room input.
72
78
 
73
79
  The first join asks for a nickname and joined-room display mode, then previews the generated
74
80
  identity fingerprint and display choice before one atomic save. Pi Chat does not read your OS
@@ -92,17 +98,18 @@ Inside the dedicated chat composer:
92
98
  - `PageUp` and `PageDown` scroll transcript history.
93
99
  - `Escape` or `Ctrl+C` returns to Pi/LLM without leaving the room or discarding the chat draft.
94
100
 
95
- The composer retains the draft when no authenticated direct peer is available or a broadcast reaches
96
- zero peers. A successful local message reports how many authenticated direct peers accepted the
97
- broadcast. A disconnect race can still record an attempted message as **not delivered**; Pi Chat
98
- never claims delivery receipts or offline retry.
101
+ The composer retains the draft when no authenticated direct neighbor is available or a relay reaches
102
+ zero neighbors. A successful local message reports how many direct neighbors accepted the first
103
+ relay; it does not claim room-wide delivery. Signed events may arrive over multiple paths, but each
104
+ client displays and forwards one `originPublicKey:eventId` only once while it remains in the bounded
105
+ deduplication window. Pi Chat never claims exactly-once delivery, delivery receipts, or offline retry.
99
106
 
100
107
  ## 💬 Commands
101
108
 
102
109
  | Command | Modes | Description |
103
110
  | --- | --- | --- |
104
111
  | `/chat` | TUI | Open the state-aware Pi Chat manager. |
105
- | `/chat <pichat:v1:invite>` | TUI | Choose private persistence, join, and open chat. |
112
+ | `/chat <pichat:v1-or-v2:invite>` | TUI | Choose private persistence, join, and open chat. |
106
113
  | `/chat #<public-slug>` | TUI | Review the warning, join, and open the chat composer directly. |
107
114
 
108
115
  RPC, print, and JSON modes reject the command before starting networking or custom TUI work.
@@ -179,7 +186,9 @@ an upgrade does not expose message text unexpectedly.
179
186
  Public rooms are remembered only after their existing risk confirmation. A private room is remembered
180
187
  only when **Join and remember** is selected; this stores its bearer invite in `pi-chat.json`.
181
188
  **Join once** stores no room material, and Cancel starts neither persistence nor networking. An older
182
- file without `resume` remains disconnected until the next confirmed remembered join.
189
+ file without `resume` remains disconnected until the next confirmed remembered join. Stored v1 public
190
+ or private room ids are normalized to v2 in memory without rewriting the file during load; the next
191
+ explicit resume save publishes v2 ids while preserving unknown room and resume fields.
183
192
 
184
193
  The identity seed and stored private invites are redacted from UI, notifications, status, and errors.
185
194
  On POSIX, settings are published with `0600` permissions. A missing file is a side-effect-free read;
@@ -193,25 +202,41 @@ changes your fingerprint everywhere, forgets startup restore, and leaves the act
193
202
 
194
203
  ## 🌐 Network and protocol behavior
195
204
 
196
- Pi Chat uses one versioned 32-byte discovery topic per room:
205
+ Pi Chat protocol v2 uses one versioned 32-byte discovery topic per room:
197
206
 
198
207
  - A private topic and handshake key are domain-separated from a random 32-byte invite secret.
199
208
  - A public topic is deterministically derived from the public room slug.
209
+ - A separate global topic carries only bounded public-room directory presence.
200
210
 
201
- Each peer announces and looks up the topic through HyperDHT. Hyperswarm establishes authenticated,
202
- encrypted Noise streams. The application handshake binds the room proof, nickname, and both peer
203
- public keys. Messages are sent only across authenticated direct connections; they are not forwarded
204
- as multi-hop messages. A bounded peer-list exchange asks Hyperswarm to complete a small direct mesh.
211
+ Each peer announces and looks up its topics through HyperDHT. Hyperswarm establishes authenticated,
212
+ encrypted Noise streams. The room handshake binds the room proof, nickname, and both neighbor public
213
+ keys. Each client keeps at most **8 direct neighbors** instead of completing a full mesh.
205
214
 
206
- The implementation limits a room to 16 direct peers, messages to 4 KiB, protocol frames to 16 KiB,
207
- and the local transcript to 256 entries. There is no authoritative room membership count, global
208
- ordering, server history, delivery receipt, or offline delivery. The UI therefore reports only
209
- **direct peers**.
215
+ Chat and presence payloads carry the room id, origin public key, event id, issued time, content, and an
216
+ Ed25519 signature from the origin identity. A mutable hop budget is decremented at each relay. After
217
+ validation, the first copy updates local state and is forwarded to authenticated neighbors other than
218
+ the ingress connection; later copies with the same `originPublicKey:eventId` are dropped. Deduplication,
219
+ rate-limit, participant, and presence state are all bounded and expire locally.
220
+
221
+ The active-participant catalog supports up to **256 remote identities** and expires presence that has
222
+ not refreshed for 90 seconds. This is an approximate local view: sparse-overlay partitions, churn,
223
+ clock differences, and Sybil identities can change it. Messages are limited to 4 KiB, protocol frames
224
+ to 16 KiB, gossip to 8 hops, and the local transcript to 256 entries.
225
+
226
+ Public-room browsing uses signed room-scoped pseudonyms so honest clients do not expose one stable chat
227
+ identity across directory rooms. Directory nodes gossip bounded recent presence and browsers sort
228
+ unique scoped origins by estimated count descending, then slug ascending. Results can be empty,
229
+ stale, or partial; HyperDHT cannot enumerate every unknown topic, so the UI never calls the list or
230
+ count authoritative.
231
+
232
+ `pichat:v1` invite text and stored v1 secrets are accepted and mapped to a v2 private room. Newly
233
+ created invites use `pichat:v2`. Protocol-v1 full-mesh clients do not interoperate with the v2 gossip
234
+ overlay.
210
235
 
211
236
  Hyperswarm's default DHT depends on public bootstrap infrastructure. “P2P” does not mean
212
- infrastructure-free. NAT, UDP blocking, enterprise firewalls, bootstrap availability, or peer churn
213
- can prevent connectivity. Pi Chat performs bounded early refresh and reconnect work but cannot
214
- promise a connection on every network.
237
+ infrastructure-free. NAT, UDP blocking, enterprise firewalls, bootstrap availability, peer churn, or
238
+ a partitioned sparse overlay can prevent connectivity or delivery. Pi Chat performs bounded refresh
239
+ and reconnect work but cannot promise a connection or room-wide delivery.
215
240
 
216
241
  ## 🔒 Privacy, security, and recovery
217
242
 
@@ -220,7 +245,8 @@ promise a connection on every network.
220
245
  - Anyone holding a private invite can join. There is no member revocation in the initial protocol;
221
246
  create a new room after an invite leak.
222
247
  - Public slugs are guessable. Anyone may join, record, or repost public-room content.
223
- - A local session mute reduces immediate abuse but does not stop Sybil identities.
248
+ - A local session mute hides one signed origin while still forwarding valid events so a local
249
+ preference does not partition the room. It does not stop Sybil identities.
224
250
  - Remote peers can save or copy messages. Leaving or clearing the local transcript cannot withdraw
225
251
  copies from their devices.
226
252
  - Pi Chat never sends cwd, repository data, Git remotes, Pi sessions, prompts, models, files, or agent
@@ -241,15 +267,16 @@ and remembered with an actionable error.
241
267
 
242
268
  ## 🧪 Experimental limitations
243
269
 
244
- The first release intentionally omits:
270
+ The current experimental release intentionally omits:
245
271
 
246
272
  - simultaneous multi-room connections or UI;
247
273
  - persistent or synchronized history;
248
- - offline messages and delivery receipts;
274
+ - offline messages, delivery receipts, exactly-once delivery, or global ordering;
249
275
  - files, images, reactions, replies, editing, or deletion;
250
- - administrator roles, global bans, or identity recovery;
276
+ - administrator roles, global bans, Sybil resistance, or identity recovery;
251
277
  - browser, mobile, RPC, print, or JSON chat clients;
252
- - large-room gossip pubsub and product-owned relay infrastructure;
278
+ - authoritative room enumeration/counts or product-owned relay infrastructure;
279
+ - more than 256 tracked remote participants or 8 direct neighbors per client;
253
280
  - automatic transfer of chat content into the Pi editor, transcript, or model context.
254
281
 
255
282
  The joined room uses a persistent read-only widget while the normal Pi view is active. Selecting
@@ -269,6 +296,8 @@ packages/pi-chat/
269
296
  │ ├── pi-chat.ts
270
297
  │ ├── chat-session.ts
271
298
  │ ├── network.ts
299
+ │ ├── public-room-directory.ts
300
+ │ ├── directory-network.ts
272
301
  │ ├── protocol.ts
273
302
  │ ├── identity.ts
274
303
  │ ├── settings.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-chat",
3
- "version": "0.0.0",
3
+ "version": "0.1.0",
4
4
  "description": "Experimental peer-to-peer chat extension for Pi.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -34,7 +34,8 @@
34
34
  "dependencies": {
35
35
  "@narumitw/pi-tui-kit": "^0.49.1",
36
36
  "hyperdht": "6.33.0",
37
- "hyperswarm": "4.17.0"
37
+ "hyperswarm": "4.17.0",
38
+ "sodium-universal": "5.0.1"
38
39
  },
39
40
  "peerDependencies": {
40
41
  "@earendil-works/pi-coding-agent": "*",