@narumitw/pi-chat 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 narumiruna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,293 @@
1
+ # ๐Ÿ’ฌ Pi Chat โ€” Experimental P2P Developer Chat for Pi
2
+
3
+ [![npm](https://img.shields.io/npm/v/@narumitw/pi-chat)](https://www.npmjs.com/package/@narumitw/pi-chat) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
+
5
+ > [!WARNING]
6
+ > Pi Chat is experimental. Its protocol, identity format, networking behavior, and interaction flow
7
+ > may change between releases. It is not an anonymous or reliable messaging service.
8
+
9
+ `@narumitw/pi-chat` adds an ephemeral peer-to-peer chat room beside your Pi coding workflow. It uses
10
+ Hyperswarm and HyperDHT to discover peers and opens encrypted Noise streams directly between them.
11
+ Chat messages remain separate from Pi sessions, prompts, model context, repositories, and agent
12
+ output.
13
+
14
+ ## โœจ Features
15
+
16
+ - Creates random private rooms shared through bearer invite codes.
17
+ - Joins guessable public rooms by lowercase slug.
18
+ - Shows every nickname with a stable public-key fingerprint such as
19
+ `Mika~7K2P-9D4M-HQ3T`.
20
+ - Keeps an adaptive joined-room dock visible above the Pi editor with explicit input-target status.
21
+ - 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.
23
+ - 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.
26
+ - Keeps identity settings local with private permissions and atomic publication.
27
+ - Cleans up discovery, sockets, timers, status, and widgets on leave, reload, session replacement,
28
+ or shutdown.
29
+
30
+ ## ๐Ÿ“ฆ Install
31
+
32
+ Install persistently after the package is published:
33
+
34
+ ```bash
35
+ pi install npm:@narumitw/pi-chat
36
+ ```
37
+
38
+ Try from npm without installing permanently:
39
+
40
+ ```bash
41
+ pi -e npm:@narumitw/pi-chat
42
+ ```
43
+
44
+ Try the extension from a local checkout:
45
+
46
+ ```bash
47
+ pi --no-extensions --no-skills --no-session -e ./packages/pi-chat
48
+ ```
49
+
50
+ Load the package only once per Pi process. Repeating `-e ./packages/pi-chat` creates duplicate
51
+ extension instances and suffixed commands such as `/chat:1` and `/chat:2`.
52
+
53
+ Pi extensions execute with your user permissions. Review source before installing third-party
54
+ packages.
55
+
56
+ ## ๐Ÿš€ Quick start
57
+
58
+ Run:
59
+
60
+ ```text
61
+ /chat
62
+ ```
63
+
64
+ Then choose one of these actions:
65
+
66
+ - **Join public room** accepts a lowercase slug such as `pi-dev`, remembers it after the public-room
67
+ warning is confirmed, and opens the chat composer.
68
+ - **Join with invite** accepts a private-room invite, then offers **Join and remember**, **Join once**,
69
+ or **Cancel** before networking starts.
70
+ - **Create private room** generates a random `pichat:v1:โ€ฆ` bearer invite and uses the same explicit
71
+ persistence choice.
72
+
73
+ The first join asks for a nickname and joined-room display mode, then previews the generated
74
+ identity fingerprint and display choice before one atomic save. Pi Chat does not read your OS
75
+ username, Git identity, cwd, repository, or Pi session to fill these values. Cancelling creates
76
+ neither identity settings nor network activity.
77
+
78
+ A successful remembered join stores the room and `chat` surface atomically. On the next Pi start,
79
+ Pi Chat reconnects and reopens the full composer without another command. If you intentionally press
80
+ Escape or Ctrl+C to return to Pi, it remembers the `pi` surface instead: the next start reconnects in
81
+ the background and leaves the Pi editor focused.
82
+
83
+ While connected, `/chat` opens the state-aware manager. **Open chat in <room>** is selected first,
84
+ followed by participants, private invite, settings, status, help, and **Leave and forget room** last.
85
+ The persistent dock continues showing room state while the normal Pi editor targets Pi/LLM.
86
+
87
+ Inside the dedicated chat composer:
88
+
89
+ - The header says `CHAT INPUT โ†’ <room>` so the destination is never color-only.
90
+ - `Enter` sends the current message.
91
+ - Pi's configured newline key inserts a newline in the composer.
92
+ - `PageUp` and `PageDown` scroll transcript history.
93
+ - `Escape` or `Ctrl+C` returns to Pi/LLM without leaving the room or discarding the chat draft.
94
+
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.
99
+
100
+ ## ๐Ÿ’ฌ Commands
101
+
102
+ | Command | Modes | Description |
103
+ | --- | --- | --- |
104
+ | `/chat` | TUI | Open the state-aware Pi Chat manager. |
105
+ | `/chat <pichat:v1:invite>` | TUI | Choose private persistence, join, and open chat. |
106
+ | `/chat #<public-slug>` | TUI | Review the warning, join, and open the chat composer directly. |
107
+
108
+ RPC, print, and JSON modes reject the command before starting networking or custom TUI work.
109
+ Unknown and trailing arguments are rejected instead of ignored.
110
+
111
+ ## ๐Ÿชช Identity and nicknames
112
+
113
+ The display format is:
114
+
115
+ ```text
116
+ nickname~7K2P-9D4M-HQ3T
117
+ ```
118
+
119
+ The nickname is editable. The 12-character identity tag is the first 60 bits of the SHA-256 digest
120
+ of the authenticated DHT public key, encoded with Crockford Base32 and grouped `4-4-4`. The complete
121
+ public key remains the protocol identity. If short tags collide in one room, the UI can extend them;
122
+ the short tag is never an authorization boundary.
123
+
124
+ A fingerprint establishes continuity for one pseudonymous key. It does **not** prove a person's
125
+ real-world identity, prevent a user from creating many identities, or recover trust after the local
126
+ identity is reset or lost.
127
+
128
+ Nicknames are NFKC-normalized, trimmed, and limited to 24 grapheme clusters. Terminal, C0/C1, and
129
+ bidirectional control characters are rejected. Remote display text is sanitized again before
130
+ wrapping or rendering.
131
+
132
+ ## โš™๏ธ Settings
133
+
134
+ Pi Chat uses this user-owned file:
135
+
136
+ ```text
137
+ <getAgentDir()>/pi-chat.json
138
+ ```
139
+
140
+ The usual location is `~/.pi/agent/pi-chat.json`. Pi Chat does not add environment variables or read
141
+ project-local settings because the identity material is user-owned and secret.
142
+
143
+ Example with a remembered public room:
144
+
145
+ ```json
146
+ {
147
+ "nickname": "Mika",
148
+ "identitySeed": "base64url-encoded-private-seed",
149
+ "widgetMode": "count",
150
+ "resume": {
151
+ "rooms": [
152
+ {
153
+ "id": "derived-room-id",
154
+ "kind": "public",
155
+ "slug": "pi-dev"
156
+ }
157
+ ],
158
+ "activeRoomId": "derived-room-id",
159
+ "surface": "chat"
160
+ }
161
+ }
162
+ ```
163
+
164
+ `resume.rooms` is a bounded catalog designed to permit future multi-room expansion. This release
165
+ connects only `activeRoomId`. `surface` is `chat` when the user last kept the composer open and `pi`
166
+ after an intentional return to Pi/LLM. Transcripts, drafts, peers, and unread counts are never stored.
167
+
168
+ `widgetMode` accepts:
169
+
170
+ - `dock`: room and input-target status plus up to three recent messages, adapting to terminal height.
171
+ - `latest`: the existing single-message preview.
172
+ - `count`: room, direct-peer, and unread status only, without message text.
173
+ - `off`: hides the persistent widget.
174
+
175
+ New identities choose a mode before confirmation, with **Room dock** listed first. Existing settings
176
+ retain their stored mode; an older document without `widgetMode` continues to default to `count`, so
177
+ an upgrade does not expose message text unexpectedly.
178
+
179
+ Public rooms are remembered only after their existing risk confirmation. A private room is remembered
180
+ only when **Join and remember** is selected; this stores its bearer invite in `pi-chat.json`.
181
+ **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.
183
+
184
+ The identity seed and stored private invites are redacted from UI, notifications, status, and errors.
185
+ On POSIX, settings are published with `0600` permissions. A missing file is a side-effect-free read;
186
+ it is created only after an explicit first-use confirmation or settings change. Saves are ordered
187
+ within one Pi process, preserve unknown top-level and nested resume fields, and use a same-directory
188
+ temporary file plus rename. Malformed, invalid, symlinked, non-regular, invalid UTF-8, or oversized
189
+ files fail closed and remain unchanged.
190
+
191
+ **Reset identity** previews the old and candidate fingerprints and requires confirmation. Resetting
192
+ changes your fingerprint everywhere, forgets startup restore, and leaves the active room.
193
+
194
+ ## ๐ŸŒ Network and protocol behavior
195
+
196
+ Pi Chat uses one versioned 32-byte discovery topic per room:
197
+
198
+ - A private topic and handshake key are domain-separated from a random 32-byte invite secret.
199
+ - A public topic is deterministically derived from the public room slug.
200
+
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.
205
+
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**.
210
+
211
+ 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.
215
+
216
+ ## ๐Ÿ”’ Privacy, security, and recovery
217
+
218
+ - Noise encrypts direct transport, but DHT infrastructure and direct peers may observe IP addresses,
219
+ timing, and topic participation metadata. Pi Chat does not provide anonymity.
220
+ - Anyone holding a private invite can join. There is no member revocation in the initial protocol;
221
+ create a new room after an invite leak.
222
+ - 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.
224
+ - Remote peers can save or copy messages. Leaving or clearing the local transcript cannot withdraw
225
+ copies from their devices.
226
+ - Pi Chat never sends cwd, repository data, Git remotes, Pi sessions, prompts, models, files, or agent
227
+ output unless a user manually types that information into chat.
228
+ - Chat messages never call Pi message APIs and never enter model context or the main transcript.
229
+ - Deleting `pi-chat.json` loses identity continuity and produces a new fingerprint on the next
230
+ confirmed join.
231
+
232
+ If an ordinary join fails, Pi Chat tears down partially opened discovery and sockets and preserves
233
+ the previous valid settings. If startup restore fails, the remembered room is kept and `/chat` shows
234
+ Retry, Join another room, and Forget recovery actions instead of retrying forever. Invalid settings
235
+ must be fixed manually before a save can proceed.
236
+
237
+ Reloading, replacing the Pi session, or shutting down still releases every session-owned network and
238
+ UI resource. A new TUI session then restores the remembered room. Explicit **Leave and forget room**
239
+ atomically removes resume state before disconnecting; if that save fails, the room stays connected
240
+ and remembered with an actionable error.
241
+
242
+ ## ๐Ÿงช Experimental limitations
243
+
244
+ The first release intentionally omits:
245
+
246
+ - simultaneous multi-room connections or UI;
247
+ - persistent or synchronized history;
248
+ - offline messages and delivery receipts;
249
+ - files, images, reactions, replies, editing, or deletion;
250
+ - administrator roles, global bans, or identity recovery;
251
+ - browser, mobile, RPC, print, or JSON chat clients;
252
+ - large-room gossip pubsub and product-owned relay infrastructure;
253
+ - automatic transfer of chat content into the Pi editor, transcript, or model context.
254
+
255
+ The joined room uses a persistent read-only widget while the normal Pi view is active. Selecting
256
+ **Reply in <room>** temporarily opens the full custom chat view instead of a small floating window.
257
+ Closing it returns to Pi and the dock without leaving the room. The dock and composer reduce message
258
+ rows before hiding room, connectivity, or input-target status.
259
+
260
+ Pi's public extension widget API does not provide generic mouse hit-testing, so the dock is not
261
+ clickable and Pi Chat registers no global shortcut. `/chat` remains the menu-first entrypoint.
262
+
263
+ ## ๐Ÿ—‚๏ธ Package layout
264
+
265
+ ```text
266
+ packages/pi-chat/
267
+ โ”œโ”€โ”€ src/
268
+ โ”‚ โ”œโ”€โ”€ index.ts
269
+ โ”‚ โ”œโ”€โ”€ pi-chat.ts
270
+ โ”‚ โ”œโ”€โ”€ chat-session.ts
271
+ โ”‚ โ”œโ”€โ”€ network.ts
272
+ โ”‚ โ”œโ”€โ”€ protocol.ts
273
+ โ”‚ โ”œโ”€โ”€ identity.ts
274
+ โ”‚ โ”œโ”€โ”€ settings.ts
275
+ โ”‚ โ”œโ”€โ”€ menu.ts
276
+ โ”‚ โ”œโ”€โ”€ chat-view.ts
277
+ โ”‚ โ”œโ”€โ”€ widget.ts
278
+ โ”‚ โ””โ”€โ”€ text.ts
279
+ โ”œโ”€โ”€ test/
280
+ โ”œโ”€โ”€ README.md
281
+ โ”œโ”€โ”€ LICENSE
282
+ โ”œโ”€โ”€ package.json
283
+ โ””โ”€โ”€ tsconfig.json
284
+ ```
285
+
286
+ ## ๐Ÿ”Ž Keywords
287
+
288
+ Pi extension, Pi coding agent, peer-to-peer chat, P2P developer chat, Hyperswarm, HyperDHT, terminal
289
+ chat, TypeScript Pi package.
290
+
291
+ ## ๐Ÿ“„ License
292
+
293
+ MIT. See [`LICENSE`](./LICENSE).
package/package.json ADDED
@@ -0,0 +1,55 @@
1
+ {
2
+ "name": "@narumitw/pi-chat",
3
+ "version": "0.0.0",
4
+ "description": "Experimental peer-to-peer chat extension for Pi.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "private": false,
8
+ "keywords": [
9
+ "pi-package",
10
+ "pi-extension",
11
+ "pi",
12
+ "chat",
13
+ "p2p",
14
+ "dht"
15
+ ],
16
+ "files": [
17
+ "src",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "pi": {
22
+ "extensions": [
23
+ "./src/index.ts"
24
+ ]
25
+ },
26
+ "piExtension": {
27
+ "lifecycle": "experimental"
28
+ },
29
+ "scripts": {
30
+ "check": "biome check . && npm run typecheck",
31
+ "format": "biome check --write .",
32
+ "typecheck": "tsc --noEmit"
33
+ },
34
+ "dependencies": {
35
+ "@narumitw/pi-tui-kit": "^0.49.1",
36
+ "hyperdht": "6.33.0",
37
+ "hyperswarm": "4.17.0"
38
+ },
39
+ "peerDependencies": {
40
+ "@earendil-works/pi-coding-agent": "*",
41
+ "@earendil-works/pi-tui": "*"
42
+ },
43
+ "devDependencies": {
44
+ "@biomejs/biome": "2.5.7",
45
+ "@earendil-works/pi-coding-agent": "0.84.1",
46
+ "@earendil-works/pi-tui": "0.84.1",
47
+ "@types/node": "26.1.2",
48
+ "typescript": "7.0.2"
49
+ },
50
+ "repository": {
51
+ "type": "git",
52
+ "url": "https://github.com/narumiruna/pi-extensions",
53
+ "directory": "packages/pi-chat"
54
+ }
55
+ }