@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 +21 -0
- package/README.md +293 -0
- package/package.json +55 -0
- package/src/chat-session.ts +436 -0
- package/src/chat-view.ts +256 -0
- package/src/external.d.ts +69 -0
- package/src/identity.ts +80 -0
- package/src/index.ts +1 -0
- package/src/menu.ts +490 -0
- package/src/network.ts +201 -0
- package/src/pi-chat.ts +647 -0
- package/src/protocol.ts +325 -0
- package/src/settings.ts +330 -0
- package/src/text.ts +73 -0
- package/src/widget.ts +87 -0
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
|
+
[](https://www.npmjs.com/package/@narumitw/pi-chat) [](https://pi.dev) [](./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
|
+
}
|