pi-pocket 0.27.0 → 0.28.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 +11 -8
- package/docs/architecture.md +9 -1
- package/docs/customizing.md +16 -2
- package/docs/docker.md +2 -0
- package/docs/examples/quiet-note.js +21 -0
- package/docs/examples/quiet-note.ts +73 -0
- package/docs/extensions/app.md +1 -0
- package/docs/extensions/policies/api-stability.md +3 -0
- package/docs/extensions/reference/limits.md +11 -0
- package/docs/extensions/reference/pocket.md +22 -1
- package/docs/extensions/reference/theme-surface.md +12 -0
- package/docs/extensions/reference/web.md +36 -2
- package/docs/extensions.md +2 -0
- package/docs/features.md +20 -16
- package/docs/map.md +24 -12
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +3163 -0
- package/package.json +3 -2
- package/src/launcher/access.ts +75 -4
- package/src/launcher/main.ts +303 -60
- package/src/launcher/options.ts +8 -5
- package/src/launcher/serve.ts +677 -0
- package/src/server/app.ts +223 -14
- package/src/server/avatars.ts +54 -0
- package/src/server/background.ts +214 -42
- package/src/server/build.ts +53 -0
- package/src/server/commands.ts +28 -33
- package/src/server/config.ts +9 -1
- package/src/server/docs.ts +8 -1
- package/src/server/entry-presentation.ts +275 -0
- package/src/server/export.ts +26 -3
- package/src/server/extension-web.ts +113 -8
- package/src/server/extensions/pip.ts +57 -2
- package/src/server/host.ts +21 -3
- package/src/server/http/api.ts +106 -6
- package/src/server/http/assets.ts +9 -1
- package/src/server/http/conversation-routes.ts +61 -0
- package/src/server/http/events.ts +19 -0
- package/src/server/http/icon-route.ts +196 -0
- package/src/server/http.ts +41 -2
- package/src/server/icon-mask.ts +33 -0
- package/src/server/icon-render.ts +149 -0
- package/src/server/icon-store.ts +57 -0
- package/src/server/model-images.ts +124 -0
- package/src/server/pip.ts +30 -6
- package/src/server/projection.ts +127 -32
- package/src/server/room.ts +171 -8
- package/src/server/running.ts +307 -2
- package/src/server/schedules.ts +5 -0
- package/src/server/skills.ts +99 -8
- package/src/server/spend.ts +5 -0
- package/src/server/transcripts.ts +28 -3
- package/src/server/when.ts +25 -11
- package/types/pocket.d.ts +53 -2
- package/web/app-icon.js +149 -0
- package/web/app.js +12 -8
- package/web/avatar.js +46 -2
- package/web/composer.js +107 -15
- package/web/entry-presentation.js +264 -0
- package/web/extension-ui.js +18 -0
- package/web/fingerprint.d.ts +2 -0
- package/web/fingerprint.js +21 -0
- package/web/launcher.js +15 -3
- package/web/model-favorites.js +27 -0
- package/web/peeks.js +11 -3
- package/web/pip.js +7 -1
- package/web/running-board.js +1197 -0
- package/web/session-cache.js +144 -0
- package/web/session-tabs.js +58 -0
- package/web/sessions.js +51 -12
- package/web/sheets/all-artifacts.js +104 -0
- package/web/sheets/appearance.js +45 -0
- package/web/sheets/background.js +228 -0
- package/web/sheets/find.js +61 -7
- package/web/sheets/folder.js +43 -4
- package/web/sheets/menu.js +3 -1
- package/web/sheets/message.js +80 -15
- package/web/sheets/model.js +39 -3
- package/web/sheets/people.js +35 -1
- package/web/sheets/providers.js +80 -26
- package/web/sheets/schedules.js +4 -1
- package/web/sheets/shortcuts.js +1 -0
- package/web/sheets/text.js +2 -0
- package/web/sheets.js +11 -4
- package/web/store.js +837 -27
- package/web/style.css +1928 -166
- package/web/subagents-board.js +3 -2
- package/web/tab-order.js +34 -0
- package/web/theme-surface.js +7 -0
- package/web/theme.js +15 -0
- package/web/transcript.js +588 -57
- package/web/user-search.js +6 -0
- package/web/sheets/running.js +0 -130
package/README.md
CHANGED
|
@@ -74,14 +74,17 @@ While it runs: **q** quit · **r** restart server · **a** change access · **o*
|
|
|
74
74
|
|
|
75
75
|
Choose a mode in the launcher, or pass `--access`:
|
|
76
76
|
|
|
77
|
-
| Mode
|
|
78
|
-
|
|
|
79
|
-
| `local`
|
|
80
|
-
| `lan`
|
|
81
|
-
| `cloudflare`
|
|
82
|
-
| `tailscale`
|
|
83
|
-
|
|
84
|
-
|
|
77
|
+
| Mode | Who can connect | Notes |
|
|
78
|
+
| ----------------- | -------------------- | ---------------------------------------------------------- |
|
|
79
|
+
| `local` | This machine | `127.0.0.1`; bring your own tunnel to port 8787 |
|
|
80
|
+
| `lan` | Your local network | Plain http |
|
|
81
|
+
| `cloudflare` | Anyone with the link | Free https quick tunnel, no account; needs `cloudflared` |
|
|
82
|
+
| `tailscale` | Your tailnet | Plain http on the tailnet address |
|
|
83
|
+
| `tailscale-serve` | Your tailnet | https at the tailnet name; needs `tailscale` 1.52 or newer |
|
|
84
|
+
|
|
85
|
+
`tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet. 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
|
+
|
|
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)).
|
|
85
88
|
|
|
86
89
|
> [!WARNING]
|
|
87
90
|
> 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.
|
package/docs/architecture.md
CHANGED
|
@@ -167,12 +167,18 @@ Each room update sends a tab its new entries, the live run, and some small field
|
|
|
167
167
|
|
|
168
168
|
The message Pi is writing goes as what changed since the tab's last update (`liveMessageDelta` in `projection.ts`, put together by `web/live.js`): the blocks the tab has stay, and the block that grows sends only its new characters. A whole message each time made a long answer cost its length squared. The server keeps the blocks each tab has (`Client.liveBlocks`) and forgets them with each full view, which sends the whole message. Events reach a tab in order on one connection (long polling sends again what a lost answer carried), and a new connection starts with a full view, so a change always fits. One that does not, which should not happen, makes the tab connect again.
|
|
169
169
|
|
|
170
|
-
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. 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.
|
|
170
|
+
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.
|
|
171
171
|
|
|
172
172
|
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.
|
|
173
173
|
|
|
174
174
|
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.
|
|
175
175
|
|
|
176
|
+
A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/fingerprint.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
176
182
|
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.
|
|
177
183
|
|
|
178
184
|
## Who Pi works for
|
|
@@ -278,6 +284,8 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
|
|
|
278
284
|
|
|
279
285
|
**Extensions' browser modules (`extension-ui.js`).** `hello` lists the browser modules a person's tabs load (`server.ui`: each module's name, title, and address, with its version in it). The tab imports each, and imports it again when its address changes: the server sends `hello` again when a browser module comes, goes, changes who it is for, or one of the files it serves changes (`ExtensionWebs` watches its folders), and when its module's new version installs other tools. A reload that leaves all that as it was leaves the address as it was, so tabs keep the browser module they loaded (they may hear `hello` again for other reasons). Event streams and poll queues cut off a tab more than 8 MB behind that took nothing for 30 s, or any tab 128 MB behind (`http/events.ts`); it connects again and gets a full view. A large first view is no reason: the tab has had no time to take it. A polling tab with an answer on its way is taking it until it polls again (one that never does ends 60 s after its last poll or answer), and a stream's ping checks too, so a stalled tab is cut off with no new events for it. A browser module is meant to add only through `pocket` (it runs in the page, so nothing stops it from more), and one that throws is caught there: its notice, its row in the Extensions sheet, its page's error box. One that failed stays listed (`dead`) but adds nothing more, until its module installs other tools: then the tab loads it again, as it may have failed on a tool the server did not have yet. Its events come as `ext` (`{ module, event, data }`). How a module's tools' calls show (`pocket.toolCall`) reaches `calls.js` and `turns.js` through setters, as they import nothing. Each `ui` entry lists the tools its module installs (from the loader), and a module describes only those; what a describer gives is used only when it is text. When a module goes, `sheets.js` takes its sheets out of the ones back would bring back (`onExtensionsGone`). A tab in safe mode (`?noext=1`, kept as `pocket.noext` in session storage) loads none of them.
|
|
280
286
|
|
|
287
|
+
**Model favorites (`model-favorites.js`).** Providers and the session/default-model picker share per-person browser-local stars (`pocket.modelFavorites.<user-id>`). Stars are a browsing preference, not a default model or a subagent permission. Filters preserve the picker's enabled-model scope and current-model priority.
|
|
288
|
+
|
|
281
289
|
**Contracts with the server.**
|
|
282
290
|
|
|
283
291
|
- Event names and shapes (`hello`, `view`, `chat`, `peek`, `subagents`, `ext`, …) and the sheet types the server names (`sheet: "chat"`).
|
package/docs/customizing.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Changing how Pi works, without code
|
|
2
2
|
|
|
3
|
-
Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi. So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
|
|
3
|
+
Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi, except Pi's extensions ([below](#pis-extensions-and-packages)). So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
|
|
4
4
|
|
|
5
5
|
## Instructions for one session
|
|
6
6
|
|
|
@@ -23,6 +23,14 @@ Pi's `configuration.md` gives the full list of names, with `AGENTS.override.md`.
|
|
|
23
23
|
|
|
24
24
|
Keep the files short and true. They go with each request, and a rule that Pi cannot obey is worse than no rule.
|
|
25
25
|
|
|
26
|
+
## PiP's instructions
|
|
27
|
+
|
|
28
|
+
PiP has no project, so it does not read AGENTS.md files. Write the rules for PiP, such as the language of its answers, in `pip.md` in Pi Pocket's data folder: `~/.pi-pocket/pip.md`, unless `--data` or `PI_POCKET_DIR` names another folder (since 0.28.0).
|
|
29
|
+
|
|
30
|
+
- PiP gets the file with each message. When the file changes, the next message has the new text.
|
|
31
|
+
- Only PiP reads it: sessions, subagents, and Pi's terminal app do not.
|
|
32
|
+
- A session that PiP messages still answers PiP in Simplified Technical English. PiP answers you as the file says.
|
|
33
|
+
|
|
26
34
|
## Skills: procedures that Pi follows on request
|
|
27
35
|
|
|
28
36
|
A skill is a folder with a `SKILL.md`: a name and a description at the top, and the steps below. Its name and description go into the system prompt. Pi reads the rest when a task matches it, or when a person sends `/skill:name what to do`.
|
|
@@ -54,7 +62,9 @@ Use a template for a message that people send often. Use a skill for steps that
|
|
|
54
62
|
|
|
55
63
|
## Models and providers
|
|
56
64
|
|
|
57
|
-
People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add a model or a provider that Pi does not know,
|
|
65
|
+
People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add a model or a provider that Pi does not know, add it to `models.json` as Pi's `models.md` says. A provider that needs code comes as a Pi Pocket drop-in that calls `host.registerModelProvider` ([host.md](extensions/reference/host.md#registermodelprovider)), not as a Pi extension: see [Pi's extensions and packages](#pis-extensions-and-packages).
|
|
66
|
+
|
|
67
|
+
**A Claude subscription.** Sign in to Anthropic with it in Providers. Then turn on **Claude subscription billing** in Menu → Extensions → Installed → **Built in**, so that requests count against the plan. It is off by default. Without it, Anthropic can bill the requests as extra usage, and refuse them when that is used up. Anthropic can change how it counts requests at any time.
|
|
58
68
|
|
|
59
69
|
Models are the person's choice, never Pi's:
|
|
60
70
|
|
|
@@ -129,6 +139,10 @@ These are in the app, not in files. Tell the person where they are. Do not chang
|
|
|
129
139
|
|
|
130
140
|
See [features.md](features.md) for each of them.
|
|
131
141
|
|
|
142
|
+
## Pi's extensions and packages
|
|
143
|
+
|
|
144
|
+
Pi Pocket reads Pi's sign-ins, models, settings, skills, prompt templates, and AGENTS.md files, but not Pi's extensions. It does not load `~/.pi/agent/extensions/`, the `extensions` setting, or the packages of the `packages` setting in Pi's `settings.json`. Pi Pocket runs on Pi Durable, and its extensions are of another kind ([extensions.md](extensions.md)). For something that a Pi package gives, look in Menu → Extensions: under **Built in**, and in **Discover**.
|
|
145
|
+
|
|
132
146
|
## When this is not enough
|
|
133
147
|
|
|
134
148
|
To give Pi a new tool, add a rule to its prompt that depends on the session's state, or check its tool calls, write an extension: [extensions.md](extensions.md). An extension can also add a page, a rail button, or a route to the app ([Adding to the app](extensions/app.md)).
|
package/docs/docker.md
CHANGED
|
@@ -61,6 +61,8 @@ Do not use `PI_POCKET_ACCESS=local` with the published port: `local` listens on
|
|
|
61
61
|
|
|
62
62
|
`cloudflare` works in the container: the image already contains `cloudflared`, so the launcher does not need a terminal to download it. The tunnel runs inside the container, and the published port is not used. `tailscale` looks for a Tailscale address in the container, which it usually does not have. Run Tailscale on the host instead: publish the port on `127.0.0.1` as above and point `tailscale serve` at it, or run the container with `network_mode: host`.
|
|
63
63
|
|
|
64
|
+
`tailscale-serve` does not work from the container as shipped: the image has no `tailscale` command, and it would need the host's `tailscaled` socket as well. Keep Tailscale on the host and mount the port by hand, as above; the launcher's own mode is for a native install.
|
|
65
|
+
|
|
64
66
|
## Permissions
|
|
65
67
|
|
|
66
68
|
Compose runs the container as root. With rootless Podman, root inside the container is your own host user, so the bind-mounted folders are writable without extra work. This is why the default is root, despite the Browser panel being a Chromium process.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// Quiet note's browser module: until a person chooses otherwise, this browser hides the module's notes, so they show
|
|
2
|
+
// only through Find or the note's row control. The model still reads each one.
|
|
3
|
+
// The app loads it and calls its default export with `pocket` (docs/extensions.md).
|
|
4
|
+
|
|
5
|
+
/** The version of `pocket` this module was written for: an older app does not load it. */
|
|
6
|
+
export const pocketApi = 1;
|
|
7
|
+
|
|
8
|
+
const NOTE = "x.quiet-note.note";
|
|
9
|
+
|
|
10
|
+
export default function setup(pocket) {
|
|
11
|
+
// On an older app there is nothing to set: the notes show as the app shows them.
|
|
12
|
+
if (typeof pocket.entryPresentation !== "function") {
|
|
13
|
+
return;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
// `open` is the message, `folded` is one line (the app's default), and `hidden` keeps the turn until Find.
|
|
17
|
+
// Only a browser with no choice yet: a person who picked "Fold" or "Show" on a note keeps what they picked.
|
|
18
|
+
if (pocket.entryPresentation(NOTE) === undefined) {
|
|
19
|
+
pocket.entryPresentation(NOTE, "hidden");
|
|
20
|
+
}
|
|
21
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A note the transcript can fold: one line in the app, and the whole message for the model.
|
|
3
|
+
* An example drop-in: copy it and `quiet-note.js` into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
|
+
*/
|
|
5
|
+
import { Type } from "@earendil-works/pi-ai";
|
|
6
|
+
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
|
+
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
|
+
import type { Web } from "../../types/pocket.d.ts";
|
|
9
|
+
|
|
10
|
+
/** The start of a note nobody wrote. A message a person sends that starts this way stays theirs. */
|
|
11
|
+
const NOTE = "NOTE ";
|
|
12
|
+
|
|
13
|
+
const leaveNote = defineTool({
|
|
14
|
+
name: "quiet_note",
|
|
15
|
+
description:
|
|
16
|
+
"Leave a note in this session. The app may show one line; you still read the whole note.",
|
|
17
|
+
parameters: Type.Object({
|
|
18
|
+
text: Type.String({ description: "The whole note" }),
|
|
19
|
+
summary: Type.String({ description: "A few words for the one line" }),
|
|
20
|
+
}),
|
|
21
|
+
// The request id is this call's, so a replay finds the note instead of leaving another.
|
|
22
|
+
replay: "safe",
|
|
23
|
+
execute: async (args, api, context) => {
|
|
24
|
+
const text = args.text.trim();
|
|
25
|
+
const summary = args.summary.replace(/\s+/g, " ").trim();
|
|
26
|
+
|
|
27
|
+
if (text === "" || summary === "") {
|
|
28
|
+
throw new Error("Give the whole note and a short summary.");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const body = text.startsWith(NOTE) ? text : `${NOTE}${text}`;
|
|
32
|
+
const conversation = await api.conversation(api.conversationId, context);
|
|
33
|
+
|
|
34
|
+
if (conversation === undefined) {
|
|
35
|
+
throw new Error("This session is gone.");
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// After this turn: the note is the next message the model reads, in full.
|
|
39
|
+
await conversation.submit(
|
|
40
|
+
{
|
|
41
|
+
type: "input",
|
|
42
|
+
content: body,
|
|
43
|
+
whenBusy: "followUp",
|
|
44
|
+
requestId: `quiet-note:${api.taskId}:${api.callId}`,
|
|
45
|
+
entry: { kind: "x.quiet-note.note", data: { summary } },
|
|
46
|
+
},
|
|
47
|
+
context,
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
return {
|
|
51
|
+
output: [
|
|
52
|
+
{
|
|
53
|
+
type: "text" as const,
|
|
54
|
+
text: "The note is in the session. You still read it in full.",
|
|
55
|
+
},
|
|
56
|
+
],
|
|
57
|
+
};
|
|
58
|
+
},
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
// It returns `output`, so it needs version 2 of the extension API.
|
|
62
|
+
export const pocketApi = 2;
|
|
63
|
+
|
|
64
|
+
export default function createQuietNote(_host: unknown, web: Web) {
|
|
65
|
+
web.presentEntry({
|
|
66
|
+
kind: "x.quiet-note.note",
|
|
67
|
+
label: "Note",
|
|
68
|
+
userPrefix: NOTE,
|
|
69
|
+
});
|
|
70
|
+
web.client("quiet-note.js");
|
|
71
|
+
|
|
72
|
+
return defineExtension({ name: "example-quiet-note", tools: [leaveNote] });
|
|
73
|
+
}
|
package/docs/extensions/app.md
CHANGED
|
@@ -9,6 +9,7 @@ The second argument of the default export, `web`, registers these parts while th
|
|
|
9
9
|
- **Routes** on the server, under `/api/x/<module>/`. The browser module calls them. Keys and other secrets stay on the server. See [Routes](routes.md).
|
|
10
10
|
- **A browser module**: a `.js` file that the app loads in the tabs of the people that it is for. Through `pocket`, the app's API for extensions, it adds rail buttons, pages, sheets, panels, status-line items, menu rows, and launcher actions, and says how its tools' calls show. See [Browser modules](browser-modules.md).
|
|
11
11
|
- **Commands** for the message box (`/name`). They run on the server, and need no browser module. See [Slash commands](commands.md).
|
|
12
|
+
- **A presentation** (since 0.28.0, experimental) for an input this module sends. The transcript shows one line, which opens to the message, or hides it until Find. The model still reads the message in full. See [`web.presentEntry`](reference/web.md#presententry). Each browser chooses open, folded, or hidden: a person in the row's message sheet, and a browser module, for its own kinds, with [`pocket.entryPresentation`](reference/pocket.md#entrypresentation), which also reads the choice. An input stored as the module's own kind is not a person's message: it cannot be sent again, and `pocket.messages` leaves it out.
|
|
12
13
|
- **Public pages** (since 0.22.0, experimental) for anyone with one of the module's links, with no sign-in. See [Public pages](public-pages.md).
|
|
13
14
|
|
|
14
15
|
```typescript
|
|
@@ -61,6 +61,7 @@ The host's members do not change while modules reload. A new member comes only a
|
|
|
61
61
|
- `api`, `module`, `route`, `conversationRoute` (since 0.16.0), `client`, `command`, `send`, `error`, and `onDispose`.
|
|
62
62
|
- `provide`, `use`, `onService`, `settings`, `setting`, and `onSettings` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md)).
|
|
63
63
|
- `publicPage` and `links` (experimental, since 0.22.0): pages at `/l/<token>` for anyone with a module's link, what a page handler gets (`PublicPageRequest`), and what its answer does ([Public pages](../public-pages.md)).
|
|
64
|
+
- `presentEntry` (experimental, since 0.28.0), with `PresentEntry`: how an input this module sends shows in the transcript. The model still reads that message in full ([Adding to the app](../app.md)).
|
|
64
65
|
- What a route handler gets (`WebRequest`: `method`, `params`, `query`, `body`, `user`, `signal`; since 0.16.0 also request-lifetime `snapshot`, `context`, `commit`), and what its answer does.
|
|
65
66
|
- A conversation-bound request's `conversation` metadata and human `linkedSessions.start` / `list`, with their authenticated-actor, receipt, and admission checks (since 0.16.0).
|
|
66
67
|
- The route paths, the methods, the `access` values (`owner`, `steer`, `view`), and the `X-Pocket` header that every call to a route must have.
|
|
@@ -164,6 +165,8 @@ Since 0.26.0, `pocket.pip` (`ask`) is experimental, with `PipApi` and `PipAskRes
|
|
|
164
165
|
|
|
165
166
|
Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` field of `host.browser`'s `snapshot()`.
|
|
166
167
|
|
|
168
|
+
Since 0.28.0, `web.presentEntry` and `pocket.entryPresentation` are experimental, with `PresentEntry`. A module names how an input it sends shows. The model still reads that message in full. Since then too, `pocket.messages` leaves out an input stored as a module's own kind: before, such an input was not a message in the transcript at all.
|
|
169
|
+
|
|
167
170
|
Since 0.20.0, the session list's extension points are experimental: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, and `sessionSearch`, `WebRequest.sessions`, and their types. So is `pocket.composerKey`, with `ComposerKeySpec` and `ComposerBox`, and so are `pocket.onConversation`, `messages`, and `reveal`, with `MessagesOptions`, `MessagePage`, and `MessageInfo`. So are `host.registerModelProvider`, and `host.fetchPublic` with `PublicFetchInit`.
|
|
168
171
|
|
|
169
172
|
### Deprecated
|
|
@@ -171,6 +171,17 @@ All the numbers that limit a module, in one place. Each group links to the guide
|
|
|
171
171
|
- **`revoked`:** 50 commits at most, each with a reason of 300 characters at most.
|
|
172
172
|
- **Looks for revoked versions:** two times a day, while extensions from the index are installed.
|
|
173
173
|
|
|
174
|
+
## Presentations
|
|
175
|
+
|
|
176
|
+
[Adding to the app](../app.md)
|
|
177
|
+
|
|
178
|
+
- **Presentations of one module:** 32 at most.
|
|
179
|
+
- **A kind:** `x.<module>.<name>`. `<name>` is 1 to 64 characters: a letter or a digit, then letters, digits, `_`, and `-`.
|
|
180
|
+
- **A label:** one line of 80 characters at most, with no control characters.
|
|
181
|
+
- **A `userPrefix`:** up to 200 characters, at least 3 of them not spaces, and not starting with `[` (the app's own inputs nobody typed do). It cannot start another module's `userPrefix`, or start with one, nor another of the same module's.
|
|
182
|
+
- **`entry.data.summary`:** whitespace collapsed to one line, and past 200 characters cut to 199 and "…".
|
|
183
|
+
- **Modes this browser remembers:** 256 kinds; past that, the one chosen longest ago is forgotten. Each is `open`, `folded`, or `hidden`.
|
|
184
|
+
|
|
174
185
|
## Themes
|
|
175
186
|
|
|
176
187
|
[Themes](../themes.md)
|
|
@@ -276,7 +276,7 @@ messages(options?: MessagesOptions): Promise<MessagePage>;
|
|
|
276
276
|
|
|
277
277
|
Since 0.20.0 · Experimental
|
|
278
278
|
|
|
279
|
-
Reads a page of the people's messages in the session the tab shows, oldest first: Pi's answers, tool calls, and notes are not in it. With no `before`, it is the newest `limit` messages (50 by default, up to 200). The page's `before` is the cursor for the page before it, and null at the start. Read pages until `before` is null to have them all. The messages are those of the transcript: after a New context, the earlier ones are not in it.
|
|
279
|
+
Reads a page of the people's messages in the session the tab shows, oldest first: Pi's answers, tool calls, and notes are not in it. Neither is an input a module stored as its own kind, even while it shows as a message ([`web.presentEntry`](web.md#presententry)). A user message that a module's `userPrefix` presents stays in: it is a message to Pi, as it was before. With no `before`, it is the newest `limit` messages (50 by default, up to 200). The page's `before` is the cursor for the page before it, and null at the start. Read pages until `before` is null to have them all. The messages are those of the transcript: after a New context, the earlier ones are not in it.
|
|
280
280
|
|
|
281
281
|
The server checks the person's access to the session for each page. A page is from the session that the tab showed when it was asked for (`conversationId`): compare it with the one shown now before you use it. It rejects with an error whose `status` is 409 when its cursor is stale, as after a compaction: read again from the newest. Abort it with `signal`. With no session open, or from a version of the module that is gone, the page is empty. See [`MessagesOptions`](#messagesoptions), [`MessagePage`](#messagepage), and [`MessageInfo`](#messageinfo).
|
|
282
282
|
|
|
@@ -323,6 +323,27 @@ pocket.sheet({
|
|
|
323
323
|
});
|
|
324
324
|
```
|
|
325
325
|
|
|
326
|
+
### `entryPresentation`
|
|
327
|
+
|
|
328
|
+
```ts
|
|
329
|
+
entryPresentation(kind: string, mode: "open" | "folded" | "hidden"): void;
|
|
330
|
+
entryPresentation(kind: string): "open" | "folded" | "hidden" | undefined;
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Since 0.28.0 · Experimental
|
|
334
|
+
|
|
335
|
+
How this browser shows one of this module's inputs (`web.presentEntry` on the server). `kind` is `x.<module>.<name>`. `open` shows the message. `folded` shows one line, which opens to the text: that is also how it shows when this browser has no choice. `hidden` keeps the turn and shows nothing until Find jumps to it. The model still reads the message in full.
|
|
336
|
+
|
|
337
|
+
With a mode, it sets this browser's choice; the same mode again changes nothing. With the kind alone, it returns the choice, or undefined when there is none yet. A person can choose too: the message sheet of any of these rows has Show, Fold, and Hide for every input of its kind. So set a mode only when there is none, or from a command the person runs, and a person's choice stays theirs. The choice stays in this browser, and its other tabs follow it.
|
|
338
|
+
|
|
339
|
+
A kind that is not this module's throws, and so does a mode that is not one of those three. This browser remembers a limited number of kinds; past it, the one chosen longest ago is forgotten ([limits](limits.md#presentations)). Where the browser cannot store it, the choice lasts until the tab reloads. On an older app, check for it first.
|
|
340
|
+
|
|
341
|
+
```js
|
|
342
|
+
if (typeof pocket.entryPresentation === "function" && !pocket.entryPresentation("x.notes.note")) {
|
|
343
|
+
pocket.entryPresentation("x.notes.note", "hidden");
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
326
347
|
## Routes and events
|
|
327
348
|
|
|
328
349
|
### `api`
|
|
@@ -132,6 +132,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
132
132
|
| `home-list` | The session list as a phone's home screen |
|
|
133
133
|
| `pane` | The conversation's window (or the subagents board, or an extension's page) |
|
|
134
134
|
| `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
|
|
135
|
+
| `tabstrip`, `tabstrip-tab`, `tabstrip-name` | The session tabs above the title bar: the strip, each tab (`data-state`, its `--folder` color), and its name |
|
|
135
136
|
|
|
136
137
|
### The conversation
|
|
137
138
|
|
|
@@ -142,6 +143,10 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
142
143
|
| `prompt` | A person's message |
|
|
143
144
|
| `prompt-head`, `author-mark`, `prompt-author` | Its head: who sent it and when; their initials; their name |
|
|
144
145
|
| `prompt-text` | What it says (its skill chip, words, and files) |
|
|
146
|
+
| `presented-input`, `presented-head` | An extension's input (`web.presentEntry`), folded: its card and the line that opens it (since 0.28.0) |
|
|
147
|
+
| `presented-chevron`, `presented-tag` | That line's chevron; the input's label in its head, when shown open (since 0.28.0) |
|
|
148
|
+
| `presented-more` | The button beside that line that opens its message sheet (since 0.28.0) |
|
|
149
|
+
| `presented-choice` | In its message sheet: Show, Fold, and Hide for every input of its kind (since 0.28.0) |
|
|
145
150
|
| `reply` | Pi's answer |
|
|
146
151
|
| `reply-quote` | The passage a reply quotes, at the top of a message (since 0.27.0) |
|
|
147
152
|
| `reply-actions` | The row under an answer: react, discuss, pin, copy |
|
|
@@ -199,6 +204,11 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
199
204
|
| `browser-panel` | The Browser panel |
|
|
200
205
|
| `pip` | PiP's panel |
|
|
201
206
|
| `subagents-board` | The subagents board |
|
|
207
|
+
| `running-board` | The Running now board |
|
|
208
|
+
| `running-timeline` | Its Coming up timeline |
|
|
209
|
+
| `running-needs` | Its Needs you list |
|
|
210
|
+
| `running-next` | Its Next up list |
|
|
211
|
+
| `running-schedule` | The schedule selected on it |
|
|
202
212
|
| `extension-page` | An extension's page, with `data-module` naming its module |
|
|
203
213
|
| `extension-panel` | An extension's panel, with `data-module` naming its module (since 0.19.0) |
|
|
204
214
|
| `diff` | A diff, in a tool call, a reply, or the review |
|
|
@@ -214,6 +224,8 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
214
224
|
| `session-button` | `aria-current` | `page` on the open session's |
|
|
215
225
|
| `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open; none on Priority's Needs you head, which does not fold |
|
|
216
226
|
| `activity` | `data-state` | `open` while open |
|
|
227
|
+
| `presented-input` | `data-state` | `open` while open; its `presented-head` has `aria-expanded` `true` (since 0.28.0) |
|
|
228
|
+
| `prompt-row` | `data-entry-kind` | The input's kind (`x.<module>.<name>`) on one an extension presents (since 0.28.0) |
|
|
217
229
|
| `tool-call` | `data-state` | `running`, `ok`, `failed`, `waiting` (for approval), `denied`, `stopped` |
|
|
218
230
|
| `prompt` | `data-from` | `me`, `person` (someone else), `linked` (a linked session), `other` (Pi's schedule, the main agent, a watch or a webhook) |
|
|
219
231
|
| `send-button` | `data-state` | `ready` when there is something to send |
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# web
|
|
2
2
|
|
|
3
|
-
`web` is the second argument of a module's default export. With it, a module adds to the app what a tool cannot: routes on the server, a browser module,
|
|
3
|
+
`web` is the second argument of a module's default export. With it, a module adds to the app what a tool cannot: routes on the server, a browser module, commands for the message box, and how its own inputs show. [Adding to the app](../app.md) tells you how the parts work together.
|
|
4
4
|
|
|
5
|
-
Register routes, the browser module, and
|
|
5
|
+
Register routes, the browser module, commands, and presentations while the module loads. After that, these calls throw. What you register goes when this version of the module goes: an edit replaces it, or the owner turns the module off.
|
|
6
6
|
|
|
7
7
|
The types are `Web` and the types that it uses, in [types/pocket.d.ts](../../../types/pocket.d.ts).
|
|
8
8
|
|
|
@@ -94,6 +94,26 @@ Adds the command `/name` to the message box, for the people who can run it. The
|
|
|
94
94
|
- [Command context](command-context.md) gives the fields of `command` and what its handler gets and returns.
|
|
95
95
|
- [Slash commands](../commands.md) tells you who can run a command, how a run is kept, and how a person stops it.
|
|
96
96
|
|
|
97
|
+
### `presentEntry`
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
presentEntry(spec: PresentEntry): void;
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Since 0.28.0 · Experimental
|
|
104
|
+
|
|
105
|
+
Says how an input this module sends shows in the transcript, while the module is on. The model still reads the message in full. Nothing registered here is stored.
|
|
106
|
+
|
|
107
|
+
- `kind` is `x.<module>.<name>`: this module's name, then a name of letters, digits, `_` and `-`.
|
|
108
|
+
- `label` is one short line ([limits](limits.md#presentations)).
|
|
109
|
+
- `userPrefix`, when set, matches a user message that starts with it only when nobody wrote that message. A message a person sent stays theirs. It is a few characters at least, and cannot start with `[`: the app's own inputs nobody typed (subagent reports, linked sessions, schedules) do ([limits](limits.md#presentations)).
|
|
110
|
+
- A module registers a limited number of presentations ([limits](limits.md#presentations)). Two modules cannot share a kind, and no prefix can start another one.
|
|
111
|
+
- Turning the module off, or a load that fails, drops the registration. Open transcripts show the change at once, as do rows whose author becomes known.
|
|
112
|
+
- An input stored as the module's own kind cannot be sent again from its message sheet, and [`pocket.messages`](pocket.md#messages) leaves it out: it is not a person's message to Pi. A user message that `userPrefix` matched stays one.
|
|
113
|
+
- Each browser chooses how these inputs show: a person picks Show, Fold, or Hide in a row's message sheet, and a browser module can read or set that choice for its own kinds with [`pocket.entryPresentation`](pocket.md#entrypresentation).
|
|
114
|
+
|
|
115
|
+
The module puts a short `summary` string on the entry's data when it submits. The transcript shows `label`, or `label · summary` when that string is there. See [`PresentEntry`](#presententry).
|
|
116
|
+
|
|
97
117
|
### `publicPage`
|
|
98
118
|
|
|
99
119
|
```ts
|
|
@@ -401,6 +421,20 @@ Since 0.22.0 · Experimental
|
|
|
401
421
|
|
|
402
422
|
Draws a public page. A `POST` to a link with `uses` counts one before the handler runs. A handler that throws, or answers with a status of 400 or more, gives it back.
|
|
403
423
|
|
|
424
|
+
### `PresentEntry`
|
|
425
|
+
|
|
426
|
+
```ts
|
|
427
|
+
interface PresentEntry {
|
|
428
|
+
kind: string;
|
|
429
|
+
label: string;
|
|
430
|
+
userPrefix?: string;
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
Since 0.28.0 · Experimental
|
|
435
|
+
|
|
436
|
+
What [`presentEntry`](#presententry) registers. `kind` is the stored kind. `label` is the line the transcript shows. `userPrefix` matches the start of a user message that nobody wrote.
|
|
437
|
+
|
|
404
438
|
### `PublicPageAnswer`
|
|
405
439
|
|
|
406
440
|
```ts
|
package/docs/extensions.md
CHANGED
|
@@ -25,6 +25,7 @@ This page is the map. Read all of it, then only the pages that your task needs.
|
|
|
25
25
|
| Use the app's services, and work with older servers | [Using the host](extensions/host.md) |
|
|
26
26
|
| Start sessions, and send messages between them | [Starting and messaging sessions](extensions/linked-sessions.md) |
|
|
27
27
|
| Add to the app: routes, a browser module, commands | [Adding to the app](extensions/app.md) |
|
|
28
|
+
| Name how an input this module sends shows in the transcript | [Adding to the app](extensions/app.md), [`web.presentEntry`](extensions/reference/web.md#presententry) |
|
|
28
29
|
| Answer requests on the server, and say who may use them | [Routes](extensions/routes.md) |
|
|
29
30
|
| Show a page to anyone with a link, with no sign-in | [Public pages](extensions/public-pages.md) |
|
|
30
31
|
| Ask for a password or a key, hide it, or drive the browser page | [People's values and the browser](extensions/people-values.md) |
|
|
@@ -102,6 +103,7 @@ These examples work. `npm test` runs them (`test/docs-examples.test.ts`):
|
|
|
102
103
|
- [examples/no-force-push.ts](examples/no-force-push.ts): a hook that stops some bash calls, and a prompt section that tells Pi so.
|
|
103
104
|
- [examples/read-page.ts](examples/read-page.ts): a tool that reads a public web page with `host.fetchPublic`, and fences its text with `host.text`.
|
|
104
105
|
- [examples/server-status.ts](examples/server-status.ts) with [examples/server-status.js](examples/server-status.js): a page on the rail, with a route that reads the machine's load and memory, and events that keep it live.
|
|
106
|
+
- [examples/quiet-note.ts](examples/quiet-note.ts) with [examples/quiet-note.js](examples/quiet-note.js): an input the transcript can fold. The model still reads the whole message.
|
|
105
107
|
|
|
106
108
|
## Rules that are easy to break
|
|
107
109
|
|