@yefengr/pi-reach 0.0.7 → 0.0.8
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 +62 -48
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,62 +1,73 @@
|
|
|
1
|
-
|
|
1
|
+
# Pi Reach
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Control your running Pi coding agent from your phone or any browser.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
When you step away from your computer, Pi Reach lets you follow Pi's live responses and tool calls, send another prompt or a file, and stop the current task. Pi keeps running on your computer; the browser is its remote interface.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
device -> endpoint -> runtime -> session / history generation
|
|
11
|
-
```
|
|
9
|
+
## Features
|
|
12
10
|
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
11
|
+
- **Pair without an account**: scan a QR code or enter an 8-character pairing code. Pair each computer once; later Pi processes on that computer appear automatically.
|
|
12
|
+
- **Switch between computers and Pi sessions**: connect to multiple computers and choose among the Pi processes currently running on each one.
|
|
13
|
+
- **Follow and control a live conversation**: stream responses and tool calls, send prompts and file attachments, or stop the current task. Attachments reach your computer as original files for Pi to read; image previews do not automatically become model vision input.
|
|
14
|
+
- **Manage the current session**: start a new conversation, compact context, or change the model and thinking level.
|
|
15
|
+
- **Use an installable PWA**: add the browser app to your home screen, choose light or dark mode, and use English or Chinese. Previously received conversations remain available for read-only viewing in that browser while offline.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
|
|
18
18
|
|
|
19
19
|
## Quick start
|
|
20
20
|
|
|
21
|
-
Install the Extension
|
|
21
|
+
1. Install the Extension:
|
|
22
22
|
|
|
23
|
-
```bash
|
|
24
|
-
pi install npm:@yefengr/pi-reach
|
|
25
|
-
```
|
|
23
|
+
```bash
|
|
24
|
+
pi install npm:@yefengr/pi-reach
|
|
25
|
+
```
|
|
26
26
|
|
|
27
|
-
Open Pi in the project you want to control.
|
|
27
|
+
2. Open Pi in the project you want to control. The Extension automatically connects to the configured Relay when the session starts.
|
|
28
|
+
3. Open the public [Pi Reach PWA](https://pi-reach.yefengr.cn/app) on your phone or another browser.
|
|
29
|
+
4. Run this command in Pi, then scan the terminal QR code from the PWA or enter the 8-character pairing code:
|
|
28
30
|
|
|
29
|
-
```text
|
|
30
|
-
/pi-reach pair
|
|
31
|
-
```
|
|
31
|
+
```text
|
|
32
|
+
/pi-reach pair
|
|
33
|
+
```
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
5. Pick an online Pi in the PWA and send your first prompt.
|
|
34
36
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
/pi-reach
|
|
38
|
-
|
|
37
|
+
Each computer only needs to be paired once. Pairings apply to the computer that creates them, not to every computer you use.
|
|
38
|
+
|
|
39
|
+
The public PWA and the default Relay are run by the maintainer. For sensitive work, [self-host the PWA and Relay](https://github.com/yefengr/pi-reach/blob/main/README.en.md#self-hosting).
|
|
40
|
+
|
|
41
|
+
## Security and limits
|
|
39
42
|
|
|
40
|
-
|
|
43
|
+
**Pi Reach has no application-layer end-to-end encryption. The Relay is fully trusted.** TLS protects transport, but the Relay operator can read conversation content, including code, commands, and output. The operator could also impersonate a paired browser and send prompts that Pi executes on your computer. Use a Relay you control for sensitive work.
|
|
44
|
+
|
|
45
|
+
- Pi must already be running with the Extension loaded. Pi Reach cannot remotely start, wake, or keep Pi running in the background.
|
|
46
|
+
- Browser history is a local, read-only cache of received conversations, not a cloud backup or a way to browse and resume old Pi sessions on your computer.
|
|
47
|
+
- Sending prompts and files requires a live connection. There is no offline send queue or push notifications, and phone lock-screen connectivity is not guaranteed.
|
|
48
|
+
- Browser identity, pairings, and received history stay in that browser's local storage. Clearing site data removes them and requires pairing again. There are no cloud accounts or cross-browser history synchronization.
|
|
49
|
+
- Revoke browsers you no longer use from Pi with `/pi-reach revoke <shortid>`; list them with `/pi-reach devices`.
|
|
50
|
+
|
|
51
|
+
Report vulnerabilities through GitHub's [private vulnerability reporting](https://github.com/yefengr/pi-reach/security/advisories/new); see the [security policy](https://github.com/yefengr/pi-reach/blob/main/SECURITY.md).
|
|
41
52
|
|
|
42
53
|
## Commands
|
|
43
54
|
|
|
44
55
|
| Command | Description |
|
|
45
56
|
|---|---|
|
|
46
|
-
| `/pi-reach` |
|
|
47
|
-
| `/pi-reach start` / `/pi-reach stop` | Connect or disconnect this
|
|
48
|
-
| `/pi-reach status` | Show Relay, endpoint, runtime, and
|
|
49
|
-
| `/pi-reach pair` | Show
|
|
50
|
-
| `/pi-reach devices` | List
|
|
51
|
-
| `/pi-reach revoke <shortid>` | Revoke
|
|
52
|
-
| `/pi-reach set-relay <url>` |
|
|
57
|
+
| `/pi-reach` | Reconnect this Pi after `/pi-reach stop` |
|
|
58
|
+
| `/pi-reach start` / `/pi-reach stop` | Connect or disconnect this Pi |
|
|
59
|
+
| `/pi-reach status` | Show Relay, endpoint, runtime, and paired-browser state |
|
|
60
|
+
| `/pi-reach pair` | Show a pairing QR code and pairing code for this Pi |
|
|
61
|
+
| `/pi-reach devices` | List browsers paired with this computer |
|
|
62
|
+
| `/pi-reach revoke <shortid>` | Revoke a browser's pairing on this computer |
|
|
63
|
+
| `/pi-reach set-relay <url>` | Save the Relay URL |
|
|
53
64
|
| `/pi-reach config` | Show the resolved Relay URL |
|
|
54
65
|
|
|
55
|
-
The Extension handles remote `session_new` requests in-process through Pi's session API. There is no standalone `pi-reach` CLI, background process, scheduler, or service installation command.
|
|
56
|
-
|
|
57
66
|
## Relay configuration
|
|
58
67
|
|
|
59
|
-
|
|
68
|
+
Pi and the PWA must use the same Relay. The pairing QR code does not carry a Relay address.
|
|
69
|
+
|
|
70
|
+
The Extension resolves its Relay URL in this order:
|
|
60
71
|
|
|
61
72
|
1. `PI_REACH_RELAY`
|
|
62
73
|
2. `~/.pi/pi-reach/config.json`
|
|
@@ -69,27 +80,30 @@ Set and inspect it from Pi:
|
|
|
69
80
|
/pi-reach config
|
|
70
81
|
```
|
|
71
82
|
|
|
72
|
-
|
|
83
|
+
In the PWA, set the same URL under **Settings → Connection → Relay URL**. Use `https://` for a deployed Relay; `http://` is accepted for local development. The Extension converts the URL to WebSocket form internally. The Relay retains routing state in memory and does not persist conversations.
|
|
84
|
+
|
|
85
|
+
## Endpoint model and local state
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
device -> endpoint -> runtime -> session / history generation
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- **Device**: the computer's Ed25519 identity and the scope of pairing authorization.
|
|
92
|
+
- **Endpoint and runtime**: generated randomly when a Pi process loads the Extension. They remain stable across Extension reloads in that process and are regenerated for the next Pi process. The endpoint is not derived from the working directory.
|
|
93
|
+
- **Session / generation**: the active Pi conversation and its current history branch. Pi Reach does not list or resume historical Pi sessions.
|
|
73
94
|
|
|
74
|
-
|
|
95
|
+
Pairing QR codes target the current endpoint and runtime; the resulting browser authorization is stored at device scope. Owner messages are trusted only through the Relay-injected `source_owner_id`. Pairing and revocation update the Relay endpoint ACL with `authorized_owner_ids`.
|
|
75
96
|
|
|
76
|
-
|
|
77
|
-
- Report vulnerabilities privately through GitHub's [private vulnerability reporting](https://github.com/yefengr/pi-reach/security/advisories/new); see the [security policy](https://github.com/yefengr/pi-reach/blob/main/SECURITY.md).
|
|
78
|
-
- `device_id` is the Host Ed25519 public key in canonical Base64 form.
|
|
79
|
-
- Owner messages are trusted only through the Relay-injected `source_owner_id`.
|
|
80
|
-
- Pairing and revocation update the Relay endpoint ACL with `authorized_owner_ids`.
|
|
81
|
-
- Relay loss enters reconnecting state; the Extension does not restart Pi to recover.
|
|
82
|
-
- Device private keys, pairing tokens, encrypted payloads, and message bodies are not logged.
|
|
83
|
-
- Concurrent Pi processes coordinate device identity initialization through a local lock. If initialization is interrupted, follow the [identity storage and lock recovery rules](../docs/reference/protocol/pairing.md#host); do not delete identity or pairing data to retry.
|
|
97
|
+
The Extension handles remote `session_new` requests in-process through Pi's session API. There is no standalone `pi-reach` CLI, background process, scheduler, or service installation command. Relay loss triggers reconnection, not a Pi restart.
|
|
84
98
|
|
|
85
|
-
|
|
99
|
+
Pi Reach stores global configuration, identity files, and pairings under `~/.pi/pi-reach`, and project display configuration under `.pi/pi-reach`. Its platform keyring service is `dev.pireach.pi`. Device private keys, pairing tokens, and message bodies are not logged.
|
|
86
100
|
|
|
87
|
-
Pi
|
|
101
|
+
Concurrent Pi processes coordinate device identity initialization through a local lock. If initialization is interrupted, follow the [identity storage and lock recovery rules](https://github.com/yefengr/pi-reach/blob/main/docs/reference/protocol/pairing.md#host); do not delete identity or pairing data to retry.
|
|
88
102
|
|
|
89
103
|
## Development
|
|
90
104
|
|
|
91
105
|
Install dependencies from the repository root with `pnpm install --frozen-lockfile`.
|
|
92
|
-
The root workspace owns dependency catalogs, build approvals, and the lockfile. The private workspace package [`@pi-reach/protocol`](
|
|
106
|
+
The root workspace owns dependency catalogs, build approvals, and the lockfile. The private workspace package [`@pi-reach/protocol`](https://github.com/yefengr/pi-reach/tree/main/packages/protocol) provides the shared protocol build artifacts; the Extension uses it as a development dependency, while installed users receive vendored artifacts and need neither the workspace nor a separately published shared package. Its module and distribution boundary is defined in [ARCHITECTURE](https://github.com/yefengr/pi-reach/blob/main/docs/ARCHITECTURE.md#工程与构建边界).
|
|
93
107
|
|
|
94
108
|
The root `prepare` script and an Extension `pnpm build` build the shared package first. After changing shared sources, run `pnpm --filter @pi-reach/protocol build` from the repository root before an Extension-only `typecheck` or `test`, or use the corresponding root command.
|
|
95
109
|
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yefengr/pi-reach",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.8",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"description": "
|
|
7
|
+
"description": "Control your running Pi coding agent from your phone or any browser. Stream responses, send prompts and files, and switch between active Pi sessions.",
|
|
8
8
|
"type": "module",
|
|
9
9
|
"main": "dist/index.js",
|
|
10
10
|
"types": "dist/index.d.ts",
|
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
"pi": {
|
|
25
25
|
"extensions": [
|
|
26
26
|
"./dist"
|
|
27
|
-
]
|
|
27
|
+
],
|
|
28
|
+
"image": "https://raw.githubusercontent.com/yefengr/pi-reach/main/docs/assets/screenshot-desktop-en.png"
|
|
28
29
|
},
|
|
29
30
|
"author": "yefeng",
|
|
30
31
|
"license": "MIT",
|