pi-pocket 0.28.0-beta.6 → 0.28.0-beta.7
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 +1 -1
- package/docs/architecture.md +9 -1
- package/docs/{desktop.md → embedders.md} +33 -28
- package/docs/examples/clock.ts +3 -5
- package/docs/examples/my-words.ts +2 -2
- package/docs/examples/quiet-note.ts +4 -4
- package/docs/examples/read-page.ts +4 -6
- package/docs/extensions/first-extension.md +2 -2
- package/docs/extensions/hooks.md +4 -0
- package/docs/extensions/reference/api-versions.md +2 -0
- package/docs/extensions/reference/theme-surface.md +1 -1
- package/docs/extensions/tools.md +2 -2
- package/docs/extensions.md +2 -2
- package/docs/features.md +7 -6
- package/docs/index.md +1 -1
- package/docs/map.md +14 -13
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +103 -58
- package/package.json +9 -7
- package/src/launcher/main.ts +25 -9
- package/src/launcher/serve.ts +19 -14
- package/src/server/alerts.ts +8 -8
- package/src/server/app.ts +87 -41
- package/src/server/background.ts +10 -2
- package/src/server/commands.ts +58 -1
- package/src/server/custom-providers.ts +76 -16
- package/src/server/design/index.ts +68 -61
- package/src/server/design/scan-fig-nodes.ts +13 -4
- package/src/server/design/scan-fig.ts +119 -47
- package/src/server/design/scan-infer.ts +8 -1
- package/src/server/design/scan-tree.ts +12 -1
- package/src/server/design/system.ts +77 -74
- package/src/server/entry-format.ts +5 -0
- package/src/server/extension-document-imports.ts +9 -1
- package/src/server/extension-pi-ai-compat.ts +22 -0
- package/src/server/extensions/agent-teams.ts +24 -26
- package/src/server/extensions/artifacts.ts +53 -47
- package/src/server/extensions/ask-someone.ts +13 -10
- package/src/server/extensions/ask.ts +31 -24
- package/src/server/extensions/background.ts +20 -18
- package/src/server/extensions/browser.ts +92 -90
- package/src/server/extensions/codemode.ts +7 -3
- package/src/server/extensions/memory.ts +19 -15
- package/src/server/extensions/pip.ts +162 -162
- package/src/server/extensions/schedules.ts +20 -18
- package/src/server/extensions/subagents.ts +32 -24
- package/src/server/extensions/tool-search.ts +12 -9
- package/src/server/extensions/triggers.ts +14 -14
- package/src/server/http/api.ts +14 -1
- package/src/server/http/events.ts +5 -1
- package/src/server/http/push-routes.ts +1 -1
- package/src/server/http.ts +6 -6
- package/src/server/linked-sessions.ts +26 -23
- package/src/server/pi-sessions.ts +261 -51
- package/src/server/pip-compact.ts +11 -0
- package/src/server/pip.ts +5 -1
- package/src/server/projection.ts +11 -2
- package/src/server/providers.ts +37 -0
- package/src/server/push.ts +5 -5
- package/src/server/reload.ts +69 -5
- package/src/server/resend.ts +4 -1
- package/src/server/room.ts +103 -20
- package/src/server/running.ts +2 -2
- package/src/server/tool-schema.ts +20 -0
- package/web/agent-tile.js +4 -1
- package/web/app.js +2 -2
- package/web/composer.js +14 -36
- package/web/diff.js +4 -3
- package/web/{desktop.js → embedder.js} +33 -20
- package/web/history.js +10 -12
- package/web/host.js +3 -3
- package/web/notify.js +5 -5
- package/web/person-storage.js +99 -0
- package/web/pip-attachments.js +5 -2
- package/web/pip.js +99 -27
- package/web/quote-reply.js +109 -21
- package/web/sheets/appearance.js +14 -0
- package/web/sheets/menu.js +6 -6
- package/web/store.js +288 -40
- package/web/style.css +129 -14
- package/web/subagents-board.js +17 -2
- package/web/subagents.js +25 -1
- package/web/theme.js +2 -0
- package/web/transcript.js +16 -6
- package/web/ui.js +56 -0
- package/web/window-controls.js +3 -3
package/README.md
CHANGED
|
@@ -52,7 +52,7 @@ The launcher asks how your devices should connect, then prints a sign-in link an
|
|
|
52
52
|
|
|
53
53
|
While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
|
|
54
54
|
|
|
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
|
|
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
57
|
### Other ways to run it
|
|
58
58
|
|
package/docs/architecture.md
CHANGED
|
@@ -7,10 +7,12 @@ How Pi Pocket's parts depend on each other, and the orderings the code relies on
|
|
|
7
7
|
Pi Durable owns the lasting state of conversations: conversations, entries, tasks, and Pi Pocket's documents (`docs.ts`), in `pocket.sqlite`. People and settings, push subscriptions, uploads, and worktrees are files beside it ([map.md](map.md#data-pi-pocket-or-pi_pocket_dir)). What `PocketApp` keeps in memory about conversations is read back from storage:
|
|
8
8
|
|
|
9
9
|
- At startup, `#recover` reads each conversation's run, agent, chat, subagents, and who Pi works for in it.
|
|
10
|
-
- After that, every commit goes through `#committed`, which keeps the memory up to date.
|
|
10
|
+
- After that, every stored commit goes through `#committed`, which keeps the memory up to date.
|
|
11
11
|
|
|
12
12
|
Pi Durable 1.4.0 migrates SQLite storage to schema version 2 when it opens. Older Durable versions cannot open that database. Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.21.0.
|
|
13
13
|
|
|
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
|
+
|
|
14
16
|
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`.
|
|
15
17
|
|
|
16
18
|
Some state lives in this process alone, and a restart forgets it. For example:
|
|
@@ -165,6 +167,8 @@ Pi Durable publishes each commit's changes in no set order. `#committed` handles
|
|
|
165
167
|
- Document changes go to `#documentCommitted`. It tracks busy and ended runs, agents, the session list, and the documents the rooms show (`ROOM_DOCS`).
|
|
166
168
|
- Submissions go to `attribution.submissionCommitted`.
|
|
167
169
|
|
|
170
|
+
It gets each commit once it is stored (`Harness.observeCommits`). Since Pi Durable 1.5, a partial answer and running tool output are stored later than they are shown: with the next commit that reads `pi.live` (the end of the answer, a tool that settles, the end of a run), and at the latest after `settings.progress.persistWithinMs` (1 second). A room's watch of its conversation's view (`Conversation.watch`) shows each at once. A crash loses up to about a second of a streamed answer. Pi Durable detaches an observer that throws, so `#committed` catches what one commit throws, and the app keeps hearing of the next ones.
|
|
171
|
+
|
|
168
172
|
Everything here is synchronous. A commit listener may not call the harness's session APIs, so a write it causes (noting a message's author, or moving a session up the list when Pi starts work there) runs in `setImmediate`. Keep this one coordinator: separate listeners would make their registration order a billing rule nobody can see.
|
|
169
173
|
|
|
170
174
|
Updates to tabs are coalesced:
|
|
@@ -181,6 +185,8 @@ The message Pi is writing goes as what changed since the tab's last update (`liv
|
|
|
181
185
|
|
|
182
186
|
A tab's connection names what its code understands (`p`, `PROTOCOL` in `web/store.js`). 2 keeps the queue when an update leaves it out; 3 takes the message as what changed; 4 takes a full view with only the newest entries; 5 takes them light at first; 6 names what it kept of the session and takes the order as what comes after it. A tab below 3 gets the whole message with each update, and one that names none (older code, as a tab asleep through an update keeps) also gets the queue with each update, because its code drops a queue that an update leaves out.
|
|
183
187
|
|
|
188
|
+
A room keeps the active context's entries itself. Since Pi Durable 1.5, a conversation's view holds only a window of the newest 50 to 100 entries of the whole history. The room reads the active context from `Conversation.context()` as it opens, after each new head marker (a compaction, a reset), and when the window no longer reaches the newest entry the room has. Between these reads, it adds the entries the window adds.
|
|
189
|
+
|
|
184
190
|
A full view for a tab of protocol 4 has the order of every entry in the active context, but only the entries of the newest 80 rows (`firstEntries` in `projection.ts`), with the turn the oldest of them is in, so the tab knows which groups are open there. The tab draws 60 of the rows, and the panel for PiP draws 80. Earlier entries come from `GET /api/c/<id>/context?before=<entry>`, with `rows=<n>` or `from=<entry>` (`Room.entriesBefore`, `loadEarlier` in `web/store.js`), when the person shows earlier messages, opens Find, or jumps to a message that is not loaded yet. The server marks the entries it left out as sent, so an update does not send them. A full view of the same session, as after a reconnect, keeps the entries the tab loaded. A session of 6,000 entries was one event of 8 to 10 MB: on a phone, the tab stopped for most of a second each time to read it, and only its last rows are drawn.
|
|
185
191
|
|
|
186
192
|
A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
|
|
@@ -189,6 +195,8 @@ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`:
|
|
|
189
195
|
|
|
190
196
|
The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
|
|
191
197
|
|
|
198
|
+
Browser drafts use `web/person-storage.js`: `pocket.person.<person>:…` keys, readable after `/api/me` or an event-stream hello identifies the person. An account signal invalidates answers already on their way, including at startup. Sign-out stops the device cache and attachments before the server request; after it finishes, it clears this storage, changes `pocket.person`, broadcasts the account change, and goes to `/`. Other tabs stop their cache on the early `pocket.signedOut` signal, but reload only on the completed account change. On Back, a cover checks `/api/me` before reconnecting; the same person keeps the document and drafts. Each check has a 10 s timeout; failures retry with backoff up to 30 s, or at once with Retry.
|
|
199
|
+
|
|
192
200
|
A tab whose server says it can (`hello.server.switches`) goes to another session on the connection it has: `POST /api/switch` with the connection id its `hello` carried, the session (`c`, none for the list), what it kept of it (`have`, as above), and a number (`seq`) that grows with each switch, so the server drops one that arrives after a newer one (`PocketApp.switchTo`). The server takes the tab out of the old session's room, answers `switched` with that number, and sends the new session as a new connection gets it (`#enter`): its view, chat, notes, and browser. A connection opened anew sent its person's profile, the session list, and PiP's state again, and its person left the app and came back in every other tab's list of who is here, and the session showed "connecting" until all of it came. Until `switched` comes, the tab drops events about a session (its view, chat, notes, people, browser, and missing): the server sent those of the session it left before it heard of the switch. A view or `missing` of another session than the one shown is dropped too. A switch the server cannot take (the connection closed, or the server started again) opens a new connection, which names the session, as before; a server without `switches` gets that too.
|
|
193
201
|
|
|
194
202
|
The session list goes to a tab only when it differs from the one that tab last got (`Client.sessionsSent`): it is large, and it is worked out again for many changes that leave it as it was.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Embedders
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An **embedder** is an app that shows Pi Pocket's web app inside itself: an Electron or Tauri wrapper on a computer, for example, or a phone app with a web view, with notifications, a badge, or a menu of its own. [Pi Pocket GUI](https://github.com/vitalNohj/pi-pocket-gui) is one. Pi Pocket stays a web app on its server; the embedder loads the server's address, and the person signs in there as in a browser.
|
|
4
4
|
|
|
5
|
-
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **
|
|
5
|
+
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **app bridge** joins the two: the embedder puts `window.pocketHost` in the page, and Pi Pocket uses what it offers. Pi Pocket knows nothing else about the embedder: not its name, not what kind of app it is, not what it runs on. In a browser there is no app bridge, and nothing changes.
|
|
6
6
|
|
|
7
7
|
## Finding Pi Pocket
|
|
8
8
|
|
|
@@ -12,46 +12,51 @@ A browser tab cannot do some things that such an app can, and Web Push does not
|
|
|
12
12
|
{ "name": "pi-pocket", "bridge": 1 }
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
`bridge` is the version of the
|
|
15
|
+
`bridge` is the version of the app bridge that this server's web app speaks. The answer never has Pi Pocket's version. A server older than the app bridge answers 401 there; its web app manifest (`/manifest.webmanifest`) still has `"name": "Pi Pocket"`.
|
|
16
16
|
|
|
17
|
-
## The bridge
|
|
17
|
+
## The app bridge
|
|
18
18
|
|
|
19
|
-
The app
|
|
19
|
+
The app bridge is experimental (since 0.28.0): it can change in a minor release ([API stability](extensions/policies/api-stability.md)). Before 0.28.0-beta.7 these docs were `docs/desktop.md`.
|
|
20
|
+
|
|
21
|
+
The embedder (in Electron, its preload script) puts one object in the top page of the server's origin, and nowhere else: never in a frame (artifacts run in frames), never on another origin.
|
|
20
22
|
|
|
21
23
|
```js
|
|
22
24
|
window.pocketHost = {
|
|
23
|
-
kind: "
|
|
25
|
+
kind: "my-app", // which embedder; for logs only
|
|
24
26
|
apiVersion: 1,
|
|
25
27
|
capabilities: ["menu", "badge", "notify", "visibility", "pinned", "open"],
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
menuTitle(), // the heading of the embedder's group in the menu, such as its name; optional
|
|
30
|
+
menuItems(), // [{ id, label, hint? }]: the items of that group, at the menu's end
|
|
28
31
|
invoke(id), // one of them was chosen; false when it could not be done
|
|
29
32
|
setBadge(count), // sessions that need you, as the home-screen icon counts them
|
|
30
|
-
notify(message), // a notification for the
|
|
31
|
-
visible(), // whether the
|
|
33
|
+
notify(message), // a notification for the embedder to show (below)
|
|
34
|
+
visible(), // whether the embedder's window shows: false while hidden in a tray or minimized
|
|
32
35
|
setPinned(list), // [{ id, title, state, label, url }]: the pinned sessions, in order
|
|
33
|
-
subscribe(listener), // the
|
|
36
|
+
subscribe(listener), // the embedder's events (below)
|
|
34
37
|
};
|
|
35
38
|
```
|
|
36
39
|
|
|
37
|
-
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the
|
|
40
|
+
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the embedder throws. `web/embedder.js` does the rest. Pi Pocket uses only the capabilities the embedder names, and ignores ones it does not know. A newer app bridge keeps version 1's calls.
|
|
38
41
|
|
|
39
42
|
### Capabilities
|
|
40
43
|
|
|
41
|
-
| Capability | What Pi Pocket does
|
|
42
|
-
| ------------ |
|
|
43
|
-
| `menu` | Shows `menuItems()` in a
|
|
44
|
-
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes.
|
|
45
|
-
| `notify` | Opens its event stream with `
|
|
46
|
-
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab.
|
|
47
|
-
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these bridge names. `label` says it in words. |
|
|
48
|
-
| `open` | Opens what the
|
|
44
|
+
| Capability | What Pi Pocket does |
|
|
45
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
46
|
+
| `menu` | Shows `menuItems()` in a group of their own at the end of the menu, below its App part, under `menuTitle()` (up to 40 characters); without a title, the group has no heading. Choosing one calls `invoke(id)`. Pi Pocket GUI offers **GUI Settings…** under its name. |
|
|
47
|
+
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes. |
|
|
48
|
+
| `notify` | Opens its event stream with `embedder=notify`. The server then sends this connection every notification it would push to the person (`embedder-notify`), and the page passes each to `notify(message)`. |
|
|
49
|
+
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab. |
|
|
50
|
+
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these app bridge names. `label` says it in words. |
|
|
51
|
+
| `open` | Opens what the embedder asks for (an `open` event), also without `notify`. |
|
|
52
|
+
|
|
53
|
+
A page from before 0.28.0-beta.7, still open after the server updates, asks with `host=notify` and listens for `desktop-notify`: the server still sends it those, until the page reloads.
|
|
49
54
|
|
|
50
55
|
A page in an Electron window keeps running at full speed while the window hides in the tray, so `document.visibilityState` stays `visible` there. That is why `visible()` exists: without it, the server would think the person is looking, and hold every notification back.
|
|
51
56
|
|
|
52
57
|
### Notifications
|
|
53
58
|
|
|
54
|
-
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their
|
|
59
|
+
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their embedders' connections (`PocketApp.notifyEmbedders`). An embedder that is not running gets nothing: nothing waits for it.
|
|
55
60
|
|
|
56
61
|
```js
|
|
57
62
|
{
|
|
@@ -69,11 +74,11 @@ The server decides as for Web Push (`alerts.ts`): who can see the session, the k
|
|
|
69
74
|
}
|
|
70
75
|
```
|
|
71
76
|
|
|
72
|
-
The
|
|
77
|
+
The embedder chooses how much of an approval to show and whether to offer **Allow**, from `may`, `allow`, and `call`. It always offers **Deny**. The server checks again, when the answer comes, that the person may give it.
|
|
73
78
|
|
|
74
|
-
### The
|
|
79
|
+
### The embedder's events
|
|
75
80
|
|
|
76
|
-
`subscribe(listener)` takes one function. The
|
|
81
|
+
`subscribe(listener)` takes one function. The embedder calls it with:
|
|
77
82
|
|
|
78
83
|
- `{ type: "visibility" }`: its window was shown or hidden. The page reads `visible()` again.
|
|
79
84
|
- `{ type: "open", url }`: open this, such as a notification or a tray item that was clicked. Only addresses of the server's own origin open.
|
|
@@ -81,7 +86,7 @@ The app chooses how much of an approval to show and whether to offer **Allow**,
|
|
|
81
86
|
|
|
82
87
|
## The window's buttons
|
|
83
88
|
|
|
84
|
-
An
|
|
89
|
+
An embedder that hides its title bar, and shows Pi Pocket up to its window's top edge with the window's own buttons over it (close, minimize, zoom), tells the page where they are through the web's standard for it, the Window Controls Overlay (`navigator.windowControlsOverlay`). An installed web app with `"display_override": ["window-controls-overlay"]` does the same. The app bridge is not needed for it.
|
|
85
90
|
|
|
86
91
|
`web/window-controls.js` makes room only under the buttons, and only as much as they take; the rest of the layout keeps its whole height:
|
|
87
92
|
|
|
@@ -92,14 +97,14 @@ An app that hides its title bar, and shows Pi Pocket up to its window's top edge
|
|
|
92
97
|
|
|
93
98
|
The page reads the layout, not the screen: a window, a bar, or a panel that opens (the subagents board, Design, Files, Browser, People) has its room and its cut before the frame that first shows it, and a window that pops in is measured where it lands. Nothing shows under the buttons first and moves after.
|
|
94
99
|
|
|
95
|
-
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an
|
|
100
|
+
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an embedder can tell that it makes its own room. For a page without it (an older Pi Pocket, a sign-in page), Pi Pocket GUI instead sets a top safe-area inset as tall as the buttons, which Pi Pocket's bars have long kept clear of on phones.
|
|
96
101
|
|
|
97
102
|
## Security
|
|
98
103
|
|
|
99
|
-
The bridge is only as safe as the
|
|
104
|
+
The app bridge is only as safe as the embedder that offers it. An embedder must:
|
|
100
105
|
|
|
101
106
|
- put it only in the top frame of the server's origin, and take it away when that frame goes elsewhere;
|
|
102
107
|
- check, in its main process, the frame and origin of every call that comes from the page: the sender frame's own origin (`senderFrame.origin`), not its `url`, because the server's origin also serves sandboxed artifact pages, whose origin is opaque;
|
|
103
108
|
- give the page no Node.js, and keep its sandbox and context isolation on.
|
|
104
109
|
|
|
105
|
-
Pi Pocket gives the bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the
|
|
110
|
+
Pi Pocket gives the app bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the page.
|
package/docs/examples/clock.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A clock tool, and a /clock-zone command that sets the time zone it uses in a session. An example drop-in extension:
|
|
3
3
|
* copy it into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, opt, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -22,10 +22,8 @@ const clock = defineTool({
|
|
|
22
22
|
name: "clock",
|
|
23
23
|
description:
|
|
24
24
|
"The date and time now, in a time zone such as Europe/Berlin (by default, the session's or the server's).",
|
|
25
|
-
parameters:
|
|
26
|
-
zone:
|
|
27
|
-
Type.String({ description: "An IANA time zone, such as America/Chicago" }),
|
|
28
|
-
),
|
|
25
|
+
parameters: obj({
|
|
26
|
+
zone: opt(str({ description: "An IANA time zone, such as America/Chicago" })),
|
|
29
27
|
}),
|
|
30
28
|
// It only reads the clock: running it again after a restart cut it off is harmless.
|
|
31
29
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Web } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -13,7 +13,7 @@ function countWords(text: string): number {
|
|
|
13
13
|
const wordCount = defineTool({
|
|
14
14
|
name: "my_word_count",
|
|
15
15
|
description: "Count the words in a text.",
|
|
16
|
-
parameters:
|
|
16
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
17
17
|
replay: "safe",
|
|
18
18
|
execute: async (args) => ({
|
|
19
19
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A note the transcript can fold: one line in the app, and the whole message for the model.
|
|
3
3
|
* An example drop-in: copy it and `quiet-note.js` into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -14,9 +14,9 @@ const leaveNote = defineTool({
|
|
|
14
14
|
name: "quiet_note",
|
|
15
15
|
description:
|
|
16
16
|
"Leave a note in this session. The app may show one line; you still read the whole note.",
|
|
17
|
-
parameters:
|
|
18
|
-
text:
|
|
19
|
-
summary:
|
|
17
|
+
parameters: obj({
|
|
18
|
+
text: str({ description: "The whole note" }),
|
|
19
|
+
summary: str({ description: "A few words for the one line" }),
|
|
20
20
|
}),
|
|
21
21
|
// The request id is this call's, so a replay finds the note instead of leaving another.
|
|
22
22
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Reads a public web page for Pi: a read_page tool that fetches only public addresses and fences the page's text.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { num, obj, opt, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Host } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -30,11 +30,9 @@ export default function createReadPage(host: Host) {
|
|
|
30
30
|
const readPage = defineTool({
|
|
31
31
|
name: "read_page",
|
|
32
32
|
description: "Read the text of a public web page (http or https).",
|
|
33
|
-
parameters:
|
|
34
|
-
url:
|
|
35
|
-
maxChars:
|
|
36
|
-
Type.Number({ description: "The text to give at most (default 20000)" }),
|
|
37
|
-
),
|
|
33
|
+
parameters: obj({
|
|
34
|
+
url: str({ description: "The page's address" }),
|
|
35
|
+
maxChars: opt(num({ description: "The text to give at most (default 20000)" })),
|
|
38
36
|
}),
|
|
39
37
|
replay: "safe",
|
|
40
38
|
execute: async (args) => {
|
|
@@ -18,7 +18,7 @@ In the drop-in folder, make the file `my-words.ts` with this text:
|
|
|
18
18
|
/**
|
|
19
19
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
20
20
|
*/
|
|
21
|
-
import {
|
|
21
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
22
22
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
23
23
|
import type { Web } from "./_pocket.d.ts";
|
|
24
24
|
|
|
@@ -30,7 +30,7 @@ function countWords(text: string): number {
|
|
|
30
30
|
const wordCount = defineTool({
|
|
31
31
|
name: "my_word_count",
|
|
32
32
|
description: "Count the words in a text.",
|
|
33
|
-
parameters:
|
|
33
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
34
34
|
replay: "safe",
|
|
35
35
|
execute: async (args) => ({
|
|
36
36
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
package/docs/extensions/hooks.md
CHANGED
|
@@ -36,6 +36,10 @@ There are two kinds of hooks:
|
|
|
36
36
|
|
|
37
37
|
The calls of codemode scripts also go through `beforeTool`.
|
|
38
38
|
|
|
39
|
+
## Read a result
|
|
40
|
+
|
|
41
|
+
`afterTool(call, result, api, context)` gets each result before it is stored, and can return a changed one. Since Pi 1.5 (Pi Pocket 0.28.0), it also gets the error results that Pi Durable writes itself: for a tool that is not there, invalid arguments, a block, an interruption, and an abort. Their `result.diagnostics` say which, with a `code` such as `invalid_arguments` or `blocked`. A hook that reads `call.arguments` or `structuredOutput` checks `result.diagnostics` first. In the calls of codemode scripts, `api.entry` and `api.entries` reject.
|
|
42
|
+
|
|
39
43
|
## Send Pi on
|
|
40
44
|
|
|
41
45
|
`onYield(answer, api, context)` runs after Pi's last answer. To send Pi on with another message, return `{ continue: "the message" }`. Done when does this ([goals.ts](../../src/server/extensions/goals.ts)).
|
|
@@ -14,6 +14,8 @@ The version goes up only when a change breaks something that modules use. Additi
|
|
|
14
14
|
|
|
15
15
|
Since 0.21.0, document definitions should name `checkpointWhen` in every `defineDoc` or `defineDocFamily` call. When it is missing, Pi Pocket supplies `checkpointWhen: () => false` for older drop-ins, and logs the module and the document kind. Explicit policies stay as they are. Since 0.21.0 (Pi Durable 1.4), a task must not use `TaskRuntime.sleep()`: it must wait with durable `sleepUntil()` checkpoints.
|
|
16
16
|
|
|
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
|
+
|
|
17
19
|
## `pocketApi`
|
|
18
20
|
|
|
19
21
|
A module can export `pocketApi`: the server module, the browser module, or both.
|
|
@@ -191,7 +191,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
191
191
|
| `sheet-head`, `sheet-body` | Its title bar, and what it holds |
|
|
192
192
|
| `menu` | The menu, on wide screens (it is the sheet `menu` on phones) |
|
|
193
193
|
| `session-menu` | The right-click menu on a session row (since 0.27.0) |
|
|
194
|
-
| `quote-reply-button` | The
|
|
194
|
+
| `quote-reply-button` | The pill that shows over selected text, with Reply and (with PiP on) Ask PiP (since 0.27.0) |
|
|
195
195
|
| `launcher` | The launcher (Ctrl/⌘+K) |
|
|
196
196
|
| `launcher-input`, `launcher-filters` | Its search field, and the search types under it |
|
|
197
197
|
| `launcher-group`, `launcher-row` | A group's heading, and each result |
|
package/docs/extensions/tools.md
CHANGED
|
@@ -10,7 +10,7 @@ Use `defineTool` from `@earendil-works/pi-durable`, and give the tool to your ex
|
|
|
10
10
|
const wordCount = defineTool({
|
|
11
11
|
name: "my_word_count",
|
|
12
12
|
description: "Count the words in a text.",
|
|
13
|
-
parameters:
|
|
13
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
14
14
|
replay: "safe",
|
|
15
15
|
execute: async (args) => ({
|
|
16
16
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -28,7 +28,7 @@ export default function createMyWords() {
|
|
|
28
28
|
- `name` must be different from the name of each other tool ([Names](reference/names.md)). Use a prefix of your own.
|
|
29
29
|
- `description` and `parameters` go to the model with each request. Keep them short and exact.
|
|
30
30
|
- `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at 11,000 characters (about 4,000 tokens) in a plain session.
|
|
31
|
-
- `parameters` is a
|
|
31
|
+
- `parameters` is a JSON Schema object. Build it with the builders of `@earendil-works/pi-schema`: `obj`, `str`, `num`, `int`, `bool`, `arr`, `union`, and `opt` for a property that can be left out. `obj` makes a closed object (`additionalProperties: false`); `obj(properties, { open: true })` lets other properties through. Pi Durable checks the arguments against the schema before `execute` runs. Since Pi 1.5 (Pi Pocket 0.28.0), pi-schema does the check, and the model gets its messages, such as `- path: missing`. A drop-in written before can keep TypeBox's `Type` from `@earendil-works/pi-ai` ([API versions](reference/api-versions.md)).
|
|
32
32
|
- `execute(args, api, context)` does the work.
|
|
33
33
|
|
|
34
34
|
## Return a result
|
package/docs/extensions.md
CHANGED
|
@@ -69,13 +69,13 @@ A module is one `.ts` file with a default export: a function. Pi Pocket calls it
|
|
|
69
69
|
* A clock tool: the date and time now, in any time zone. The first sentence of this comment is the module's
|
|
70
70
|
* description in the Extensions sheet.
|
|
71
71
|
*/
|
|
72
|
-
import { Type } from "@earendil-works/pi-ai";
|
|
73
72
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
73
|
+
import { obj, opt, str } from "@earendil-works/pi-schema";
|
|
74
74
|
|
|
75
75
|
const clock = defineTool({
|
|
76
76
|
name: "clock",
|
|
77
77
|
description: "The date and time now, in a time zone such as Europe/Berlin.",
|
|
78
|
-
parameters:
|
|
78
|
+
parameters: obj({ zone: opt(str()) }),
|
|
79
79
|
replay: "safe",
|
|
80
80
|
execute: async (args) => ({
|
|
81
81
|
output: [
|
package/docs/features.md
CHANGED
|
@@ -15,7 +15,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
15
15
|
- **Keyboard.** Alt+1…9 jumps to a session (hold Alt to see the numbers), Alt+↑/↓ goes to the previous or next one, Alt+N starts a new one (where Ctrl/⌘+1…9 starts it in a favorite folder), Alt+B opens or closes the browser, Alt+E the Files tile, Alt+T turns Show thinking on or off, Alt+V starts or stops dictation, and `?` lists every shortcut. On a computer, a session opens with the caret in its message box, ready to type; on a touch screen it waits for a tap, so the keyboard does not cover the conversation, and on a Mac a session opened with Alt+1…9 or Alt+↑/↓ leaves the box alone, so the next Alt shortcut still works (Option types characters in a box).
|
|
16
16
|
- **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; Ctrl/⌘+Enter sends a message the other way while Pi works (queued when Steer is chosen, steering when Queue is) and leaves the choice as it was, and on Interrupt or with nothing running it sends as Enter does (since 0.28.0); queued messages can be withdrawn, and your own, tapped open, can go back into the message box to change (**Edit**: its words above what you were typing, on a line of their own, with its files), move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off), with these buttons in a quiet row at its right (since 0.28.0): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card. A session you go back to shows at once where you were in it, as this browser tab kept it, and what came while you were away rises in: at the bottom the conversation glides up to it, and scrolled up the row you read stays where it is. With Appearance's **Wait for updates** (off by default), a session that changed while you were away shows only once its updates have come (or after 2.5 seconds). Scrolled up, a round button above the end of the message box goes back down to the newest message.
|
|
17
17
|
- **Getting around on a phone, with one hand.** Back (the swipe, Android's back button, the browser's) goes back to where you were: it closes what opened last (a sheet, the menu's next sheet back to the menu, a file back to the Files tree, back to Changes when the file was opened from there, the Files tile or the Browser panel, the drawer) before it leaves the session, and leaving goes to the session before or to the list, scrolled and searched as you left it. A session opened straight away (a link, a notification) has the list under it, so back does not leave the app. What you use most is a thumb's reach from the bottom edge: the button beside the message box (or a swipe up from it) opens the places, a short sheet of big tiles (Files, Changes, Browser, Artifacts, Chat, Find, Branch, Peeks) with the session menu below them. On the conversation, swipe left for Files and right to go back; in Files, swipe right to go back. Each swipe shows a mark that lights when letting go will act. The top bar leads back to the list (counting other sessions that wait for an approval) and keeps only the buttons with something to say. Every control is a thumb's size on a touch screen (small ones, such as a code block's Copy or a reply's Pin, keep their look and take a wider tap); a tap anywhere on the message box, off its one line of text, still goes to the text; a quick second tap does not land on whatever just slid in under it; tables in replies scroll sideways instead of crushing their columns; a diff's header keeps the file's name on a line of its own on a phone; and the command a peek tile asks about opens its session when tapped. The Files tile and the browser slide in as screens of their own and slide away on back, a file slides in over the tree, and the browser's tools sit on their own row under the address. Drag a sheet down, or the drawer left, to close it. In an iPhone home screen app, which has no back gesture of its own, swipe in from the left edge to go back.
|
|
18
|
-
- **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words. **Reply to a passage
|
|
18
|
+
- **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words. With PiP on, PiP's orb (**Ask PiP**) sits beside **Reply** in the same pill: it opens PiP with the passage in a quote strip over its box, ready to type; your message goes with the passage quoted first, and shows with it as a quote block. PiP also gets, unseen by people, which session the passage came from (its number, title, and folder: `about` on the submit request, a `<pocket-context>` part after the message that no view or resend shows), so it can read that session for more. In Appearance, **Reply to a passage** and **Ask PiP about a passage** (both on by default) each turn their own button off in that browser; with both off, nothing shows.
|
|
19
19
|
- **Forks.** Tap Pi's reply → More → **Fork from here**: a new session with everything up to that reply, which then goes its own way. Tap one of your messages to **edit it and send it again**, or send any message again, to the same model or another one (a retry). Each makes a new session that forks just before the message; the original stays as it is. A fork gets its own chat (with the pins of what it inherited), a link back to where it came from, and optionally a git worktree of its own.
|
|
20
20
|
- **A new context.** Menu → **New context** (or `/reset [note]`): Pi starts fresh and no longer sees the messages so far, while everyone still does. An optional handoff note carries over what matters.
|
|
21
21
|
- **Instructions for Pi.** Menu → **Instructions for Pi** (or `/instructions …`): ground rules Pi gets with every message in this session, such as "use pnpm, not npm". Everyone in the session can see them.
|
|
@@ -30,7 +30,8 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
30
30
|
- **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).
|
|
31
31
|
- **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).
|
|
32
32
|
- **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.
|
|
33
|
-
- **
|
|
33
|
+
- **Drafts on a shared browser.** Message drafts, folded pastes, and uploaded files stay with the person signed in, across reloads and Back. Signing out clears them and resets other open tabs; theme and layout stay as they were. On Back, a cover checks who is signed in; Retry checks again if the server cannot be reached. Old unscoped drafts are discarded. PiP keeps text across reloads, but its files only while the page stays open.
|
|
34
|
+
- **What you sent before.** ↑ in the message box goes back through what you sent from this browser in the current session (↓ comes forward, then back to your draft), and Ctrl+R searches it. The browser keeps up to 200 entries per person across sessions, with duplicates removed only within your session. Signing out clears this history; old unscoped history is discarded.
|
|
34
35
|
- **Dictation.** The mic beside Send, in the message box and in PiP's, dictates with the browser's own speech recognition, in the language the browser is set to. Words show in the box as they are heard and stay once the browser settles on them: at the caret while the box has the focus, after its text when it does not, with a space where they meet; words typed meanwhile stay too, and a phrase still being heard when you type or move the caret elsewhere finishes where it is, the next one going to the caret. It never sends by itself: tap the mic again (or Alt+V, which dictates into PiP's box while PiP is open, else into the session's) to stop, read it over, and send. Sending, leaving the session, closing PiP, or switching away from the tab stops it as well. What was heard is kept as a draft, like typing. While it listens the mic takes the accent, with a ring that breathes (still, with reduced motion), and the box says "Listening…". On a phone while Pi works, the mic takes Send's place until there is something to send. It needs a browser with the Web Speech API: Chrome, which sends the audio to Google's servers to recognise it, and Safari, on iOS too; where there is none (Firefox), the mic does not show. Browsers give a page the microphone only over https or on localhost, as Pi Pocket is served through the Cloudflare Tunnel, Tailscale Serve, or on this device. A blocked microphone, silence, a missing microphone, or no network says so in a notice.
|
|
35
36
|
- **Long pastes.** Pasting more than 20 lines puts a placeholder such as `[Pasted text #1 · 240 lines]` in the box; the message goes out with the text in its place.
|
|
36
37
|
- **Files at a tap.** Inline code paths in Pi's replies (`src/app.ts`, `app.ts:42`), Markdown links to local paths (such as `[config](/etc/app/web.env)`), file mentions in messages, read/write/edit cards, and Changes open a viewer: text with line numbers and syntax colors (Markdown rendered too), images, and folders to browse, with **@ Mention** to put the file in the message box. While the Files tile is open, they open there instead of in a sheet. Opening a file that is already shown reads it again, so after an edit the viewer shows the new text; the old text stays on screen until the new text arrives. Someone invited to one session sees its folder only, and only the owner opens Pi's own folder and Pi Pocket's data. For the owner, Ctrl+click (⌘+click on a Mac) on such a path, or on a row in the Files tile, shows it in the file manager of the machine Pi Pocket runs on (Files, Dolphin, Finder, Explorer), selected in its folder; so does the folder button in the viewer, with a mouse. It opens on that machine, not on the device you click from.
|
|
@@ -62,7 +63,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
62
63
|
- Under Pi's answers: emoji reactions, **Discuss**, and **Pin**. Queued messages show who queued them. Approved or denied tool calls show who decided.
|
|
63
64
|
- **Take turns.** Menu → **Take turns**: one person drives and only they send to Pi or change its settings. Others tap **Ask to drive**, the driver hands over, and anyone can take the wheel when the driver has left (the owner always can). Anyone who can steer can still stop a run.
|
|
64
65
|
- **Roles and invites.** An invite can let someone **steer** or make them **view only** (they read, react, and chat, but cannot send to Pi, approve, or upload). It can cover **every session** or **only this session**, and lasts 15 minutes, an hour, a day, or a week (**Expires after**); either way it works once, and a restart keeps it. Changing what the sheet's invite grants, or how long it lasts, ends the one it showed; **New invite** makes another and leaves the one before working. Only the owner can make an owner invite (**Sign in as me (owner)**): it makes no one new, but signs the device in with the owner's token, so it has full control, works once, and always expires in 15 minutes; rotating the owner token (`--rotate-token`) signs out every device signed in that way, and ends owner invites not yet used. Menu → **People** lists everyone, who is online, and when the others were last here. The owner can change what each person may do or remove them. The session list shows who is in each session, and a dot marks new chat messages.
|
|
65
|
-
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel or Tailscale Serve, or another tunnel such as ngrok in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`. In a
|
|
66
|
+
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel or Tailscale Serve, or another tunnel such as ngrok in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`. In a host around Pi Pocket (an app such as Pi Pocket GUI), they come as the app's own notifications, with no https address needed, while the app runs ([docs/embedders.md](embedders.md)).
|
|
66
67
|
- **Built-in browser.** Menu → **Browser** (or Alt+B, `/browser localhost:5173`, or the globe in the top bar while a page is open; on a phone, a dot on the places button by the message box says so) opens a real Chromium page that runs on the server: beside the conversation on wide screens, full screen on phones. Type an address (`localhost:5173`, `example.com`), or (the owner) tap a row under **Running on this machine** on the start screen; a green dot in the rounded address field marks an open page. Tap, drag to scroll, and type into the page (the keyboard button sends text from a phone). The size button switches between fitting the panel (the page follows the panel when it changes size), desktop, phone, and tablet sizes, and the console button shows the page's logs and errors, with a warning-colored error count. Pi's `browser` tool uses the same page: it opens addresses (dev servers, HTML files on the machine, any site), reads a snapshot of the page's text and controls, clicks, types, takes screenshots it can see, reads the console, and runs JavaScript in the page, while everyone in the session watches. Each session has one page, in a browser context of its own; links that open a new tab open there instead, and dialogs are accepted. Anyone in the session can watch; using the page takes steering rights (and the wheel, while take turns is on), the addresses people open show in the chat, and only the owner opens files from the address bar. The browser reaches what the server reaches, `localhost` and its network included, and Lancet Guard does not check it (see SECURITY.md). A restart closes the pages, and each opens again at its last address and size. Where the panel covers the conversation, Esc closes it, unless the page has the keys (then Alt+B does). In plan mode Pi may look at pages but not click, type, or run scripts in them. It needs Chromium, Chrome, Brave, or Edge on the server (or `PI_POCKET_BROWSER`); the owner can turn it off in Extensions, which closes the panel too.
|
|
67
68
|
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. `inline: true` (since 0.28.0, one tool; before it a second tool, `artifact_inline`, sent almost the same schema again on every request) is the same store for HTML only (`content` or `edits`, no path, no `type` but `html`): the call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but an `inline: true` call refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `inline` only in sessions whose `artifact` tool has it (PiP's has not), and says that only a direct call shows a card. Sessions from before 0.28.0 keep their `artifact_inline` calls and results as stored, and still show them as cards, also in forks; the model is shown those calls as `artifact` with `inline: true` in its requests, so it does not repeat a tool it is no longer offered. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's.
|
|
68
69
|
- **All artifacts.** The rail's artifact button opens every artifact in every session you can see, grouped by session (archived sessions are left out), newest first. Each row shows its type, size, age, and the number of its current (latest) version, as `v3 / 3` of the versions it has (`v1` when it has one). A tap opens that version in its session. The launcher's **All artifacts** opens it too, which is the way on a phone. The list is `GET /api/artifacts`.
|
|
@@ -105,8 +106,8 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
105
106
|
- everyday words that are a model's name without its first word: "deep research" names "X9 Deep Research", and "the 2.5 flash drive" names "Nova 2.5 Flash".
|
|
106
107
|
- a longer name Pi has no model for: it names the model it starts with. "zeta-5-ultra" names zeta-5, while "zeta-5-nano", a model Pi knows, does not.
|
|
107
108
|
- **Returning from a subagent.** A subagent's conversation has **Back to main session** above the message box, for viewers too, so the way back stays in sight however long the conversation is. The top bar says which session it is a subagent of, and carries a small tag with the model it uses, which a tap opens in the model sheet. The composer hides its model chip on a phone while the subagent works, so the tag keeps the model in sight; when room is short, the parent's title is cut first.
|
|
108
|
-
- **Subagents bar.** Above the message box while a subagent works or has a report on its way: a dot per subagent, how many work and how many are done, and what the newest one does now. Tap it (or the count in the top bar while one works) for a row each: what it was asked, what it does this moment (the call it runs, or what it writes), for how long, whether its report is on its way, **Stop**, and a tap to open it; a call waiting for approval says so, and a failed one says why, and "dismissed" once someone dealt with it (see Subagents board). Done, stopped, and failed ones are counted apart, failed ones first. Once none works it stays until you put it away (×), and comes back, counting only the new ones, when one starts again. Viewers see it too, without Stop.
|
|
109
|
-
- **Subagents board.** The rail's ⑂ shows every subagent in every session in the conversation's place: a soft state-colored square each, in a rounded row per session, those that need you first, and under each row a sub-tile for every subagent at work there, with its state and
|
|
109
|
+
- **Subagents bar.** Above the message box while a subagent works or has a report on its way: a dot per subagent, how many work and how many are done, and what the newest one does now. Tap it (or the count in the top bar while one works) for a row each: what it was asked, what it does this moment (the call it runs, or what it writes), for how long, the model and thinking level it runs on (with ↗ when that is not the session's model), whether its report is on its way, **Stop**, and a tap to open it; a call waiting for approval says so, and a failed one says why, and "dismissed" once someone dealt with it (see Subagents board). Done, stopped, and failed ones are counted apart, failed ones first. Once none works it stays until you put it away (×), and comes back, counting only the new ones, when one starts again. Viewers see it too, without Stop.
|
|
110
|
+
- **Subagents board.** The rail's ⑂ shows every subagent in every session in the conversation's place: a soft state-colored square each, in a rounded row per session, those that need you first, and under each row a sub-tile for every subagent at work there, with its state and the model it runs on, so a glance says what each is doing without opening one (a tap picks it for the detail card, staying on the board; a double click, or double tap, opens it). A row shows six sub-tiles (three on a phone), and the selected one wherever it is; **Show N more** shows the rest. Working squares pulse; the selected square has a ring, and filtered-out squares fade. A proportional state bar and filter pills with counts say how many wait for an approval, failed, work, were stopped, or are done, and let you filter by one; a search finds a subagent by its name, what it was asked, what it does now, or why it failed. **Needs you** lists those waiting for an approval and those that failed with nobody dealing with it yet. The selected subagent's detail card shows its session, how long it has worked (or when it ended), what it was asked and does now, and its error, with **Open** (**Review the approval** while it waits), **Stop**, and, for a failure, **Dismiss** (off while it is asked; when the subagent failed again since, a notice says so and the newer failure stays). A failure is dealt with once someone who can steer dismisses it, or opens the subagent from the board, its row in the subagents bar, its report or the tool call that started it, or the session menu: it stays on the board as failed ("Failed · dismissed", without the "!"), and leaves Needs you, the rail's red mark, and the session's red ⑂, for everyone, after a reload or a restart too. A message someone sends it, like later work from Pi, settles it by what it comes to, after a restart too: answered, the subagent is done; failing again, it needs someone again. The session's activity says who dealt with a failure, whichever way. Hover a square to see what it does in the line under them; the arrows move the focus between squares and Enter opens the one focused; Esc, back, or × closes it, and on a phone a swipe right does too. Archived sessions show only while a subagent works there. A session keeps its 24 newest finished squares (done, stopped, or failed and dealt with); older ones are counted, as **+N** after its squares and in the bar's numbers. On a phone it is one column, Needs you first, with bigger squares and a bar at the bottom for the one selected.
|
|
110
111
|
- **The queue and the bars above the message box.** Messages waiting for Pi show above the message box, with how many wait whenever not all of them show. With the bars there (the subagents bar, plan mode, a goal, a PR watch, a trust question, who drives), they take less than half of the room they share with the conversation when the bars fit in it, and the conversation keeps the rest, staying where you were reading. The bars always show whole; the queue and the subagents' list take what the bars leave, and scroll. Unfolding the subagents bar gives the list the room, one whole row at least: the queue shows fewer rows, or folds to how many wait. With several bars on a short screen, the plan, goal, watch, and trust bars keep one line each, their words cut short and their buttons whole. When even that does not fit (a phone on its side with every bar up), the stack scrolls, and the conversation keeps a quarter of the room, or a few lines, whichever is less.
|
|
111
112
|
- **Live editing.** No build step. Edit a file in `web/` and every open browser reloads. Edit a file in `src/server/extensions/` and it is reinstalled into the running server (a running tool call finishes on the old code). For core server changes, use **Restart server** in the menu: running work resumes after the restart.
|
|
112
113
|
- **Lancet Guard.** Off by default: the owner turns it on in Menu → **Extensions**. If `specpi-lancet-guard` is installed in Pi and turned on there too, its rules and classifier check every bash, write, and edit call, and each command Pi starts in the background. A "risky" or "unsure" verdict shows Allow/Deny buttons to everyone in the session; the answer survives restarts. The classifier needs the LANCET Nano model, a one-time download of about 109 MB. While it is missing, the guard row in Extensions says so and the owner gets a **Download** button there: it fetches the pinned release from GitHub, checks it against fixed checksums, and installs it where Pi's own `/lancet-guard setup` puts it, so Pi uses it too. Progress shows in every tab, and nothing downloads it without that button. A guard that is on without its model blocks the bash calls its local rules leave open, and the status line shows "guard failed".
|
|
@@ -125,7 +126,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
125
126
|
- **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
|
|
126
127
|
- **OpenAI-compatible endpoints.** The owner adds an endpoint from the **OpenAI Compatible** row of the Providers list (**Add**; searching "ollama", "local", or "custom" finds it): a name, a base URL (`http://localhost:1234/v1`), and an API key, or **No key** for a local server. **Find models** asks the endpoint's `GET /models` and lists what it has, each with a checkbox; a model ID can also be typed by hand, and either way it is added. **Save** writes the endpoint into Pi's `~/.pi/agent/models.json` (made, with `~/.pi/agent/`, when missing) and keeps the key in Pi's sign-ins (`auth.json`), so its models show in the model menu at once, with no restart. Each endpoint is a row of the list like any provider, with **Edit** (an empty key keeps the saved one; models can be found again with the saved key, at the same address only) and **Remove** (which removes its key too). Pi Pocket rewrites `models.json` only when it is plain JSON that Pi accepts, and keeps the fields that it does not set; a file with comments or trailing commas is left alone, with a message.
|
|
127
128
|
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (the refresh button beside the Subagent models heading), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
|
|
128
|
-
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them. That includes HEIC and HEIF photos (from an iPhone, say), which the server converts to JPEG for the model in a worker, one photo at a time, with limits of 30 seconds and 64 million pixels (a photo that big needs about 1 GB of memory while it converts), so a broken or huge photo gets a notice and does not hold up the server; the original stays in the session's uploads. When the image the model gets differs from the file, its line in the message says so: the format when it changes (`[Image: shown to you as JPEG.]`, always for a HEIC photo), and, in the words of Pi's `read` tool, the original size, the shown size, and the multiplier when it is made smaller. An image that does not change gets no note. An image starts to be made ready for the model as soon as it uploads, so a send seldom waits for it. In a session's message box (not PiP's), attached files stay across a reload, as the draft does, and leave with your sign-out; while a message is on its way, the box dims and holds what it sends, and if the send fails, it is all there to send again.
|
|
129
|
+
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them. That includes HEIC and HEIF photos (from an iPhone, say), which the server converts to JPEG for the model in a worker, one photo at a time, with limits of 30 seconds and 64 million pixels (a photo that big needs about 1 GB of memory while it converts), so a broken or huge photo gets a notice and does not hold up the server; the original stays in the session's uploads. When the image the model gets differs from the file, its line in the message says so: the format when it changes (`[Image: shown to you as JPEG.]`, always for a HEIC photo), and, in the words of Pi's `read` tool, the original size, the shown size, and the multiplier when it is made smaller. An image that does not change gets no note. A sent HEIC photo shows in the chat and in PiP as the JPEG the model got; when the model did not get one (a model without images, or a failed conversion), or when Pi Pocket cannot be sure which image is the photo's (the message names an image with `@`, or another attached image failed), it shows as a file. An image starts to be made ready for the model as soon as it uploads, so a send seldom waits for it. In a session's message box (not PiP's), attached files stay across a reload, as the draft does, and leave with your sign-out; while a message is on its way, the box dims and holds what it sends, and if the send fails, it is all there to send again.
|
|
129
130
|
- **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.
|
|
130
131
|
- **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.
|
|
131
132
|
- **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. 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.
|
package/docs/index.md
CHANGED
|
@@ -39,7 +39,7 @@ A drop-in extension stays when Pi Pocket updates, and the owner can turn it off
|
|
|
39
39
|
- [extensions/themes.md](extensions/themes.md): how to make a theme, which changes how the app looks and is laid out. Every token and part is in [extensions/reference/theme-surface.md](extensions/reference/theme-surface.md).
|
|
40
40
|
- [extensions/policies/](extensions/policies/index.md): the rules for extensions and changes to Pi Pocket: what belongs in core, the public API and how it changes, the security model for authors, and the gallery's review.
|
|
41
41
|
- [self-editing.md](self-editing.md): how to change Pi Pocket's code while it runs, check the change, and undo a change that breaks it.
|
|
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
45
|
- [map.md](map.md): where each part of the code is, and how to add the usual things.
|