pi-pocket 0.29.0 → 0.30.0-beta.2
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 +58 -1
- package/SECURITY.md +1 -0
- package/docs/architecture.md +9 -4
- package/docs/desktop-app.md +54 -0
- package/docs/examples/approval-monitor.ts +82 -0
- package/docs/extensions/people-values.md +8 -0
- package/docs/extensions/policies/api-stability.md +1 -0
- package/docs/extensions/reference/api-versions.md +3 -0
- package/docs/extensions/reference/host.md +92 -1
- package/docs/extensions/tools.md +1 -0
- package/docs/features.md +4 -4
- package/docs/index.md +3 -0
- package/docs/macos.md +90 -0
- package/docs/map.md +9 -5
- package/docs/windows.md +73 -0
- package/npm-shrinkwrap.json +71 -67
- package/package.json +9 -9
- package/src/launcher/desktop.ts +45 -0
- package/src/launcher/main.ts +81 -17
- package/src/launcher/options.ts +59 -2
- package/src/server/alerts.ts +2 -2
- package/src/server/app.ts +2 -0
- package/src/server/auth.ts +40 -0
- package/src/server/background.ts +109 -241
- package/src/server/commands.ts +28 -17
- package/src/server/design/scan-fig-container.ts +3 -2
- package/src/server/design/scan-files.ts +3 -11
- package/src/server/design/system.ts +3 -4
- package/src/server/design/tokens-io.ts +2 -3
- package/src/server/docs.ts +9 -0
- package/src/server/errors.ts +12 -0
- package/src/server/extension-document-compat.ts +4 -0
- package/src/server/extensions/artifacts.ts +2 -6
- package/src/server/extensions/codemode.ts +27 -1
- package/src/server/extensions/guard.ts +9 -1
- package/src/server/extensions/pocket-relay/files.ts +10 -3
- package/src/server/extensions/pocket-relay/runtime.ts +6 -0
- package/src/server/extensions/pocket-relay.ts +31 -3
- package/src/server/extensions/schedules.ts +9 -2
- package/src/server/host.ts +25 -0
- package/src/server/http/api.ts +21 -4
- package/src/server/http/browser-routes.ts +5 -2
- package/src/server/http/conversation-routes.ts +4 -3
- package/src/server/http/events.ts +9 -4
- package/src/server/http/io.ts +5 -2
- package/src/server/http/sign-in.ts +9 -3
- package/src/server/limit-gate.ts +257 -65
- package/src/server/limits.ts +80 -4
- package/src/server/main.ts +71 -16
- package/src/server/no-follow.ts +67 -0
- package/src/server/pending-approvals.ts +174 -0
- package/src/server/processes.ts +1480 -0
- package/src/server/projection.ts +7 -6
- package/src/server/room.ts +2 -0
- package/src/server/schedules.ts +226 -4
- package/src/server/secrets.ts +6 -4
- package/src/server/socket-path.ts +167 -0
- package/src/server/themes.ts +2 -4
- package/src/server/worktrees.ts +16 -17
- package/types/pocket.d.ts +74 -0
- package/web/agent-now.js +2 -2
- package/web/notify.js +1 -5
- package/web/peeks.js +1 -1
- package/web/sessions.js +2 -3
- package/web/sheets/schedules.js +18 -0
- package/web/store.js +126 -13
- package/web/transcript.js +4 -30
package/README.md
CHANGED
|
@@ -54,6 +54,14 @@ While it runs: **q** quit · **r** restart server · **a** change access · **o*
|
|
|
54
54
|
|
|
55
55
|
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 and 0.28.0 upgrade the data one way, so going back needs the backup.
|
|
56
56
|
|
|
57
|
+
### Windows installer
|
|
58
|
+
|
|
59
|
+
Download `Pi-Pocket-Setup-<version>.exe` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and run it. It needs no admin rights and no Node.js: it installs its own Node.js and Pi Pocket in `%LOCALAPPDATA%\Pi Pocket`, adds **Pi Pocket** to the Start menu, and can start it when you sign in. Pi Pocket opens as a desktop app: a window of its own, already signed in, and an icon in the notification area, with no console window. **Pi Pocket (console)** has the access modes, tunnels, and the sign-in QR code. The installer is not code-signed yet, so SmartScreen warns: select **More info**, then **Run anyway**. Menu → **Update Pi Pocket** updates it. The uninstaller asks before it deletes your data. See [docs/windows.md](docs/windows.md) and [docs/desktop-app.md](docs/desktop-app.md).
|
|
60
|
+
|
|
61
|
+
### macOS package
|
|
62
|
+
|
|
63
|
+
Download `Pi-Pocket-<version>.pkg` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and open it. It needs no admin password and no Node.js: it installs its own Node.js and Pi Pocket in `~/Library/Application Support/Pi Pocket` for your user only, adds **Pi Pocket.app** to `~/Applications`, and can start it when you sign in. Pi Pocket.app opens a window of its own, already signed in, with an item in the menu bar and no Terminal window. **Pi Pocket (console).app** has the access modes, tunnels, and the sign-in QR code. The package is not signed yet, so Gatekeeper blocks it: open System Settings → Privacy & Security, then select **Open Anyway**. Menu → **Update Pi Pocket** updates it. Its uninstaller asks before it deletes your data. See [docs/macos.md](docs/macos.md) and [docs/desktop-app.md](docs/desktop-app.md).
|
|
64
|
+
|
|
57
65
|
### Other ways to run it
|
|
58
66
|
|
|
59
67
|
- **Docker or Podman:** `docker compose up -d --build`. See [docs/docker.md](docs/docker.md).
|
|
@@ -84,11 +92,60 @@ Choose a mode in the launcher, or pass `--access`:
|
|
|
84
92
|
|
|
85
93
|
`tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet, and, when the launcher does not run as root, that user as tailscaled's operator (`sudo tailscale set --operator=$USER`). It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. `--host` cannot be combined with it: serve always listens on `127.0.0.1` and lets tailscaled reach it. For another tunnel (ngrok), choose `local` and point it at port 8787.
|
|
86
94
|
|
|
87
|
-
Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `--host` overrides the address a named mode would listen on, and one launcher runs per data folder (a second one says which pid holds it). `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_SESSION_CACHE=off` keeps browsers from saving the sessions they open on the device (IndexedDB), so that they keep them in each tab's memory only; it is on by default. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)). `PI_POCKET_KEEPALIVE_SECONDS` (default `5`, from `1` to `3600`) is how long the server keeps an idle connection open for its next request. Behind a reverse proxy of your own (Caddy, nginx, a load balancer), set it above the proxy's idle timeout, or set the proxy's below it: otherwise the proxy can send a request on a connection as the server closes it, and answers with a 502. Caddy keeps idle connections for 2 minutes by default, so `PI_POCKET_KEEPALIVE_SECONDS=125`, or `keepalive 4s` in Caddy's `transport http` block.
|
|
95
|
+
Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, `--socket` ([below](#behind-a-reverse-proxy-on-a-unix-socket)), and `-y` to reuse the last access choice. `--host` overrides the address a named mode would listen on, and one launcher runs per data folder (a second one says which pid holds it). `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_SESSION_CACHE=off` keeps browsers from saving the sessions they open on the device (IndexedDB), so that they keep them in each tab's memory only; it is on by default. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)). `PI_POCKET_KEEPALIVE_SECONDS` (default `5`, from `1` to `3600`) is how long the server keeps an idle connection open for its next request. Behind a reverse proxy of your own (Caddy, nginx, a load balancer), set it above the proxy's idle timeout, or set the proxy's below it: otherwise the proxy can send a request on a connection as the server closes it, and answers with a 502. Caddy keeps idle connections for 2 minutes by default, so `PI_POCKET_KEEPALIVE_SECONDS=125`, or `keepalive 4s` in Caddy's `transport http` block.
|
|
88
96
|
|
|
89
97
|
> [!WARNING]
|
|
90
98
|
> Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. [SECURITY.md](SECURITY.md) says what is protected and what is not.
|
|
91
99
|
|
|
100
|
+
### Behind a reverse proxy on a Unix socket
|
|
101
|
+
|
|
102
|
+
`--socket PATH` (or `PI_POCKET_SOCKET`) makes the server listen on a Unix socket instead of a TCP port, for a reverse proxy on the same machine, such as Caddy or nginx. Use it on a machine that other people use too: while the server restarts, any user can take a free TCP port and get the requests meant for Pi Pocket, sign-in cookies too. A socket's folder keeps them out.
|
|
103
|
+
|
|
104
|
+
`--socket` replaces `--access`, `--host`, and `--port`: it cannot be combined with them, and their environment variables are ignored. The launcher starts no tunnel and runs no `tailscale serve`, and its `a` and `o` keys do nothing. It prints the owner's sign-in path (`/login?token=…`): open it at the proxy's address.
|
|
105
|
+
|
|
106
|
+
The folder is the security boundary. Pi Pocket checks it before it listens, and does not start when:
|
|
107
|
+
|
|
108
|
+
- the folder is a symlink, or the path goes through one;
|
|
109
|
+
- another user than the server's (or root) owns the folder, or its group or others can write to it;
|
|
110
|
+
- another user can write to a folder above it, unless that folder is sticky, as `/tmp` is;
|
|
111
|
+
- the path is a file, a folder, or a symlink: Pi Pocket never follows or removes one;
|
|
112
|
+
- a server answers on the socket already.
|
|
113
|
+
|
|
114
|
+
A socket that nothing answers on, as a killed server leaves, is replaced. The new socket gets mode `0660`, so the folder's group can connect. Give the folder the proxy's group and mode `2750`: then only the server's user and the proxy can reach the socket. Pi Pocket removes the socket when it stops.
|
|
115
|
+
|
|
116
|
+
An example on Linux, with the server as `alice` and Caddy as `caddy`:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
# /run is empty after a reboot: a tmpfiles.d line (d /run/pi-pocket 2750 alice caddy -) makes the folder again.
|
|
120
|
+
sudo install -d -o alice -g caddy -m 2750 /run/pi-pocket
|
|
121
|
+
pi-pocket --socket /run/pi-pocket/pocket.sock
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```caddyfile
|
|
125
|
+
pocket.example.com {
|
|
126
|
+
reverse_proxy unix//run/pi-pocket/pocket.sock
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Caddy keeps idle connections longer than Pi Pocket does: also set `PI_POCKET_KEEPALIVE_SECONDS=125`, as [Remote access](#remote-access) says.
|
|
131
|
+
|
|
132
|
+
With nginx (as the user `www-data`, in that group):
|
|
133
|
+
|
|
134
|
+
```nginx
|
|
135
|
+
location / {
|
|
136
|
+
proxy_pass http://unix:/run/pi-pocket/pocket.sock:;
|
|
137
|
+
proxy_http_version 1.1;
|
|
138
|
+
# Uploads: nginx takes only 1 MB by default.
|
|
139
|
+
client_max_body_size 50m;
|
|
140
|
+
# $http_host keeps a port that is not the default one.
|
|
141
|
+
proxy_set_header Host $http_host;
|
|
142
|
+
proxy_set_header X-Forwarded-Host $http_host;
|
|
143
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Sign-in works as it does on a port: the owner's link, invites, the `HttpOnly` cookie, and the `X-Pocket` header on every change. Pi Pocket trusts no client address, on a port or on a socket, so the socket lets nobody past sign-in. Invite links and the cookie's `Secure` flag come from the `X-Forwarded-Host` (else `Host`) and `X-Forwarded-Proto` headers. Caddy sets them by itself, and nginx needs the lines above. Let the proxy set them, and not pass on a client's: a wrong value gives wrong invite links, not access.
|
|
148
|
+
|
|
92
149
|
## Documentation
|
|
93
150
|
|
|
94
151
|
- [Feature tour](docs/features.md): every feature, in full.
|
package/SECURITY.md
CHANGED
|
@@ -9,6 +9,7 @@ Please report security problems privately through GitHub: on this repository, op
|
|
|
9
9
|
Pi Pocket runs a coding agent that executes commands on the machine it runs on, as the user who started it.
|
|
10
10
|
|
|
11
11
|
- **Signing in.** The owner's sign-in link is the key to the server. Invites are one-time links that expire after 15 minutes, or an hour, a day, or a week when whoever makes one picks that; the longer one lasts, the longer a link that leaks can be used. Their codes are stored hashed. An owner invite, which only the owner can make, always lasts 15 minutes and gives the device that opens it the owner token itself, and with it full control; starting with `--rotate-token` signs out every device that has it and ends owner invites not yet used. Tokens are random, stored hashed, and kept in an `HttpOnly` cookie. The cookie is host-only (it has no `Domain`), so each address needs its own sign-in: `127.0.0.1` and `localhost` are different hosts to a browser, and a device signed in at one is not signed in at the other.
|
|
12
|
+
- **A Unix socket** (`--socket`) is for a reverse proxy on the same machine. Its folder decides which Unix users can connect: Pi Pocket does not start in a folder that another user can change, never removes anything there but a stale socket, and opens the socket only to the folder's group. Sign-in is the same as on a port. The proxy sets the host and scheme that invite links and the cookie's `Secure` flag use ([README](README.md#behind-a-reverse-proxy-on-a-unix-socket)).
|
|
12
13
|
- **Viewers** can read, react, and chat. They cannot make Pi do anything.
|
|
13
14
|
- **Anyone who can steer can do what you can.** Through Pi, they reach your files, Pi Pocket's settings and tokens, and its code. An invite to one session limits what someone sees in the app, not what Pi can reach. Neither do git worktrees or spend limits: a worktree keeps a session's files apart, and a run is stopped only after the request that crosses its limit.
|
|
14
15
|
- **Approvals.** Lancet Guard approvals can come from anyone who can steer, including the person who asked, unless the owner turns on "Approvals need someone else" (Menu → Extensions); then, when nobody is known to have asked, only the owner can allow. A notification offers Allow only for a call that fits on one short line; anything longer opens the app first. Since 0.22.0, an extension can ask a question on the same kind of card (a sign-in, a code): only the person Pi works for fills it in, what they type goes to that extension and never to Pi or the transcript, and its notification has no Allow. Values an extension hides show as `[label]` in command output, tool results, and messages to Pi; that keeps them out by accident, not from a command or a model that leaks them on purpose. A "Done when" check command runs after every answer without asking, so with Lancet Guard on it must be one the guard allows outright.
|
package/docs/architecture.md
CHANGED
|
@@ -13,6 +13,8 @@ Pi Durable 1.4.0 migrates SQLite storage to schema version 2 when it opens. Olde
|
|
|
13
13
|
|
|
14
14
|
Pi Durable 1.5.0 keeps schema version 2, but it stores `pi.live` at version 3, and its tool and generation tasks at newer versions, as soon as a conversation runs. An older Pi Pocket then does not start on that data folder: it stops with "Document … (pi.live) has newer version 3 than 1". Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.28.0, and do not go back to an older version with the same folder.
|
|
15
15
|
|
|
16
|
+
Pi Durable 1.6.0 stores its tool tasks (`pi.tool`) at version 4 and its generation tasks (`pi.generation`) at version 3. An older Pi Durable does not run such tasks (`task_too_old`), and takes a sleep without `until` as due. Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.30.0, and do not go back to an older version with the same folder.
|
|
17
|
+
|
|
16
18
|
Scheduled messages, PR watches, repository watches, and PiP reports held while PiP is off use durable `sleepUntil()` checkpoints. A sleeping task holds no invocation and resumes at its saved phase when the harness clock reaches its deadline. The task graph includes these tasks with status `sleeping`.
|
|
17
19
|
|
|
18
20
|
Some state lives in this process alone, and a restart forgets it. For example:
|
|
@@ -49,6 +51,8 @@ The native extension loader registers one scoped resolve hook for drop-in import
|
|
|
49
51
|
|
|
50
52
|
Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose functions call into the app lazily, and `web`, through which they add routes and a browser module to the app. `ExtensionWebs` (`extension-web.ts`) keeps what each module's version added, which the loader commits once the module installed and removes with it, running its cleanups. The HTTP layer parses a request, checks it, calls a part, and writes the answer; it holds no state of its own beyond invites and the event streams' pollers.
|
|
51
53
|
|
|
54
|
+
`host.pendingApprovals` (`pending-approvals.ts`) observes the internal approval service in `host.ts`. It filters waits for the source session's requester and everyone who can see the source. It does not pass on commands, arguments, reasons, or answers. The guard hook keeps a wait's first creation time in its Durable call memo, so a resumed run can show the same wait. Approval decisions still use the app's existing paths.
|
|
55
|
+
|
|
52
56
|
## Workspace execution providers
|
|
53
57
|
|
|
54
58
|
`PocketApp` selects the execution environment by the session's working folder. Local folders keep the existing Node environment; URI workspaces use the last registered provider for their scheme. Removal restores the previous registration, and a missing provider fails closed. Resolution checks the provider identity and cancellation after awaited work. Only the owner can use a workspace URI. The provider's module, a drop-in outside the core package, owns host-key trust, connections, remote project context, and cleanup. Files/Git actions and managed worktrees remain local-only.
|
|
@@ -116,14 +120,15 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
|
|
|
116
120
|
|
|
117
121
|
## Waiting for a provider's limit
|
|
118
122
|
|
|
119
|
-
`LimitGate` (`limit-gate.ts`, `app.limits`) wraps `models.streamSimple` after `timing.ts` does, so each attempt is timed on its own. A request that fails before any content on a limit that clears with time does not fail: it waits inside its own stream, and goes on. Pi Durable sees one slow request. `limits.ts` (`classify`) reads the error text
|
|
123
|
+
`LimitGate` (`limit-gate.ts`, `app.limits`) wraps `models.streamSimple` after `timing.ts` does, so each attempt is timed on its own. A request that fails before any content on a limit that clears with time does not fail: it waits inside its own stream, and goes on. Pi Durable sees one slow request. `limits.ts` (`classify`) reads the error text and the facts a recording `fetch` saw: status, limit headers, and a hint from a small 5xx body. A known status decides what can wait: 408, 429, and transient 5xx; 409 only with a reset time in a header; and 403 only in a usage limit's own shape with a reset time. An error that does not wait goes on as it is.
|
|
120
124
|
|
|
121
|
-
- **The key.** A limit that covers the account (a Claude subscription window, a ChatGPT or OpenCode Go usage limit) is held by the provider (`provider`), so one canary serves every model.
|
|
125
|
+
- **The key.** A limit that covers the account (a Claude subscription window, a ChatGPT or OpenCode Go usage limit) is held by the provider (`provider`), so one canary serves every model. Other shared failures (a 429 or an overload, or a cap for one Claude model) are held by `provider/modelId`. The key holds no token (it changes at each renewal) and no counter (it starts again at each start), so a renewal and a restart keep a gate. A sign-in or sign-out here drops the provider's gates (`LimitGate.reset`), and a failure of a request sent before one opens none (`Providers.signInEpoch`, compared within one request).
|
|
126
|
+
- **One request.** A 5xx that says the provider could not continue this conversation backs off only in its own stream. Its time and try count are separate from the shared gates. It is never saved. If the request was a shared gate's canary, the next waiter can try; the failure says nothing about whether that gate should open.
|
|
122
127
|
- **Waiting.** Until the reset (with 5 to 30 seconds added) or, with no time, 15 s, 30 s, 1, 2, 5, then 10 minutes. At most `limitWaitHours` (the owner's, default 6, 0 is off) for a known reset and 30 minutes without one; a reset farther away, or 40 tries, makes the gate give up (`refusing`): that request fails at once with the reset in its text, and for five minutes every request for the key fails at once, so Pi Durable's own three retries cannot start a second wait.
|
|
123
128
|
- **The canary is the real request.** A request the provider rejects costs nothing. One waiter sends it. When it gets content, the gate opens and the others leave one at a time, 1 to 5 s apart. A failure that is not a limit, or a Stop, frees the next waiter to try. Retry now (`POST /api/c/:id/limit/retry`, for whoever may see and steer the session) sets the gate due. A failure after content started is never replayed; Pi Durable retries it as before.
|
|
124
|
-
- **Durable.** Nothing here is stored as the truth. A restart replays the generation's `request` phase, which meets the limit again and waits again. `provider-limits.json` keeps the gates so that each waiting session does not send a rejected request first. It keeps a gate's first time (`since`) and a refusal with its end, so a restart does not start a wait again: a gate that nobody waits at, whose deadline passed (a stopped wait, or the server was down), does not refuse: it lets one request go as canary at once and keeps its first time, so a canary that meets the limit again gives up and no new full wait starts. One whose retry time passed but whose deadline did not tries at once too. A request also keeps its own first time and try count across
|
|
129
|
+
- **Durable.** Nothing here is stored as the truth. A restart replays the generation's `request` phase, which meets the limit again and waits again. `provider-limits.json` keeps the gates so that each waiting session does not send a rejected request first. It keeps a gate's first time (`since`) and a refusal with its end, so a restart does not start a wait again: a gate that nobody waits at, whose deadline passed (a stopped wait, or the server was down), does not refuse: it lets one request go as canary at once and keeps its first time, so a canary that meets the limit again gives up and no new full wait starts. One whose retry time passed but whose deadline did not tries at once too. A request also keeps its own first time and try count across the shared gates it moves through (a scope that changes does not start the wait again). It is a hint: a missing, damaged, or odd file means no limit is known. A close aborts every nap through the run's signal, so a close writes no failure, and Stop and Interrupt end a wait at once. Pi Pocket sets `restartLimit: Infinity` to turn off Pi Durable 1.4's crash-loop guard. Its task phases can wait for hours without changing state, so repeated unclean stops must not park them. This keeps the 1.3 behavior; the launcher already delays repeated server restarts. The wait can move to a Pi Durable retry decision hook later with no change that people can see.
|
|
125
130
|
- **No spend, no model choice.** A wait sends nothing but rejected requests. A gate never picks another model: only people do. Titles and PiP's summaries pass `noWait` and fail as they did.
|
|
126
|
-
- **What people see.** The room view's `live.limit`, the session list's `limited` (a session's subagents too), the peek summary, and a subagent's `limited` on its bar and the board: the live line, the square (`limited`), peek tiles, and one push (kind `limit`) when a wait of ten minutes or more begins.
|
|
131
|
+
- **What people see.** The room view's `live.limit`, the session list's `limited` (a session's subagents too), the peek summary, and a subagent's `limited` on its bar and the board: the live line, the square (`limited`), peek tiles, and one push (kind `limit`) when a wait of ten minutes or more begins. Wait and give-up reasons use fixed wording, not the provider's error text.
|
|
127
132
|
|
|
128
133
|
## Prompt cache keeper
|
|
129
134
|
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# The desktop apps
|
|
2
|
+
|
|
3
|
+
The Windows installer and the macOS package install a desktop app: **Pi Pocket**. It opens like any other app, with no console or Terminal window. It runs the server on this computer only, shows Pi Pocket in a window of its own that is already signed in, and puts an icon in the notification area (Windows) or the menu bar (macOS) with **Open**, **Restart server**, and **Quit**. [windows.md](windows.md) and [macos.md](macos.md) say how to install and remove it; this page says how it works.
|
|
4
|
+
|
|
5
|
+
The console launcher stays, as **Pi Pocket (console)**: it has the access menu (the local network, a Cloudflare tunnel, Tailscale), the keys, and the sign-in QR code.
|
|
6
|
+
|
|
7
|
+
## How it opens
|
|
8
|
+
|
|
9
|
+
| | Windows | macOS |
|
|
10
|
+
| --------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
11
|
+
| The app | `Pi Pocket.exe`, C# for the .NET Framework 4.x that Windows has | `Pi Pocket.app`, Swift and AppKit, one file for Apple silicon and Intel |
|
|
12
|
+
| Its source | [`packaging/windows/PiPocket.cs`](../packaging/windows/PiPocket.cs) | [`packaging/macos/app/main.swift`](../packaging/macos/app/main.swift) |
|
|
13
|
+
| The window | Edge in app mode (`msedge --app`), with a profile of its own | A `WKWebView` window, with the app bridge ([embedders.md](embedders.md)): badge, notifications |
|
|
14
|
+
| Its icon | The notification area. A click opens the window | **π** in the menu bar. Closing the window keeps it there; the Dock icon goes with the window |
|
|
15
|
+
| At sign-in (optional) | The Startup shortcut runs `Pi Pocket.exe --hidden`: the icon only | A LaunchAgent runs `open -g -a Pi Pocket.app --args --hidden`: the menu bar item only |
|
|
16
|
+
| The log | `%LOCALAPPDATA%\Pi Pocket\launcher.log`, and `launcher.old.log` from the run before | `~/Library/Logs/Pi Pocket/launcher.log`, and `launcher.old.log` |
|
|
17
|
+
|
|
18
|
+
1. **One app per user.** A second start (the Start menu again, Spotlight, the Dock) asks the first one to show its window, then exits. Windows uses a named mutex and event in the session's `Local\` namespace; macOS a distributed notification. `--quit` asks the running one to quit, as its **Quit** does; the installers use it.
|
|
19
|
+
2. **A server that runs already is used.** Each launcher writes `launcher-running.json` in the data folder when its server is ready, and removes it when it quits ([`src/launcher/desktop.ts`](../src/launcher/desktop.ts)): its process, the server's local address, and whether a desktop app started it. The app uses that server when the process is there and `GET /api/pocket/info` answers. **Quit** then leaves it running: another launcher, such as Pi Pocket (console), started it.
|
|
20
|
+
3. **Otherwise the app starts a launcher**, `pi-pocket --desktop`, with the install's own Node.js. `--desktop` means: this device only (unless `--access` says otherwise), no access menu, no keys, no sign-in link and no QR code in its output, and the choice is not saved as the console's last one. It stops when its standard input closes. The app holds that input: **Quit** closes it, and so does the end of the app, also when it crashes.
|
|
21
|
+
4. **The window signs in.** See below.
|
|
22
|
+
|
|
23
|
+
On Windows the launcher and everything it starts (the server, the commands of the agents, the Edge window) are in a job object that ends with the app, so nothing runs on after it, even when the app is killed. Edge's window closes on **Quit**, with the server it shows. Without Edge, the default browser opens the one-time link; it is not in the job, and stays.
|
|
24
|
+
|
|
25
|
+
On macOS the app starts the launcher through the user's login shell (`zsh -l`, or the user's own `bash`, `sh`, `ksh`, or `dash`), so the `PATH` of `~/.zprofile` (Homebrew, for example) reaches the sessions, as it does in Terminal. **Quit**, a logout, and a `SIGTERM` (from the installer) close the launcher's input and send it `SIGTERM`; after 20 seconds it gets `SIGKILL`.
|
|
26
|
+
|
|
27
|
+
## Sign-in
|
|
28
|
+
|
|
29
|
+
The owner's token is the key to the whole server, so it is never on a command line, in a window title, in the log, or in a crash report. The app reads it from `config.json` in the data folder, which only this user can read, and asks the server for a one-time sign-in link:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
POST /api/sign-in-link Authorization: Bearer <owner token>, X-Pocket: 1
|
|
33
|
+
→ { "path": "/login?once=<code>", "expiresInMs": 60000 }
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Only the owner can ask. The code is 32 random bytes, works once, and ends after a minute; the server keeps it only in memory, and at most 8 wait at once. `GET /login?once=<code>` sets the owner's sign-in cookie and goes on to the app, like the owner's `/login?token=` link. It does not ask before it switches a browser that is signed in as someone else (that question would put the token in the page): the app's window is the owner's own.
|
|
37
|
+
|
|
38
|
+
On Windows the one-time link is on Edge's command line, and only there: it is spent within a second, and then worth nothing. Edge's profile (`%LOCALAPPDATA%\Pi Pocket\Edge profile`) keeps the cookie, as a browser does; the uninstaller deletes it. On macOS the link goes straight into the window. `WKWebView` keeps the cookie in the app's own website data.
|
|
39
|
+
|
|
40
|
+
**Restart server** sends `POST /api/restart` with the same bearer token.
|
|
41
|
+
|
|
42
|
+
## What the apps rely on
|
|
43
|
+
|
|
44
|
+
A newer installer replaces the app; Menu → **Update Pi Pocket** does not. So an installed app runs against newer `pi-pocket` packages, and these stay as they are: `--desktop`, `launcher-running.json` (its fields only grow), `/api/pocket/info`, `/api/sign-in-link`, `/login?once=`, and `/api/restart`.
|
|
45
|
+
|
|
46
|
+
## What the window does not do yet
|
|
47
|
+
|
|
48
|
+
- macOS: no Web Push in a `WKWebView`, so notifications come through the app bridge while the app runs. Approvals in a notification have no **Allow** or **Deny** buttons: a click opens the session.
|
|
49
|
+
- Windows: Edge's app window is Edge. It has Edge's notifications, downloads, and file dialogs.
|
|
50
|
+
- A server on a Unix socket (`--socket`) has no address for the window: the app cannot use it, and its own launcher cannot start while that one runs.
|
|
51
|
+
|
|
52
|
+
## How it is tested
|
|
53
|
+
|
|
54
|
+
[`test/launcher-desktop.test.ts`](../test/launcher-desktop.test.ts) runs `--desktop`: `launcher-running.json`, the one-time link, no token in the output, and the stop when its input closes. On each pull request, [`windows.yml`](../.github/workflows/windows.yml) and [`macos.yml`](../.github/workflows/macos.yml) install the app, open it as the Start menu or Finder does, and check: no console or Terminal window, the server on this computer only, a window that signed in (on Windows, Edge spent the one-time link; on macOS, the window's own `/api/me` answers 200), no token in the log or on a command line, one instance only, and **Quit** that stops the launcher, the server, and the window. They also take a screenshot of the window. Nobody has tried them yet on a real PC or Mac, only on GitHub's runners.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reports approval waits, then shows a notice when a wait starts or ends. Copy this drop-in into
|
|
3
|
+
* `~/.pi-pocket/extensions/` and turn it on in Menu → Extensions. Call `approval_status` in a source session first.
|
|
4
|
+
*/
|
|
5
|
+
import { obj } from "@earendil-works/pi-schema";
|
|
6
|
+
import { type ConversationId, defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
|
+
// In the drop-in folder, import these types from "./_pocket.d.ts".
|
|
8
|
+
import type { Host, Web } from "../../types/pocket.d.ts";
|
|
9
|
+
|
|
10
|
+
export const pocketApi = 2;
|
|
11
|
+
|
|
12
|
+
export default function createApprovalMonitor(host: Host, web: Web) {
|
|
13
|
+
const approvals = host.pendingApprovals;
|
|
14
|
+
const watching = new Set<ConversationId>();
|
|
15
|
+
const disposers: (() => void)[] = [];
|
|
16
|
+
|
|
17
|
+
web.onDispose(() => {
|
|
18
|
+
for (const dispose of disposers) {
|
|
19
|
+
dispose();
|
|
20
|
+
}
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
return defineExtension({
|
|
24
|
+
name: "approval-monitor",
|
|
25
|
+
tools: [
|
|
26
|
+
Object.assign(
|
|
27
|
+
defineTool({
|
|
28
|
+
name: "approval_status",
|
|
29
|
+
description:
|
|
30
|
+
"List visible approval waits and watch for human decisions. Never answers a card.",
|
|
31
|
+
parameters: obj({}),
|
|
32
|
+
replay: "safe",
|
|
33
|
+
execute: async (_args, api) => {
|
|
34
|
+
if (approvals === undefined) {
|
|
35
|
+
return {
|
|
36
|
+
output: [
|
|
37
|
+
{
|
|
38
|
+
type: "text",
|
|
39
|
+
text: "Approval waits are not available on this server.",
|
|
40
|
+
},
|
|
41
|
+
],
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const source = api.conversationId;
|
|
46
|
+
|
|
47
|
+
if (!watching.has(source)) {
|
|
48
|
+
// Subscribe first. A snapshot reconciles state; events alone are not a restart log.
|
|
49
|
+
disposers.push(
|
|
50
|
+
approvals.on(source, "created", (approval) => {
|
|
51
|
+
host.notice(
|
|
52
|
+
"info",
|
|
53
|
+
`Waiting for a person: ${approval.summary}`,
|
|
54
|
+
source,
|
|
55
|
+
);
|
|
56
|
+
}),
|
|
57
|
+
approvals.on(source, "resolved", (approval) => {
|
|
58
|
+
host.notice(
|
|
59
|
+
"info",
|
|
60
|
+
`Approval wait ended: ${approval.outcome}`,
|
|
61
|
+
source,
|
|
62
|
+
);
|
|
63
|
+
}),
|
|
64
|
+
);
|
|
65
|
+
watching.add(source);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return {
|
|
69
|
+
output: [
|
|
70
|
+
{
|
|
71
|
+
type: "text",
|
|
72
|
+
text: JSON.stringify(approvals.list(source)),
|
|
73
|
+
},
|
|
74
|
+
],
|
|
75
|
+
};
|
|
76
|
+
},
|
|
77
|
+
}),
|
|
78
|
+
{ annotations: { readOnlyHint: true } },
|
|
79
|
+
),
|
|
80
|
+
],
|
|
81
|
+
});
|
|
82
|
+
}
|
|
@@ -49,6 +49,14 @@ if (!answer.answered) {
|
|
|
49
49
|
- **Do not keep the values** in `api.memo` or a document: a restart would find them there. A tool that asks is not safe to replay (the default), so a call that a restart cut off comes back as interrupted, and Pi asks again.
|
|
50
50
|
- Tell Pi what happened, never the values: "Signed in as the person".
|
|
51
51
|
|
|
52
|
+
## Observe an approval wait
|
|
53
|
+
|
|
54
|
+
An orchestration or status extension can observe waits through [`host.pendingApprovals`](reference/host.md#pendingapprovals), since 0.30.0 (experimental). It provides a pending snapshot and `created` and `resolved` events. It cannot allow, deny, or answer a card. Only the usual human interface can do that.
|
|
55
|
+
|
|
56
|
+
Give it a source session where Pi works for a known person. Core returns only approvals visible to that person and to everyone who can see the source. PiP waits are excluded. Tool arguments, free-text reasons, question contents, and answer values never leave this API; summaries are fixed text for the action.
|
|
57
|
+
|
|
58
|
+
Subscribe before listing, reconcile by id, and list again after a restart or an access change. As durable runs resume after a restart, the guard reconstructs a pending wait with the same id and original creation time. Events are not a stored history. See [the reference](reference/host.md#pendingapprovals) for cancellation and replay.
|
|
59
|
+
|
|
52
60
|
## Hide a value
|
|
53
61
|
|
|
54
62
|
`host.hide` keeps a value out of what Pi and people read, from now until you call the function that it returns. It becomes `[label]`:
|
|
@@ -53,6 +53,7 @@ These members are public:
|
|
|
53
53
|
- `thinkingLevels`
|
|
54
54
|
- `fetchPublic(url, init)` (experimental, since 0.20.0)
|
|
55
55
|
- `ask(request, context)`, `hide(value)`, `commandEnv(provider)`, `browser(conversationId, options)` (experimental, since 0.22.0: [People's values and the browser](../people-values.md))
|
|
56
|
+
- [`pendingApprovals`](../reference/host.md#pendingapprovals): read-only approval snapshots and events (experimental, since 0.30.0)
|
|
56
57
|
- `on(event, listener)` and the events of `AppEvents` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md))
|
|
57
58
|
|
|
58
59
|
These members are on `host` for Pi Pocket's own built-in extensions: `guard`, `approvals`, `schedules`, `goals`, `browsers`, `memory`, `watches`, `repoWatches`, `gallery`, `updates`, `pip`, `pipCompaction`, `toolNames`, `stopToolCall`, `waitsForLimit`, and `alertOwner`, and `linkedSessions.activity`, `linkedSessions.stopCall`, and `linkedSessions.onLedRun`. They are **internal**. A drop-in can read them, but their shapes can change in any release. One of them becomes public only through a request for an extension point ([core-or-extension.md](core-or-extension.md#ask-for-a-new-extension-point)).
|
|
@@ -16,6 +16,8 @@ Since 0.21.0, document definitions should name `checkpointWhen` in every `define
|
|
|
16
16
|
|
|
17
17
|
Since 0.28.0 (Pi 1.5), the main entry of `@earendil-works/pi-ai` does not export TypeBox's `Type`. A drop-in that imports `Type` from it still gets it: Pi Pocket gives drop-ins pi-ai with TypeBox's `Type` added, so their tool schemas stay as they were. New code builds its schemas with `@earendil-works/pi-schema` ([Tools](../tools.md#define-a-tool)). Since then, a watch listener (`api.watchDoc`) gets one call: `watch.start(async (call, context) => …)`, with `call.value`, `call.ops`, and `call.retired` when `call.kind` is `"value"`. A document that is retired does not end its watch with a `null` value any more: the next call has `retired: true`.
|
|
18
18
|
|
|
19
|
+
Since 0.30.0 (Pi 1.6), Pi Durable names `runEndTask` and `RunEndTask` `hookTask` and `HookTask`. A drop-in that imports the old names still gets them. A tool's `execute` can return a park in place of a result ([Tools](../tools.md#return-a-result)), and a sleeping task's `until` can be missing. The `durationMs` of a tool result is the time from the call's first run to its result, not the time of its last run.
|
|
20
|
+
|
|
19
21
|
## `pocketApi`
|
|
20
22
|
|
|
21
23
|
A module can export `pocketApi`: the server module, the browser module, or both.
|
|
@@ -101,3 +103,4 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
101
103
|
| `linkedSessions.reports`: a lead turns off run-end answers (experimental) | 0.29.0 |
|
|
102
104
|
| `options.artifact` and `options.version` in `pocket.openConversation`: open an artifact of that session (experimental) | 0.29.0 |
|
|
103
105
|
| `subagents: "always"` on a tool: the tool comes with every subagent that has a tool list (experimental) | 0.29.0 |
|
|
106
|
+
| `host.pendingApprovals`: read-only approval snapshots and events (experimental) | 0.30.0 |
|
|
@@ -246,6 +246,97 @@ web.onDispose(
|
|
|
246
246
|
);
|
|
247
247
|
```
|
|
248
248
|
|
|
249
|
+
## Approval observations
|
|
250
|
+
|
|
251
|
+
### `pendingApprovals`
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
readonly pendingApprovals: PendingApprovals;
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Since 0.30.0 · Experimental
|
|
258
|
+
|
|
259
|
+
Read-only snapshots and events for tool approvals and questions that wait for a person. This is the public observation API; the mutable approval service remains internal. It never approves, denies, or answers a question. Check that this member exists on older servers.
|
|
260
|
+
|
|
261
|
+
Each call names a top-level `source` session. It acts for the person Pi works for there, as `linkedSessions` does. An unknown session, a PiP, a source with no known requester, or a requester who no longer sees the source is refused. The snapshot includes only waits that the requester **and everyone who can see the source** can see. This prevents a tool from copying a private session's status into a shared transcript. Subagents use their parent session's audience. PiP waits are never exposed.
|
|
262
|
+
|
|
263
|
+
Snapshots and events are frozen copies. Arguments, commands, paths, free-text reasons, question titles and fields, answer values, and the answering person's name are withheld. `tool` and `summary` describe only the kind of action; an unknown tool name becomes `tool`. This deliberately withholds all argument text, not just text that looks like a secret.
|
|
264
|
+
|
|
265
|
+
#### `pendingApprovals.list`
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
list(source: ConversationId): readonly PendingApproval[];
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Since 0.30.0 · Experimental
|
|
272
|
+
|
|
273
|
+
The currently pending, visible waits, including waits in other visible sessions. Resolved waits are not kept as history. Subscribe first, then list, and reconcile by `id`. Re-list after a reload, reconnect, audience change, or restart. On a restart the durable guard hook reconstructs pending waits as runs resume; the snapshot can be empty until that happens. The same guard wait keeps its `id` and original `createdAt`. An old wait made before this API gets a time on its first replay with this version. Questions from `host.ask` keep their existing interrupted-call behavior: a retried question can have a new id.
|
|
274
|
+
|
|
275
|
+
#### `pendingApprovals.on`
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
on<E extends keyof ApprovalEvents>(
|
|
279
|
+
source: ConversationId,
|
|
280
|
+
event: E,
|
|
281
|
+
listener: (approval: ApprovalEvents[E]) => unknown,
|
|
282
|
+
): () => void;
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Since 0.30.0 · Experimental
|
|
286
|
+
|
|
287
|
+
Listen to `created` or `resolved`, and pass the returned disposer to `web.onDispose`. The subscription binds to the source's current requester. Core checks that person's current access and the source's whole current audience again before each delivery. Removing access stops delivery; it does not synthesize a resolved event. Reconcile a snapshot when access changes.
|
|
288
|
+
|
|
289
|
+
Listeners run after the change and do not block an approval. A throwing or rejecting listener is logged without its error text; other listeners still run. Events are live notifications, not a durable queue. A restarted server can emit `created` again for the same pending id; subscribers must handle duplicates. A stop or server shutdown cancels an in-memory wait, but a restart can reconstruct that same guard wait. Use `resolved` with `cancelled` as the end of this wait, not as a denial.
|
|
290
|
+
|
|
291
|
+
### `PendingApproval`
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
interface PendingApproval {
|
|
295
|
+
readonly id: string;
|
|
296
|
+
readonly conversationId: ConversationId;
|
|
297
|
+
readonly session: ConversationId;
|
|
298
|
+
readonly createdAt: number;
|
|
299
|
+
readonly tool: "bash" | "write" | "edit" | "ask" | "tool";
|
|
300
|
+
readonly summary: string;
|
|
301
|
+
readonly state: "pending";
|
|
302
|
+
}
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Since 0.30.0 · Experimental
|
|
306
|
+
|
|
307
|
+
- `id`: the approval's stable id, also used by its card in the app. It grants no permission to answer it.
|
|
308
|
+
- `conversationId`: the conversation that waits, which can belong to a subagent.
|
|
309
|
+
- `session`: the top-level session that contains it. A browser module can use `pocket.openConversation(Number(approval.session))` to open the session for a person.
|
|
310
|
+
- `createdAt`: Unix time in milliseconds.
|
|
311
|
+
- `tool`, `summary`: the kind of action, with all arguments redacted.
|
|
312
|
+
- `state`: always `pending` in a snapshot or `created` event.
|
|
313
|
+
|
|
314
|
+
### `ResolvedApproval`
|
|
315
|
+
|
|
316
|
+
```ts
|
|
317
|
+
interface ResolvedApproval extends Omit<PendingApproval, "state"> {
|
|
318
|
+
readonly state: "resolved";
|
|
319
|
+
readonly outcome: "allowed" | "denied" | "cancelled" | "superseded";
|
|
320
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Since 0.30.0 · Experimental
|
|
324
|
+
|
|
325
|
+
The same metadata, with `state: "resolved"` and an `outcome`. `allowed` and `denied` record the person's decision (submitted and declined for a question). `cancelled` means the waiting context ended without a decision; `superseded` means another request replaced this id. No answer values or person's name are included.
|
|
326
|
+
|
|
327
|
+
### `ApprovalEvents`
|
|
328
|
+
|
|
329
|
+
```ts
|
|
330
|
+
interface ApprovalEvents {
|
|
331
|
+
readonly created: PendingApproval;
|
|
332
|
+
readonly resolved: ResolvedApproval;
|
|
333
|
+
}
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Since 0.30.0 · Experimental
|
|
337
|
+
|
|
338
|
+
What each `pendingApprovals.on` listener receives. These events are source-scoped, not global `host.on` events.
|
|
339
|
+
|
|
249
340
|
## Asking people, hiding values, and the browser
|
|
250
341
|
|
|
251
342
|
These came in 0.22.0, and are experimental. [People's values and the browser](../people-values.md) tells how to use them together.
|
|
@@ -843,7 +934,7 @@ The page, with what Pi's `browser` tool does, but no script to run in it.
|
|
|
843
934
|
|
|
844
935
|
The host has more members, for Pi Pocket's built-in modules only. They are not in the types file, and they can change in any release without notice. Do not use them in a drop-in. [API stability](../policies/api-stability.md) tells you what this means.
|
|
845
936
|
|
|
846
|
-
- `approvals`:
|
|
937
|
+
- `approvals`: the mutable approval service, for the guard and app only. For public, read-only snapshots and events, use [`pendingApprovals`](#pendingapprovals).
|
|
847
938
|
- `guard`: Lancet Guard.
|
|
848
939
|
- `schedules`: scheduled messages, for the schedule tool. `schedules.limits` holds the limits in force (`perSession`, `chars`, `repeatMinutes`, `aheadDays`); the schedules module copies the owner's settings into it, so a module should read it and not change it. A server from before 0.24.0 has no `limits`.
|
|
849
940
|
- `background`: commands Pi runs in the background, for the background tool: `start`, `read`, `stop`, `list`, and `limits` (`running`, which the background module copies from the owner's setting). A server from before 0.24.0 has none.
|
package/docs/extensions/tools.md
CHANGED
|
@@ -55,6 +55,7 @@ Since 0.29.0, experimental: it can change in a minor release. This is an additio
|
|
|
55
55
|
- Pi Durable 1.2 renamed the result field `content` to `output`. Pi Pocket still reads `content` from what `execute` of a drop-in's tool returns, but new code must use `output`. A hook (`afterTool`) or a wrap (`wrapTool`) that reads or returns a result must use `output` too. A module that returns `output` exports `pocketApi = 2` ([API versions](reference/api-versions.md)): Pi Pocket 0.18 then refuses it with a clear message.
|
|
56
56
|
- To give the model an error, throw an `Error`. The model gets its message as an error result.
|
|
57
57
|
- `api.output(text)` streams output while the tool runs. When `execute` returns no `output`, this output becomes the result.
|
|
58
|
+
- Since Pi 1.6 (Pi Pocket 0.30.0), `execute` can return a park (`{ sleep: … }` or `{ wait: … }`) in place of a result, as Pi Durable's README tells. A park has no result fields: a wrap (`wrapTool`) that reads a result must let a park through. A call from a codemode script cannot park: Pi Pocket calls the tool's `cancel`, and the script's call fails with an error.
|
|
58
59
|
|
|
59
60
|
## Restarts and replays
|
|
60
61
|
|
package/docs/features.md
CHANGED
|
@@ -22,12 +22,12 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
22
22
|
- **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project, for everywhere, or for this session alone: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), everywhere's reach every session and PiP, and a session's own reach that session and its subagents for the rest of its life, through compaction and restarts, and no other session (since 0.29.0; Pi uses `scope: "session"` for something to keep only here). A fork starts with its session's lessons in force, as its own; what waits for approval stays with the session it was saved in. Archiving a session keeps its lessons for when it comes back. In PiP the same part is **PiP only**: lessons for PiP that no session gets. Menu → **Memory** (its hint says how many apply here, everywhere, and in this session) opens as a wide sheet; a switch at its top, **This project**, **Everywhere**, or **This session**, each with how many it holds and how many of them wait for approval, picks which it lists and where a lesson you type in goes. Each shows who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons, everywhere 30, and each session 20 of its own, each in a room of its own; past that, forget one first. A person's session lessons that wait count in that session only (20 at most there, and 40 in all sessions), not toward the 20 waiting elsewhere. A server from before 0.29.0 uses a session's lessons nowhere (it shows one that waits in the owner's queue, for "session “…”"), never as lessons for everywhere. Changes show as lines in the chat. Turn it off in Extensions.
|
|
23
23
|
- **A lean prompt.** A new session gets only the tools most conversations use. `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools wait, and so do their prompt sections; the prompt lists them with a line each, and Pi loads one with `tool_search` when a task needs it. On a model whose provider takes tool changes in the messages (Claude 4.8 and 5, and later), the tool joins the list and stays for the conversation; on any other, Pi calls it from a `codemode` script, so the tool list and the prompt cache never change. Long guides, such as the design guide and the page-to-app messages of artifacts, are files that Pi reads when it needs them. Turn the **Tool search** module off in Menu → Extensions to offer every tool every time. A test keeps Pi Pocket's own part of a plain session's prompt under 14,000 characters (about 5,000 tokens: schemas and this prose run at about 2.75 characters a token), so it does not grow by accident.
|
|
24
24
|
- **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
|
|
25
|
-
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or `/schedule every 30m between 9:00 and 17:00 on weekdays check the queue`, or Menu → **Scheduled messages** (also the violet pill on the left of the status line, which shows how many are set and, hovered, counts down to the next): Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Since 0.29.0 a repeat every so many minutes can run only inside a time window: `between 9:00 and 17:00`, and optionally `on weekdays`, `on weekends`, `on mon,wed`, or `on day`. It runs at the window's start on each day the window opens, then every so many minutes while before the end, which is excluded (9:00, 9:30 … 16:30); a repeat longer than the window runs once, at its start. An end at or before the start ends on the next day, so `between 22:00 and 6:00 on fri` runs from Friday night to Saturday morning; the start and the end cannot be the same. The start and the end are wall-clock times, and the runs between them are real minutes apart: on a night the clocks change, a window that holds the change is an hour shorter or longer, with a run less or more. A server older than 0.29.0 ignores the window and runs such a repeat all day. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. A repeat whose last message still waits in the session's queue (Pi is at work, or a run failed and holds it) sends no other at its next time: the time is skipped, a line in the chat counts the skips, and the Schedules sheet, the Running now board, and Pi's `schedule` tool list show how many there were (since 0.28.1). Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. The **Schedules** sheet lists them with a live countdown each; a tap on one opens an editor in its place, to change its message and when it goes out (**Once** on a date and time, **On days** at a time of day, or **Every** so many minutes, hours, or days, with **Only between** for a window and its days) with a preview of the next time, or to delete it, and **New schedule** opens the same editor, beside quick add in words. A change goes out as the work of whoever made it; a new time of day is on their device's clock, and other changes keep the time zone it was set in. **Pause** beside each schedule (and in its editor, and on Running now) stops it at once, without asking Pi: it sends nothing and stays in the list, dashed, until someone taps **Resume**. A repeat then goes on from its next time still to come, and a one-time message whose time passed while paused goes out at once. An edit keeps it paused. The pill and the countdowns count only schedules that go out; a session whose schedules are all paused shows "N paused". Pi's `schedule` tool lists a paused one as paused, and only a person resumes it. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
|
|
25
|
+
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or `/schedule every 30m between 9:00 and 17:00 on weekdays check the queue`, or Menu → **Scheduled messages** (also the violet pill on the left of the status line, which shows how many are set and, hovered, counts down to the next): Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Since 0.29.0 a repeat every so many minutes can run only inside a time window: `between 9:00 and 17:00`, and optionally `on weekdays`, `on weekends`, `on mon,wed`, or `on day`. It runs at the window's start on each day the window opens, then every so many minutes while before the end, which is excluded (9:00, 9:30 … 16:30); a repeat longer than the window runs once, at its start. An end at or before the start ends on the next day, so `between 22:00 and 6:00 on fri` runs from Friday night to Saturday morning; the start and the end cannot be the same. The start and the end are wall-clock times, and the runs between them are real minutes apart: on a night the clocks change, a window that holds the change is an hour shorter or longer, with a run less or more. A server older than 0.29.0 ignores the window and runs such a repeat all day. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. A repeat whose last message still waits in the session's queue (Pi is at work, or a run failed and holds it) sends no other at its next time: the time is skipped, a line in the chat counts the skips, and the Schedules sheet, the Running now board, and Pi's `schedule` tool list show how many there were (since 0.28.1). A repeat can **compact before each run** (a checkbox in its editor, or `compact_before` in Pi's `schedule` tool): before it sends, everything before its last message is summarized, so each run starts on the last run and what was said since, not on all the runs before, which a weekly job would otherwise pay for again each time. It suits a job that keeps its state in files. The first sending has nothing to compact; a session at work when the time comes sends without compacting, and a compaction that fails sends all the same. Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. The **Schedules** sheet lists them with a live countdown each; a tap on one opens an editor in its place, to change its message and when it goes out (**Once** on a date and time, **On days** at a time of day, or **Every** so many minutes, hours, or days, with **Only between** for a window and its days) with a preview of the next time, or to delete it, and **New schedule** opens the same editor, beside quick add in words. A change goes out as the work of whoever made it; a new time of day is on their device's clock, and other changes keep the time zone it was set in. **Pause** beside each schedule (and in its editor, and on Running now) stops it at once, without asking Pi: it sends nothing and stays in the list, dashed, until someone taps **Resume**. A repeat then goes on from its next time still to come, and a one-time message whose time passed while paused goes out at once. An edit keeps it paused. The pill and the countdowns count only schedules that go out; a session whose schedules are all paused shows "N paused". Pi's `schedule` tool lists a paused one as paused, and only a person resumes it. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
|
|
26
26
|
- **Done when.** `/until npm test`: after each of Pi's answers, the check runs in the session's folder; while it fails, Pi gets the end of its output and keeps going, for five checks at most. A bar above the message box shows how it stands. With Lancet Guard on, the check must be a command the guard allows outright. In plan mode the check waits until the plan is approved, and past a spend limit Pi stops going on. A check cut off by a server restart is not run again, as it may have done part of its work: Pi hears so, and its next answer is checked.
|
|
27
27
|
- **Mention files.** Type `@` in the message box to pick a file or folder from the session's folder: `@` alone lists its top, `@src/` a folder's own files, and anything else matches across the whole folder (`@srvapp` finds `src/server/app.ts`). Tab or Enter (or a tap) puts the path in, and a folder opens to its files. Pi gets the message as written, `@src/server/app.ts` and all, and reads what it names; or tap **Send them along** above the box to send the files' contents with the message, as Claude Code does (text files up to 100 KB each, images as images when the model takes them). The list is git's in a repository (so ignored files stay out), and a walk that skips hidden and dependency folders elsewhere; your browser fetches it once and matches as you type, so suggestions never wait on the network.
|
|
28
28
|
- **Shell commands.** `!git status` runs in the session's folder, and Pi sees the command and what it printed with your next message, as in Pi's terminal app; `!!git status` shows it only to the people here. While it runs, a row says so, with Stop (it is in Running now too). A restart while it runs does not run it again: its entry says it was cut off. With Lancet Guard on, a command from anyone but the owner must be one the guard allows outright. A command Pi sees counts as its person's message: Pi works for them from there, as for a steer. These are a person's own commands, not Pi's: plan mode does not hold them back. Stop one from its row, or from Running now on any device.
|
|
29
29
|
- **Quiet commands stop (since 0.29.0).** A bash command of Pi's that prints nothing for 15 minutes is stopped with the processes it started, and the call ends as timed out with what it printed, so a hung test run cannot hold a session or a subagent for good. A command that keeps printing, such as a long build, runs on, and Pi can give a call its own `timeout` instead. The owner changes the time in Menu → Extensions, under Background tasks (0: no limit); while Background tasks is off, the time last set there stays in force.
|
|
30
|
-
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. Tasks that end together go as one message, which joins the run in flight at its next pause rather than starting another turn (a steer, as a subagent's report is): several ending cost Pi one turn, not one each, and the answer it was writing keeps its place. A task Pi stops is not told about; one a person stops (in Running now) is, as Pi may wait for it (since 0.29.0). A task that prints nothing for 60 minutes is stopped, and Pi is told why; Pi starts a server or a watcher with `quietMinutes: 0` for no limit (since 0.29.0). In the conversation, that message shows as a card each, a group for several: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background**, its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). A tap on that count opens **Background** (Menu → **Background** opens it too, also when nothing runs): the session's commands, the newest first, and what the open one printed, as it comes. It asks again once a second while the task runs, so a dev server's log scrolls by itself; a scroll back up stops it following, and **Jump to the end** goes on. A tap on another command in the row above the log switches to it. **Stop** is there for anyone who may steer. Watching a task takes nothing from Pi: what it reads next stays where it was, so Pi still gets every line it has not read. Past the 20,000 characters the sheet keeps, or past what the log still holds, it says how many bytes it did not show. Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. Linux
|
|
30
|
+
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. Tasks that end together go as one message, which joins the run in flight at its next pause rather than starting another turn (a steer, as a subagent's report is): several ending cost Pi one turn, not one each, and the answer it was writing keeps its place. A task Pi stops is not told about; one a person stops (in Running now) is, as Pi may wait for it (since 0.29.0). A task that prints nothing for 60 minutes is stopped, and Pi is told why; Pi starts a server or a watcher with `quietMinutes: 0` for no limit (since 0.29.0). In the conversation, that message shows as a card each, a group for several: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background**, its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). A tap on that count opens **Background** (Menu → **Background** opens it too, also when nothing runs): the session's commands, the newest first, and what the open one printed, as it comes. It asks again once a second while the task runs, so a dev server's log scrolls by itself; a scroll back up stops it following, and **Jump to the end** goes on. A tap on another command in the row above the log switches to it. **Stop** is there for anyone who may steer. Watching a task takes nothing from Pi: what it reads next stays where it was, so Pi still gets every line it has not read. Past the 20,000 characters the sheet keeps, or past what the log still holds, it says how many bytes it did not show. Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. It needs bash and `split`. Since 0.30.0 it runs on Linux, macOS, and Windows (before, Linux only). Each platform knows a process by its pid and its start time together, so a stop never hits a process that took a task's pid later. Linux reads `/proc`, and macOS reads `ps`: a task is its process group, and a process that left the group is found by its marker. Windows has no process groups or signals: a task is its first process and what it starts (by parent and start time), held in a job object while the server runs, through a small PowerShell helper; it needs Git Bash, and a stop ends the processes by force at once. On Windows, a process in a task cannot leave its job, a process started outside it (through a service) is not followed, and a task does not say what it left running ([Windows](windows.md) lists what is weaker there).
|
|
31
31
|
- **Extensions' commands.** A module can add commands to the message box (`/clock-zone Europe/Berlin`), which do something without asking Pi: show a status, change a setting. They show in the suggestions with the app's own, after them; a prompt template of the same name wins. What one gives back is a notice for you alone, or a card of plain text in the conversation for everyone there, which Pi never sees and which does not change whom Pi works for; Find in session and export include it. A conversation command is for whoever may steer (whoever drives, while people take turns); a global one is the owner's, also while someone else drives; viewers get none. Each run is a durable task: sending the same text again after a lost reply gets the first run's result, a restart never runs one again, and Running now shows and stops it. See [Writing extensions](extensions/commands.md).
|
|
32
32
|
- **A person's role and the page's scroll, for extensions.** Since 0.27.0, two experimental members. `host.roleOf(personId)` gives a person's role (`owner`, `guest`, or `viewer`), or `undefined` for an id that is not a person here. It reads the role that core already uses, so a module that guards owner-only things can ask whether Pi works for the owner (`host.requesterOf` gives the id). The snapshot of `host.browser` has a `scroll` field, `{ y, viewport, height }` in CSS pixels, the same numbers that Pi's `browser` tool shows as "scrolled 0 of 800px". See [Writing extensions](extensions/host.md).
|
|
33
33
|
- **Folded inputs.** An extension can send a message the conversation shows as one line: a short label, and a summary when the message has one. Tap the line to read the message. Tap the message for its sheet, where **Show**, **Fold**, and **Hide** choose how every input of that kind shows in this browser: as a message, as the line (the usual choice), or hidden until Find jumps to it. A hidden message still starts its turn. An extension's browser code can pick one for you until you choose. The queue shows the same line. Export keeps the whole message in a folded block. Find searches the label, the summary, and the whole message, however long; Copy text copies all of it. An input the extension stored as its own kind is not a message you can send again. Peek tiles and PiP show the one line. The model still reads the whole message. Since 0.28.0.
|
|
@@ -47,7 +47,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
47
47
|
- **Watch a pull request.** Menu → **Watch pull request**, `/watch` (or `/watch 123`, `/watch <PR address>`), or Pi's `watch_pr` tool, which it can start after opening a PR (Pi only for its folder's repository, by number; a person for any): until the PR is merged or closed, Pi Pocket looks at it on GitHub every few minutes with the `gh` command signed in on the server, and tells Pi in the session what needs doing, as a message sent through the watch for whoever set it up: checks that failed on its last commit (once all of them finished, with the end of each GitHub Actions log), conflicts with its base branch, and new comments and reviews. Only comments from the repository's owner, and from organization members and collaborators whom GitHub says can write to it, count, and bots' reviews (a member may only read, a collaborator only triage: `gh` asks GitHub, at most every ten minutes for each person, and GitHub tells only an account that can push there, so on a PR where yours cannot, such as a fork's PR to someone else's repository, only the owner's count, and the watch says so); your own account's (which Pi posts as) only when they mention @pi in their own words (not in a quote or code), so Pi never answers itself. Comments keep their lines (a suggested change is code), 30 at most in a message (read newest first, so a burst never hides the new ones); each is told once, and what does not fit in one message comes in the next; nothing goes while Pi is busy there or, with take turns on, while someone else drives (the bar says it waits, and nothing counts as failed); and a watch sends 10 messages at most. While Triggers is off it asks GitHub nothing. A bar above the message box shows the PR, its checks, and how many messages went, with **Stop**. It ends, with a line in the chat and a notification, when the PR is merged or closed, when there is more to tell than it may send, after two weeks with nothing new, or after an hour of looks that failed (the bar says why). Logs reach Pi fenced as data, which nothing in them can end early, and titles, check names, and branches come on one line, quoted, as data too. It needs `gh` installed and signed in (`gh auth login`) on the server, on GitHub Enterprise hosts too: a host other than github.com is used only when `gh` is signed in there (`gh auth login --hostname <host>`; a token only in `GH_ENTERPRISE_TOKEN` does not count), for Pi, PiP, and people alike, and Pi names a PR by address only on github.com or its folder's own host.
|
|
48
48
|
- **Watch a repository.** Tell PiP in plain words, such as "watch acme/api: when CI fails on main, fix it and tell me" or "when I open an issue labelled pi in acme/web, work on it": it sets up a watch that looks at the repository on GitHub every few minutes with `gh` (no public address needed, unlike a webhook), and what is new there (issues and pull requests opened, CI failing on a branch, releases, someone writing @pi, as a word of its own, in a comment or an issue) comes to PiP, or to a session you name, with your instructions; PiP then acts on it: it starts a session in the repository (its checkout here, or a clone it makes in the data folder's `repos/`), sends it the task, follows it, and tells you what came of it. A watch can be narrowed to a label, to issues assigned to you, or to a branch's CI (mentions of @pi are not narrowed). CI is the branch's own runs: pushed to it, scheduled, started by hand or through the API, or started by another workflow, in the repository itself, never a pull request's or an issue's (a renamed repository keeps working). Only repositories `gh`'s account can push to can be watched or worked on, and issues and pull requests count only from the repository's owner, and organization members and collaborators whom GitHub says can write to it (and bots' pull requests), unless you turn on **From anyone** on the watch in Menu → Webhooks and watches (PiP cannot); @pi always only from them. PiP works in a checkout of a session you started, or in a clone it makes, which appears only once complete (a clone a restart cut off leaves a `~part-…` folder, removed at the next clone of that repository); a different folder already where the clone goes is reported, never overwritten. While Triggers is off, watches wait and ask GitHub nothing; while PiP is off, a watch to PiP holds what it found, and its note says so. What came from GitHub is fenced as data, each thing is told once, ten in a message and twelve messages an hour at most (the rest come next), and a look that fails is tried again, less often each time, with the reason shown. Menu → **Webhooks and watches** lists the watches, to remove one; or ask PiP ("what are you watching?", "stop watching acme/api"). PiP can also start a PR watch on a session ("see acme/api#12 through"), and Pi's own `watch_pr` takes a PR in another repository it can push to by its address or `owner/name#12`, telling Pi to work in a checkout of it. Part of the **Triggers** extension.
|
|
49
49
|
- **Webhooks.** Menu → **Webhooks and watches**: an address that other services (GitHub, a deploy, a monitor) post to, each post becoming a message to Pi in a session, or to PiP, as the work of whoever made the hook: their instructions first ("When a deploy fails, find out why and fix it"), then what was posted, trimmed of noise such as API addresses, and fenced as data. PiP gets them as folded cards and decides what to do: start a session, message one, or tell you. A GitHub hook is signed: GitHub gets the address and, separately, a secret (its Payload URL and Secret), and a post gets in only with GitHub's signature made with it, so whoever sees the address (the repository's admins do, in its settings) cannot post as the hook. Unless a GitHub hook is made **From anyone**, what people outside the repository wrote does not reach Pi (the repository's people are its owner, and the organization members and collaborators whom GitHub says can write to it, asked through `gh`, which must be signed in to the host and able to push there, or else only the owner counts; bots count on pull requests and what is said on them, never on issues): a post an outsider started (their issue, comment, pull request, review, or discussion) is dropped with a 202 that says so; in a post the repository's people started, the body of anything an outsider wrote in it (the issue under a member's comment, a review thread's comments) is left out, its title kept; a workflow run goes only when a branch of the repository itself started it (a push, a schedule, a manual or API dispatch, or another workflow), so one a pull request (a fork's too), an issue, or a comment started is dropped, and so is one whose head repository GitHub does not show; workflow jobs, check suites, and check runs do not say where their run came from, so they are dropped too, as are a commit status on no branch of the repository (a fork's commit) and a security advisory someone reported; and pushes, releases, and other posts that name no author go as they came. A hook for another service has the secret in its address instead: anyone who has the address can message Pi as the hook's person. **New secret** shuts out the old one, for an address or a secret that got out. Anything else gets 404. A post GitHub sends again goes to Pi once, GitHub's ping gets an answer and is nothing for Pi, a hook takes 30 posts an hour of up to 5 MB each (the server reads eight at a time, two to one hook, each within 15 seconds; past that, 503 with Retry-After), a hook to PiP answers 503 while PiP is turned off, and a post that cannot go now (someone else drives, a spend limit) gets a 409 that says no more. Services must be able to reach the server: through a tunnel, a public address works for GitHub. People who can steer make hooks for the sessions they can reach; each sees their own, the owner every one. Choose **Edit prompt** to change a hook's instructions, then **Save** or **Cancel**. Only the hook's creator or the server owner can save changes, and they need steering rights. You can enter up to 2000 characters. Leave the instructions empty to ask Pi to summarize what happened and whether anything needs doing. Saved changes apply to later posts. The address, secret, destination, and usage history stay unchanged. Webhooks and the Relay (the next item) deliver the same way, through core's inbox: the same fence, the same once-only key, and a limit for each source. The watch and webhooks are the **Triggers** extension: turned off, watches wait and hooks answer 503.
|
|
50
|
-
- **Relay.** Menu → **Extensions** → **Relay** (off by default) lets a chat service or a feed send messages to a session, with no separate relay service and no public address: each connector makes outbound connections only (it polls, or keeps a stream open), and delivers inside the server. Menu → **Relay** (the owner only) adds a connector: choose its kind, a session, and instructions for Pi, then its fields. **Discord** needs a bot token, and the bot's **Message Content Intent** turned on in the Developer Portal; **Slack** uses Socket Mode, with an app token (`xapp-…`) and a bot token (`xoxb-…`); **Telegram** needs a bot token; **Matrix** needs a homeserver address and an access token; **RSS** needs a feed address; **HTTP** polls any JSON address, with headers, the fields of an item, and an optional reply address. For a chat service, give channel, chat, or room IDs, or leave them empty for all the bot can see; for direct messages, Discord has its own switch. Each message comes to the session as `[via relay <name>]`: the owner's instructions first, then the sender, then what was written, fenced as data in `<relay-message>` tags. Pi answers with the `relay_reply` tool, which only a session that a connector delivers to is offered; a reply goes to where the message came from, and a call that runs again sends once. On **Discord**, **Slack**, **Telegram**, and **Matrix**, Pi can send images and files from the session's folder with a reply (10 files; 10 MB each on Discord, 50 MB on the others, 100 MB in all; never a hidden file, a file outside the folder, or the server's data), and can download an attachment that a person posted with `relay_fetch`, into `.relay/` in the session's folder, where it reads an image (25 MB at most, 20 MB on Telegram); the token and the file's link never reach Pi. Slack needs the `files:write` and `files:read` scopes for this, and Matrix fetches nothing from an encrypted room. Each event is delivered once, also across restarts: what came waits on disk until the session takes it (a busy session, a spend limit, or a restart do not lose it). Messages from bots, and from the connector's own account, are dropped. **Mention only** takes messages that name the bot, or that come in a direct message. **Owner IDs** are your own accounts on the service: Pi reads them as an id you marked as trusted (guidance for the model, not a boundary, since some services let a person pretend to be another), and they have no limit; every other author has 10 messages an hour by default, and a connector 30 an hour (both can be changed; a feed's items, RSS, or HTTP without an author id field, have only the connector's limit), and a message over a limit is dropped and counted. The first look at a feed or an address takes nothing that was there before. Tokens are kept on the server only (a file of mode 0600 in the data folder's `x.pocket-relay`, which Pi's tools cannot read), never reach the browser (it only shows that one is set), and are hidden from transcripts and errors. A connector that fails shows why and tries again, less often each time; a refused token stops it until you edit it, and an error never stops the server. Drop-in extensions can add kinds of connectors ([Relay connectors](extensions/relay.md)).
|
|
50
|
+
- **Relay.** Menu → **Extensions** → **Relay** (off by default) lets a chat service or a feed send messages to a session, with no separate relay service and no public address: each connector makes outbound connections only (it polls, or keeps a stream open), and delivers inside the server. Menu → **Relay** (the owner only) adds a connector: choose its kind, a session, and instructions for Pi, then its fields. **Discord** needs a bot token, and the bot's **Message Content Intent** turned on in the Developer Portal; **Slack** uses Socket Mode, with an app token (`xapp-…`) and a bot token (`xoxb-…`); **Telegram** needs a bot token; **Matrix** needs a homeserver address and an access token; **RSS** needs a feed address; **HTTP** polls any JSON address, with headers, the fields of an item, and an optional reply address. For a chat service, give channel, chat, or room IDs, or leave them empty for all the bot can see; for direct messages, Discord has its own switch. Each message comes to the session as `[via relay <name>]`: the owner's instructions first, then the sender, then what was written, fenced as data in `<relay-message>` tags. Pi answers with the `relay_reply` tool, which only a session that a connector delivers to is offered; a reply goes to where the message came from, and a call that runs again sends once. On **Discord**, **Slack**, **Telegram**, and **Matrix**, Pi can send images and files from the session's folder with a reply (10 files; 10 MB each on Discord, 50 MB on the others, 100 MB in all; never a hidden file, a `.env` file such as `prod.env`, a file outside the folder, or the server's data), and can download an attachment that a person posted with `relay_fetch`, into `.relay/` in the session's folder, where it reads an image (25 MB at most, 20 MB on Telegram); the token and the file's link never reach Pi. Slack needs the `files:write` and `files:read` scopes for this, and Matrix fetches nothing from an encrypted room. Each event is delivered once, also across restarts: what came waits on disk until the session takes it (a busy session, a spend limit, or a restart do not lose it). Messages from bots, and from the connector's own account, are dropped. **Mention only** takes messages that name the bot, or that come in a direct message. **Owner IDs** are your own accounts on the service: Pi reads them as an id you marked as trusted (guidance for the model, not a boundary, since some services let a person pretend to be another), and they have no limit; every other author has 10 messages an hour by default, and a connector 30 an hour (both can be changed; a feed's items, RSS, or HTTP without an author id field, have only the connector's limit), and a message over a limit is dropped and counted. The first look at a feed or an address takes nothing that was there before. Tokens are kept on the server only (a file of mode 0600 in the data folder's `x.pocket-relay`, which Pi's tools cannot read), never reach the browser (it only shows that one is set), and are hidden from transcripts and errors. A connector that fails shows why and tries again, less often each time; a refused token stops it until you edit it, and an error never stops the server. Drop-in extensions can add kinds of connectors ([Relay connectors](extensions/relay.md)).
|
|
51
51
|
- **Spend and limits.** Menu → **Spend** shows a large total and usage bars (against a limit, or the largest spend in that group): what Pi spent per person (the work goes to whoever asked for it) and per session, subagents included. The owner can limit a session or a person: past the limit Pi takes no new messages there, scheduled messages and goals stop, a run that crosses it stops, and subagents' reports wait instead of starting Pi again: the subagents bar says why (the owner gets **Raise it**), and they go to Pi together once the limit is raised, those that were in the queue when the run stopped included. The status line shows a session's spend and limit; for a session with a limit that started linked sessions (Agent Teams), the spend it shows, here and in the sheet, is the team's, as its limit counts it. PiP's row shows its limit too, and PiP's notices (such as a stop at its limit) show in its panel. Spend per person counts from the first start of a version with this feature; what was spent before shows for its sessions only.
|
|
52
52
|
- **A session's folder.** **New** (or Alt+N) opens a folder picker laid out as a desktop's file dialog, in the folder of the session you are in (or the server's folder, on the home screen): the path on top (tap a part to go back up, or its end to type a path), places at the side (Home, Computer, the server's default workspace when it is another folder, and recent folders; pin the default workspace there to start every new session in it, in this browser, since 0.28.0), the folders where you are, and **Cancel** and **Open** at the bottom, with **Own git worktree** and **Show hidden** beside them. With a mouse, a click selects a folder and a double click goes into it; on a touch screen, a tap goes into it. **Open** starts the session in the selected folder, or in the one you are in, as the **Folder:** line says. Keys work as in a file dialog: arrows, Enter, Backspace to go up, letters to jump, `/` or Ctrl+L to type a path, Ctrl+Enter to open. The star on the **Folder:** line keeps that folder among the places as a favorite (tap it again to let it go). Favorites are each person's own, saved on the server, and change at once on all their devices; while New session is open, Ctrl+1…9 (⌘1…9 on a Mac) starts a session in one of the first nine, with **Own git worktree** as it is set. **New folder** makes a folder where you are and goes into it; a typed path that is not there yet offers **Create it**. Menu → **Working directory** (or `/cwd`) moves a session with the same picker. Someone invited to one session cannot browse or make folders. The launcher lists these too: **New session here** for the folder you are in, and **New session in** and its name for each favorite; each starts a session there at once, without a worktree of its own.
|
|
53
53
|
- **Branch.** The top bar shows the git branch the session's folder has checked out, under the session's title beside the folder, and follows it when Pi or anyone else switches (in a terminal too, within seconds). Tap it (or Menu → **Branch**, the launcher, `/branch`, or the branch in Changes, which stays in sight however long the folder's path) for the branch picker, down from it: the folder's branches with the current one first, then the newest, each with its last commit and how far it is ahead of or behind its remote branch, and the remote branches it has no local branch for. Type to search; a name that is no branch yet makes one from what is checked out (spaces become dashes), and a remote branch becomes a local one that follows it. Uncommitted changes come along, and when git would overwrite them it says so and nothing changes. A branch checked out in another worktree is listed but switched to only there. Switching changes the files under Pi, so as with moving the session to another folder it waits while Pi works and, while taking turns, is the driver's; Pi is told. Viewers see the branch; someone invited to one session can look but not switch.
|
|
@@ -134,7 +134,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
134
134
|
- **Code in your messages.** In a message you send, `` `code` `` and a fence of ` ``` ` lines show as code, the way Pi's replies show it, colored when the fence names a language (` ```js `). A span closes with as many backticks as opened it, a fence's lines stand on their own, and a stray or unclosed one stays text. Nothing else is formatted: `*`, `#`, lists, and spacing stay as typed, and @mentions outside code stay buttons. Only the display changes: Pi, exports, and ↑ get the message as written.
|
|
135
135
|
- **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact` call with `inline: true` (an `artifact_inline` call, in a session from before 0.28.0) shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
|
|
136
136
|
- **Images inline.** Attached images show as thumbnails (also in the composer before you send). When Pi writes `` with a path on the server (absolute, `~/…`, or relative to the session's folder), the image shows in its reply. Images a tool returns and SVG artifacts show inline too; an image Pi reads with `read` (often one you just sent) shows only when its call is opened, so it is not on screen twice. `read` shrinks an image larger than the model takes (more than 2000 pixels a side, say) and converts BMP, with Photon in a worker thread that exits after 30 seconds idle; without Photon, the server still starts and `read` refuses such an image. Tap any image to see it full screen. Only real image files are shown: the server checks a file's bytes, not just its name.
|
|
137
|
-
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, Tailscale, or Tailscale Serve. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
|
|
137
|
+
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, Tailscale, or Tailscale Serve. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access. With `--socket PATH`, for a reverse proxy on the same machine, it asks nothing: the server listens on that Unix socket, and the launcher shows the sign-in path to open at the proxy's address, with no QR code ([README](../README.md#behind-a-reverse-proxy-on-a-unix-socket)).
|
|
138
138
|
|
|
139
139
|
## Limitations
|
|
140
140
|
|
package/docs/index.md
CHANGED
|
@@ -42,6 +42,9 @@ A drop-in extension stays when Pi Pocket updates, and the owner can turn it off
|
|
|
42
42
|
- [embedders.md](embedders.md): the app bridge, for an embedder (an app that shows Pi Pocket inside itself, such as an Electron or Tauri wrapper): `/api/pocket/info`, `window.pocketHost`, and notifications without Web Push.
|
|
43
43
|
- [docker.md](docker.md): running Pi Pocket in a container, with extensions, themes, Pi's folder, and the workspace mounted from the host.
|
|
44
44
|
- [systemd.md](systemd.md): running Pi Pocket as a systemd service, with a template unit whose instance name is the access mode.
|
|
45
|
+
- [desktop-app.md](desktop-app.md): the desktop apps of the Windows installer and the macOS package: the window, the tray or menu bar icon, `--desktop`, `launcher-running.json`, and the one-time sign-in link.
|
|
46
|
+
- [windows.md](windows.md): the Windows installer: SmartScreen, where it installs, updates, uninstall, and how it is built and tested.
|
|
47
|
+
- [macos.md](macos.md): the macOS package: Gatekeeper, where it installs, updates, uninstall, and how it is built and tested.
|
|
45
48
|
- [map.md](map.md): where each part of the code is, and how to add the usual things.
|
|
46
49
|
- [architecture.md](architecture.md): how the parts depend on each other, and the orders that they need.
|
|
47
50
|
- [features.md](features.md): what each feature does, as people use it.
|