pi-pocket 0.28.0-beta.2 → 0.28.0-beta.4
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/contrib/systemd/pi-pocket@.service +1 -1
- package/docs/architecture.md +2 -2
- package/docs/customizing.md +10 -1
- package/docs/design/design-mode.md +1 -1
- package/docs/extensions/linked-sessions.md +20 -4
- package/docs/extensions/policies/api-stability.md +5 -2
- package/docs/extensions/policies/core-or-extension.md +1 -1
- package/docs/extensions/reference/api-versions.md +3 -0
- package/docs/extensions/reference/host.md +42 -7
- package/docs/extensions/reference/names.md +1 -1
- package/docs/extensions/reference/web.md +77 -0
- package/docs/extensions/services-settings.md +8 -8
- package/docs/features.md +3 -3
- package/docs/map.md +70 -68
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/launcher/access.ts +8 -1
- package/src/launcher/main.ts +101 -41
- package/src/launcher/options.ts +1 -1
- package/src/launcher/serve.ts +51 -22
- package/src/server/app-events.ts +11 -1
- package/src/server/app.ts +162 -15
- package/src/server/background.ts +62 -29
- package/src/server/build.ts +1 -1
- package/src/server/conversation-usage.ts +235 -0
- package/src/server/design/scan-facts.ts +1 -0
- package/src/server/design/scan-import-eval.ts +15 -8
- package/src/server/design/scan-import.ts +15 -3
- package/src/server/design/scan.ts +18 -15
- package/src/server/design/system-types.ts +6 -0
- package/src/server/design/system.ts +106 -8
- package/src/server/design/tokens-resync.ts +542 -0
- package/src/server/design/tokens.ts +34 -3
- package/src/server/docs.ts +30 -1
- package/src/server/entry-presentation.ts +20 -0
- package/src/server/extensions/anthropic-subscription.ts +6 -4
- package/src/server/extensions/artifacts.ts +101 -41
- package/src/server/extensions/pip.ts +4 -0
- package/src/server/extensions/plan.ts +1 -2
- package/src/server/guides/artifact-bridge.md +1 -1
- package/src/server/guides/design.md +1 -0
- package/src/server/host.ts +39 -0
- package/src/server/http/extension-routes.ts +3 -0
- package/src/server/linked-sessions.ts +214 -2
- package/src/server/pip-compact.ts +1 -0
- package/src/server/pip.ts +3 -3
- package/src/server/reload.ts +1 -0
- package/src/server/room.ts +1 -1
- package/types/pocket.d.ts +86 -2
- package/web/index.html +50 -0
- package/web/pip.js +1 -1
- package/web/rich.js +1 -1
- package/web/running-board.js +107 -32
- package/web/sessions.js +61 -12
- package/web/sheets/extensions.js +23 -4
- package/web/sheets/find.js +8 -2
- package/web/store.js +1 -1
- package/web/style.css +14 -0
- package/web/text-hash.d.ts +2 -0
- package/web/{fingerprint.js → text-hash.js} +2 -1
- package/web/transcript.js +13 -4
- package/web/turns.js +7 -3
- package/web/fingerprint.d.ts +0 -2
package/README.md
CHANGED
|
@@ -82,7 +82,7 @@ Choose a mode in the launcher, or pass `--access`:
|
|
|
82
82
|
| `tailscale` | Your tailnet | Plain http on the tailnet address |
|
|
83
83
|
| `tailscale-serve` | Your tailnet | https at the tailnet name; needs `tailscale` 1.52 or newer |
|
|
84
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.
|
|
85
|
+
`tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet, and, when the launcher does not run as root, that user as tailscaled's operator (`sudo tailscale set --operator=$USER`). It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. `--host` cannot be combined with it: serve always listens on `127.0.0.1` and lets tailscaled reach it. For another tunnel (ngrok), choose `local` and point it at port 8787.
|
|
86
86
|
|
|
87
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)).
|
|
88
88
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[Unit]
|
|
4
4
|
Description=Pi Pocket (%i access)
|
|
5
5
|
Documentation=https://github.com/TannerMidd/pi-pocket/blob/main/docs/systemd.md
|
|
6
|
-
Wants=network-online.target
|
|
6
|
+
Wants=network-online.target tailscaled.service
|
|
7
7
|
After=network-online.target tailscaled.service
|
|
8
8
|
|
|
9
9
|
[Service]
|
package/docs/architecture.md
CHANGED
|
@@ -18,7 +18,7 @@ Some state lives in this process alone, and a restart forgets it. For example:
|
|
|
18
18
|
- who is connected, typing, or away;
|
|
19
19
|
- which tool calls wait for approval;
|
|
20
20
|
- the browser's pages;
|
|
21
|
-
- when each run ended, which peek tiles and session-list squares use
|
|
21
|
+
- when each run ended, which peek tiles and session-list squares use (why a session's last run failed is kept: `pocket.run-failure`);
|
|
22
22
|
- provider sign-ins in progress;
|
|
23
23
|
- the edit and write calls Changes found in each session's history, so a look reads only the entries added since.
|
|
24
24
|
|
|
@@ -173,7 +173,7 @@ A full view for a tab of protocol 4 has the order of every entry in the active c
|
|
|
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/
|
|
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/text-hash.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
177
|
|
|
178
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
179
|
|
package/docs/customizing.md
CHANGED
|
@@ -64,7 +64,16 @@ Use a template for a message that people send often. Use a skill for steps that
|
|
|
64
64
|
|
|
65
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
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.
|
|
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, and it asks before it turns on. Without it, Anthropic can bill the requests as extra usage, and refuse them when that is used up.
|
|
68
|
+
|
|
69
|
+
> [!WARNING]
|
|
70
|
+
> **Using a Claude subscription in Pi Pocket is at your own risk.** Anthropic's terms and its help pages disagree on it:
|
|
71
|
+
>
|
|
72
|
+
> - Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) forbid accessing its services "through automated or non-human means, whether through a bot, script, or otherwise", except with an Anthropic API key or where Anthropic explicitly permits it.
|
|
73
|
+
> - Its help pages say that third-party apps can use your subscription limits. Yet its servers often bill such requests as extra usage.
|
|
74
|
+
> - Claude subscription billing makes Pi Pocket's requests look like Claude Code's.
|
|
75
|
+
>
|
|
76
|
+
> Anthropic can change how it counts these requests, refuse them, or act on an account it finds using them. An Anthropic API key, or a model from another provider, has none of these risks.
|
|
68
77
|
|
|
69
78
|
Models are the person's choice, never Pi's:
|
|
70
79
|
|
|
@@ -29,7 +29,7 @@ Rules for every stream:
|
|
|
29
29
|
|
|
30
30
|
A design needs images, fonts, data files, and more than one page. Today an artifact is one UTF-8 file.
|
|
31
31
|
|
|
32
|
-
- The `artifact` and `artifact_inline`
|
|
32
|
+
- The `artifact` tool (and `artifact_inline`, until 0.28.0, when `inline: true` replaced it) gets `assets`: up to 200 entries of `{ name, path }` (copy a file from the session's machine, binary allowed) or `{ name, content }` (UTF-8 text). `name` is a relative path: segments of `[A-Za-z0-9._-]`, joined by `/`, no `.` or `..` segment, no leading `/`, up to 200 characters.
|
|
33
33
|
- A new version keeps the assets of the version before. `removeAssets: string[]` drops some. An entry with an existing name replaces it.
|
|
34
34
|
- Limits: 5 MB for one asset, 20 MB for all the assets of one version, as constants beside `MAX_BYTES`.
|
|
35
35
|
- Storage: assets are stored once for each content hash (sha256) in a new document kind, `pocket.artifact-asset`, keyed by the hash, with the bytes in base64. `ArtifactVersion` gets an optional `assets?: Record<string, { hash: string; size: number; type: string }>`. A replayed call must find what it wrote, as the body does.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Starting and messaging sessions
|
|
2
2
|
|
|
3
|
-
A tool can start a session from the session that it runs in,
|
|
3
|
+
A tool can start a session from the session that it runs in, send messages between such sessions, and stop or archive one. Agent Teams does this ([agent-teams.ts](../../src/server/extensions/agent-teams.ts)). A team or orchestration extension uses the same calls. Use `host.linkedSessions`. Its members are in [the host reference](reference/host.md).
|
|
4
4
|
|
|
5
5
|
**Experimental** in 0.14: it can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)).
|
|
6
6
|
|
|
@@ -44,18 +44,34 @@ Check for `web.conversationRoute` at runtime and set gallery `minPocket: "0.16.0
|
|
|
44
44
|
- `send` returns when the session takes the message, not when it answers.
|
|
45
45
|
- The session that gets the message reads it in a fence. Words before it say that another session's agent wrote it, that it is a request and not an order from a person, and which address to reply to.
|
|
46
46
|
|
|
47
|
+
## Stop a run
|
|
48
|
+
|
|
49
|
+
`stop(source, { to }, key)` stops the run of the linked session at the address `to`, and withdraws what waits in its queue. Stopping is the safe direction: it needs the same access as `send`, including the turn and room under the spend limit.
|
|
50
|
+
|
|
51
|
+
- When the session is idle, it has no run to stop: the call only withdraws what waits in its queue.
|
|
52
|
+
- It returns `{ busy }`. `busy` is true when the session was working.
|
|
53
|
+
- Since 0.28.0. An older Pi Pocket has no `stop`, so a module checks for it and sets `minPocket` to `0.28.0` when it needs it.
|
|
54
|
+
|
|
55
|
+
## Archive a session
|
|
56
|
+
|
|
57
|
+
`archive(source, { to, archived? }, key)` archives the linked session at the address `to`. With `archived: false`, it brings the session back. Without `archived`, it archives.
|
|
58
|
+
|
|
59
|
+
- It returns `{ archived, repeating }`. `archived` says whether the session is archived now. `repeating` is how many of its repeating schedules keep running: an archive does not stop them.
|
|
60
|
+
- It needs the same access as `send`.
|
|
61
|
+
- Since 0.28.0, with the same check as `stop`.
|
|
62
|
+
|
|
47
63
|
## List the sessions
|
|
48
64
|
|
|
49
65
|
`list(source)` gives the sessions linked to the source, at any distance, that the person whom Pi works for can see.
|
|
50
66
|
|
|
51
67
|
- Each one has an `address` of the source's own, so no session's id goes into the source's transcript.
|
|
52
|
-
- Each one has its title, folder, and state only when all the people who see the source also see it.
|
|
68
|
+
- Each one has its title, folder, and state only when all the people who see the source also see it. Since 0.28.0 that state includes `failed`: why its last run gave up, the same short line the session list shows, and only while that failure stands. A later run clears it. A run that was stopped is not a failure.
|
|
53
69
|
|
|
54
70
|
Addresses belong to the session that has them. A fork starts with none, so it leaves the team: the addresses in the history that it copied do not work there.
|
|
55
71
|
|
|
56
72
|
## Who it acts for
|
|
57
73
|
|
|
58
|
-
`start` and `
|
|
74
|
+
`start`, `send`, `stop`, and `archive` act for the person whom Pi works for in the source. They need that person's access and right to steer. To start a session, that person must also have access to all sessions. `stop` and `archive` reach only a session of this team that the person can see.
|
|
59
75
|
|
|
60
76
|
Pi Pocket refuses them while the source is in plan mode, past a spend limit, or while another person has the turn. `send` also needs the turn, and room under the spend limit, in the target session.
|
|
61
77
|
|
|
@@ -73,6 +89,6 @@ Pi Pocket keeps a team small. Past these limits ([Limits](reference/limits.md#li
|
|
|
73
89
|
|
|
74
90
|
## Replays
|
|
75
91
|
|
|
76
|
-
Give a `key` that stays the same when the call runs again: `${api.taskId}:${api.callId}`. A
|
|
92
|
+
Give a `key` that stays the same when the call runs again: `${api.taskId}:${api.callId}`. A call with a key that Pi Pocket saw before returns what the first call returned, and does not act again. So a replay makes one session, sends one message, stops one run, and archives once. A repeated `stop` returns the first call's `{ busy }`. A repeated `archive` returns the first call's `{ archived, repeating }`, not a state someone changed later. Pi Pocket keeps the record of a key for a limited time, and for a limited number of calls ([limits](reference/limits.md#linked-sessions)).
|
|
77
93
|
|
|
78
94
|
The errors say what is wrong. They do not tell Pi what to do about it: your tool tells Pi that.
|
|
@@ -45,7 +45,7 @@ These members are public:
|
|
|
45
45
|
- `roleOf(personId)` (experimental, since 0.27.0)
|
|
46
46
|
- `skillPaths()`, `skills(cwd)`
|
|
47
47
|
- `heldBack(conversationId)`, `onLimitsChanged(listener)`
|
|
48
|
-
- `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental))
|
|
48
|
+
- `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental)); `stop`, `archive` (experimental, since 0.28.0)
|
|
49
49
|
- `text`: `quoted`, `defang`
|
|
50
50
|
- `thinkingLevels`
|
|
51
51
|
- `fetchPublic(url, init)` (experimental, since 0.20.0)
|
|
@@ -64,6 +64,7 @@ The host's members do not change while modules reload. A new member comes only a
|
|
|
64
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)).
|
|
65
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.
|
|
66
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).
|
|
67
|
+
- `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage` (experimental, since 0.28.0): read-only usage for a visible conversation and its visible descendants.
|
|
67
68
|
- The route paths, the methods, the `access` values (`owner`, `steer`, `view`), and the `X-Pocket` header that every call to a route must have.
|
|
68
69
|
|
|
69
70
|
### 5. A command's `ctx` and result
|
|
@@ -165,7 +166,9 @@ Since 0.26.0, `pocket.pip` (`ask`) is experimental, with `PipApi` and `PipAskRes
|
|
|
165
166
|
|
|
166
167
|
Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` field of `host.browser`'s `snapshot()`.
|
|
167
168
|
|
|
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
|
+
Since 0.28.0, `web.presentEntry` and `pocket.entryPresentation` are experimental, with `PresentEntry`; so is `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage`. 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.
|
|
170
|
+
|
|
171
|
+
Since 0.28.0, `run.ended` carries `outcome` (`done`, `failed`, or `aborted`) and, when the run gave up, `failure`: the same short line the session list shows. `LinkedSession.failed` carries that line for a linked session's last run, with the same audience rule as its title, and only while the failure stands. Both are experimental.
|
|
169
172
|
|
|
170
173
|
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`.
|
|
171
174
|
|
|
@@ -54,7 +54,7 @@ Ask these questions in this order. The first "yes" gives the answer.
|
|
|
54
54
|
|
|
55
55
|
### Linked sessions and Agent Teams
|
|
56
56
|
|
|
57
|
-
- **Core: linked sessions** (`linked-sessions.ts`, `host.linkedSessions`). Core starts a linked session, carries messages, and
|
|
57
|
+
- **Core: linked sessions** (`linked-sessions.ts`, `host.linkedSessions`). Core starts a linked session, carries messages, lists the sessions, and stops or archives one of the team. It acts with the rights of the person Pi works for. It refuses work in plan mode. It counts the cost of the team against the budget of the top session. It stops a team at its [limits](../reference/limits.md#linked-sessions) of sessions, and of messages with no message from a person. It uses keys, so a replay acts once. It gives sessions addresses, so no session ID goes into a transcript.
|
|
58
58
|
- **Extension: Agent Teams** (`extensions/agent-teams.ts` and `agent-teams.js`). The `team` tool, its words to Pi, and how its calls show. It is off by default. At run time it uses only `host` and `web`, as a drop-in does.
|
|
59
59
|
- **Why:** pull request #84 first put Agent Teams in core. In 0.14 the mechanism stayed in core, because it decides permissions, stored data, and spend (C1 to C3). The workflow became a built-in extension (C6, C7). Another team workflow can use the same linked sessions.
|
|
60
60
|
|
|
@@ -75,6 +75,7 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
75
75
|
| `pocket.panel` and `pocket.status` (experimental) | 0.19.0 |
|
|
76
76
|
| Slots: `pocket.topbar`, `composerButton`, `replyAction`, `insertText`, `arrange` (experimental) | 0.19.0 |
|
|
77
77
|
| `cwd` in `host.linkedSessions.start` and the human-bound `linkedSessions.start` | 0.19.0 |
|
|
78
|
+
| `stop` and `archive` on `host.linkedSessions` (experimental) | 0.28.0 |
|
|
78
79
|
| The session list: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, `sessionSearch`, and `WebRequest.sessions` (experimental) | 0.20.0 |
|
|
79
80
|
| `host.registerModelProvider` (experimental) | 0.20.0 |
|
|
80
81
|
| `host.fetchPublic` (experimental) | 0.20.0 |
|
|
@@ -88,3 +89,5 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
88
89
|
| A person's role: `host.roleOf` (experimental) | 0.27.0 |
|
|
89
90
|
| The page's scroll position: `scroll` in the `host.browser` snapshot (experimental) | 0.27.0 |
|
|
90
91
|
| Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
|
|
92
|
+
| Read-only conversation and descendant usage: `ConversationWebRequest.conversationUsage` (experimental) | 0.28.0 |
|
|
93
|
+
| How a run stopped: `outcome` and `failure` on `run.ended`, and `failed` on a linked session (experimental) | 0.28.0 |
|
|
@@ -216,9 +216,9 @@ Calls `listener` each time something happens in the app: a session is made, rena
|
|
|
216
216
|
|
|
217
217
|
```typescript
|
|
218
218
|
web.onDispose(
|
|
219
|
-
host.on("run.ended", ({ conversationId, session }) => {
|
|
220
|
-
if (conversationId === session) {
|
|
221
|
-
|
|
219
|
+
host.on("run.ended", ({ conversationId, session, outcome, failure }) => {
|
|
220
|
+
if (conversationId === session && outcome === "failed") {
|
|
221
|
+
log.push({ session, failure });
|
|
222
222
|
}
|
|
223
223
|
}),
|
|
224
224
|
);
|
|
@@ -391,7 +391,7 @@ readonly linkedSessions: LinkedSessions;
|
|
|
391
391
|
|
|
392
392
|
Since 0.14.0 · Experimental
|
|
393
393
|
|
|
394
|
-
Lets a tool start sessions from the session that it runs in,
|
|
394
|
+
Lets a tool start sessions from the session that it runs in, send messages between them, and stop or archive one, as Agent Teams does. A team or orchestration extension uses the same calls. A linked session is an ordinary session. [Starting and messaging sessions](../linked-sessions.md) tells you how they work, what they cannot do, and how to call them.
|
|
395
395
|
|
|
396
396
|
Each call acts as the person that Pi works for in `source`, and that person's checks apply. Give each call a `key` that stays the same when the call runs again, such as `${api.taskId}:${api.callId}`. A second call with the same `key` does nothing again: it returns what the first call returned.
|
|
397
397
|
|
|
@@ -431,6 +431,34 @@ Sends `message` to the linked session at the address `to`. Without `steer`, the
|
|
|
431
431
|
|
|
432
432
|
The session that gets the message reads it between tags. Words before it say that the agent of another session wrote it, and that it is a request, not a person's order. They also give the address to reply to.
|
|
433
433
|
|
|
434
|
+
#### `linkedSessions.stop`
|
|
435
|
+
|
|
436
|
+
```ts
|
|
437
|
+
stop(
|
|
438
|
+
source: ConversationId,
|
|
439
|
+
request: { to: string },
|
|
440
|
+
key: string,
|
|
441
|
+
): Promise<{ busy: boolean }>;
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
Since 0.28.0 · Experimental
|
|
445
|
+
|
|
446
|
+
Stops the run of the linked session at the address `to`, and withdraws what waits in its queue. When the session is idle, it has no run to stop, and the call only withdraws what waits in its queue. `busy` is true when it was working. It needs the same access as `send`, and it reaches only a session of this team. An older Pi Pocket has no `stop`: check for it, and set `minPocket` to `0.28.0` when you need it.
|
|
447
|
+
|
|
448
|
+
#### `linkedSessions.archive`
|
|
449
|
+
|
|
450
|
+
```ts
|
|
451
|
+
archive(
|
|
452
|
+
source: ConversationId,
|
|
453
|
+
request: { to: string; archived?: boolean },
|
|
454
|
+
key: string,
|
|
455
|
+
): Promise<{ archived: boolean; repeating: number }>;
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
Since 0.28.0 · Experimental
|
|
459
|
+
|
|
460
|
+
Archives the linked session at the address `to`. With `archived: false`, it brings the session back. Without `archived`, it archives. `archived` in the result says whether the session is archived now. `repeating` is how many of its repeating schedules keep running: an archive does not stop them. It needs the same access as `send`. An older Pi Pocket has no `archive`.
|
|
461
|
+
|
|
434
462
|
#### `linkedSessions.list`
|
|
435
463
|
|
|
436
464
|
```ts
|
|
@@ -450,6 +478,7 @@ interface LinkedSession {
|
|
|
450
478
|
cwd?: string;
|
|
451
479
|
busy?: boolean;
|
|
452
480
|
archived?: boolean;
|
|
481
|
+
failed?: string;
|
|
453
482
|
}
|
|
454
483
|
```
|
|
455
484
|
|
|
@@ -458,7 +487,8 @@ Since 0.14.0 · Experimental
|
|
|
458
487
|
A linked session, as `list` gives it.
|
|
459
488
|
|
|
460
489
|
- `address`: the address that the asking session uses for it. It is never the session's id.
|
|
461
|
-
- `title`, `cwd` (its folder), `busy` (Pi works in it now), and `
|
|
490
|
+
- `title`, `cwd` (its folder), `busy` (Pi works in it now), `archived`, and `failed`: these are there only when all the people who see the asking session see this session too.
|
|
491
|
+
- `failed` (since 0.28.0): why its last run gave up, the same short line the session list shows. It is there only while that failure stands. A later run clears it, and a run that was stopped leaves none.
|
|
462
492
|
|
|
463
493
|
## Types for events
|
|
464
494
|
|
|
@@ -483,7 +513,12 @@ interface AppEvents {
|
|
|
483
513
|
via?: string;
|
|
484
514
|
};
|
|
485
515
|
"run.started": { conversationId: number; session: number };
|
|
486
|
-
"run.ended": {
|
|
516
|
+
"run.ended": {
|
|
517
|
+
conversationId: number;
|
|
518
|
+
session: number;
|
|
519
|
+
outcome: "done" | "failed" | "aborted";
|
|
520
|
+
failure?: string;
|
|
521
|
+
};
|
|
487
522
|
}
|
|
488
523
|
```
|
|
489
524
|
|
|
@@ -494,7 +529,7 @@ What each event's listener gets.
|
|
|
494
529
|
- `session.created`: a session in the list was made, by a person, a fork (`forkedFrom`), a linked start (`linkedFrom`), or a resend. `createdBy` is a person's id. Subagents are not sessions in the list, and send none.
|
|
495
530
|
- `session.renamed`, `session.archived`: its new title, or whether it is archived now.
|
|
496
531
|
- `message.sent`: a person's message to Pi, a steer or a queued one too. `by` is their id. `text` is the words as stored, with values that extensions hide already hidden and attachments left out. `via` names what sent it for them, such as PiP or a schedule.
|
|
497
|
-
- `run.started`, `run.ended`: Pi started or stopped working in a conversation. `conversationId` is that conversation, a session's or a subagent's; `session` is the session it belongs to.
|
|
532
|
+
- `run.started`, `run.ended`: Pi started or stopped working in a conversation. `conversationId` is that conversation, a session's or a subagent's; `session` is the session it belongs to. Since 0.28.0, `run.ended` also says how the run stopped: `outcome` is `done` when it finished, `failed` when it gave up, or `aborted` when it was stopped. `failure` is why it gave up, the same short line the session list shows, and only when `outcome` is `failed`. A session's failure stands until a later run starts.
|
|
498
533
|
|
|
499
534
|
### `AppEventName`
|
|
500
535
|
|
|
@@ -7,7 +7,7 @@ The rules for the names that a module gives. These are the names of its file, ex
|
|
|
7
7
|
To install an extension with the name of an installed extension replaces that extension. A tool with the name of another tool replaces it in all sessions. Thus Pi Pocket refuses a drop-in that would take a name that Pi Pocket keeps, or a name that another module has. Menu → Extensions says why.
|
|
8
8
|
|
|
9
9
|
- **Extension names that Pi Pocket keeps:** `coding-tools`, and all names that start with `pocket-`, such as `pocket-core`, `pocket-prompt`, and `pocket-guard`. This is true also when that built-in module is off.
|
|
10
|
-
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact
|
|
10
|
+
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact` (and `artifact_inline`, a name still kept: it was a tool until 0.28.0, and old sessions hold its calls), `browser`, `subagent`, `team`, `schedule`, `background`, `codemode`, `tool_search`, `memory`, `ask`, and `ask_someone`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`. Design's tools: `design_preview`, `design_export`, and `design_system`.
|
|
11
11
|
- **Names that another module has:** the first module to install an extension or tool keeps its name.
|
|
12
12
|
|
|
13
13
|
Give each extension and tool a name of your own, with a prefix: `example-clock`, `acme_lookup`. To change how a built-in tool works, do not replace it. Wrap it (`wrapTool` in Pi Durable's README), or check its calls with a hook.
|
|
@@ -307,6 +307,7 @@ interface ConversationWebRequest extends WebRequest {
|
|
|
307
307
|
readonly thinkingLevel: ModelThinkingLevel;
|
|
308
308
|
};
|
|
309
309
|
readonly linkedSessions: HumanLinkedSessions;
|
|
310
|
+
conversationUsage(conversationId?: ConversationId): Promise<ConversationUsage>;
|
|
310
311
|
}
|
|
311
312
|
```
|
|
312
313
|
|
|
@@ -314,6 +315,82 @@ Since 0.16.0 · Stable
|
|
|
314
315
|
|
|
315
316
|
Authoritative source metadata, plus request-lifetime human linked-session capabilities. An omitted `model` means the source has none. Metadata is a snapshot, not a promise that settings cannot change. A start rejects a source model, thinking level, or folder changed while it waits.
|
|
316
317
|
|
|
318
|
+
### `ConversationWebRequest.conversationUsage`
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
conversationUsage(conversationId?: ConversationId): Promise<ConversationUsage>;
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
Since 0.28.0 · Experimental
|
|
325
|
+
|
|
326
|
+
A server-side member of `ConversationWebRequest`, available only inside a `web.conversationRoute` handler. Without an id, it reads the bound source. An id can select another visible conversation, including a subagent. It returns committed usage only, with no entries, text, session ids, or write capability.
|
|
327
|
+
|
|
328
|
+
Use a GET conversation route with `access: "view"` for a status item:
|
|
329
|
+
|
|
330
|
+
```typescript
|
|
331
|
+
web.conversationRoute(
|
|
332
|
+
"GET",
|
|
333
|
+
"usage/:source",
|
|
334
|
+
async (request) => {
|
|
335
|
+
if (typeof request.conversationUsage !== "function") {
|
|
336
|
+
throw web.error(503, "Usage needs Pi Pocket 0.28.0 and a server restart.");
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
return request.conversationUsage();
|
|
340
|
+
},
|
|
341
|
+
{ conversation: "source", access: "view" },
|
|
342
|
+
);
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
The route checks its source and the signed-in person before the handler runs. The member checks them again when called and before returning. A target id requires visibility too. Missing conversations and PiP conversations are refused. Descendant sums and counts include only conversations the person can still see. A retained callback fails after the handler returns or the browser disconnects. There is no actor override. Do not broadcast the result to other people or keep it in a shared document: their visibility can differ.
|
|
346
|
+
|
|
347
|
+
This addition does not change route access: people invited to one session still cannot use extension web routes. Viewers with access to all sessions can read through a GET route; no steering, turn, or spend check applies to this read. A gallery entry that needs this member sets `minPocket` to `0.28.0`.
|
|
348
|
+
|
|
349
|
+
Each call reads usage documents and scans stored entries. It also reads the in-memory conversation tree. Cost grows with the stored history, including tool output, of the selected conversation and its descendants, not just their active context. Poll sparingly, not on each streamed token. The result is not an atomic snapshot: work can commit between the ledger and history reads or between conversations.
|
|
350
|
+
|
|
351
|
+
### `UsageTotals`
|
|
352
|
+
|
|
353
|
+
```ts
|
|
354
|
+
interface UsageTotals {
|
|
355
|
+
readonly requests: number;
|
|
356
|
+
readonly input: number;
|
|
357
|
+
readonly cacheRead: number;
|
|
358
|
+
readonly cacheWrite: number;
|
|
359
|
+
readonly output: number;
|
|
360
|
+
readonly reasoning?: number;
|
|
361
|
+
readonly cost: number;
|
|
362
|
+
readonly lastPrompt: number;
|
|
363
|
+
}
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Since 0.28.0 · Experimental
|
|
367
|
+
|
|
368
|
+
- `requests`: the number of stored assistant responses owned by this conversation, including error or aborted responses. Pi's own retry after an error stores a response of its own, so it counts. Requests with no assistant entry, such as compaction attempts and cache-keeper warm requests, are not counted.
|
|
369
|
+
- `input`: reported uncached input tokens, summed across requests.
|
|
370
|
+
- `cacheRead`: reported input tokens read from a prompt cache.
|
|
371
|
+
- `cacheWrite`: reported input tokens written to a prompt cache, including any 1-hour subset. That subset is not added twice.
|
|
372
|
+
- `output`: reported output tokens, including any separately reported reasoning tokens.
|
|
373
|
+
- `reasoning`: the sum of separately reported reasoning tokens. It is absent when none were reported, and can be 0 when a provider reports 0. Do not add it to `output`.
|
|
374
|
+
- `cost`: estimated US dollars from core's usage ledger, not a provider invoice. It includes model and tool usage, as core's spend does.
|
|
375
|
+
- `lastPrompt`: `input + cacheRead + cacheWrite` of the newest stored assistant response that reports any of them, by entry id: a failed request with no usage leaves the one before. It is 0 without such a response. It measures the last request, not the next request's context after a reset or compaction.
|
|
376
|
+
|
|
377
|
+
Token and cost totals come from core's `pi.usage` ledger. They include compaction and auxiliary requests recorded there, even when those requests have no response entry. Tool-reported usage counts too. A fork starts its own ledger; inherited responses do not count toward `requests` or `lastPrompt`. Old responses still count after a compaction or reset. A number that a provider does not report contributes 0; reasoning stays absent until one provider reports it. A conversation with no usage returns zeros and no reasoning field. Results are independent copies; changing a result changes no stored data. A call reads only the entries that came since the last call for the same conversation, so a module can ask often.
|
|
378
|
+
|
|
379
|
+
### `ConversationUsage`
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
interface ConversationUsage {
|
|
383
|
+
readonly own: UsageTotals;
|
|
384
|
+
readonly children: UsageTotals & { readonly count: number };
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
Since 0.28.0 · Experimental
|
|
389
|
+
|
|
390
|
+
`own` covers only the selected conversation. `children` sums every visible conversation it started, at any depth: subagents, linked sessions, and their descendants. It excludes the selected conversation, its ancestors, siblings, and forks. Archived descendants still count. Each conversation counts once, including one with no usage. `children.count` is their count, and `children.lastPrompt` is the sum of each descendant's `lastPrompt`, not the newest prompt across the family. No descendants gives zeros and count 0.
|
|
391
|
+
|
|
392
|
+
Requested by @Haichiu in #195.
|
|
393
|
+
|
|
317
394
|
### `HumanLinkedSessions`
|
|
318
395
|
|
|
319
396
|
```ts
|
|
@@ -12,14 +12,14 @@ if (typeof host.on !== "function" || typeof web.provide !== "function") {
|
|
|
12
12
|
|
|
13
13
|
`host.on(event, listener)` calls `listener` each time something happens in the app ([reference](reference/host.md#on)):
|
|
14
14
|
|
|
15
|
-
| Event | When
|
|
16
|
-
| ------------------ |
|
|
17
|
-
| `session.created` | A session is made: by a person, a fork, a linked start, or a resend.
|
|
18
|
-
| `session.renamed` | A session gets a new title.
|
|
19
|
-
| `session.archived` | A session is archived, or brought back.
|
|
20
|
-
| `message.sent` | A person sends Pi a message, a steer or a queued one too.
|
|
21
|
-
| `run.started` | Pi starts to work in a session or a subagent.
|
|
22
|
-
| `run.ended` | Pi stops.
|
|
15
|
+
| Event | When |
|
|
16
|
+
| ------------------ | ------------------------------------------------------------------------------------ |
|
|
17
|
+
| `session.created` | A session is made: by a person, a fork, a linked start, or a resend. |
|
|
18
|
+
| `session.renamed` | A session gets a new title. |
|
|
19
|
+
| `session.archived` | A session is archived, or brought back. |
|
|
20
|
+
| `message.sent` | A person sends Pi a message, a steer or a queued one too. |
|
|
21
|
+
| `run.started` | Pi starts to work in a session or a subagent. |
|
|
22
|
+
| `run.ended` | Pi stops: the run finished (`done`), gave up (`failed`), or was stopped (`aborted`). |
|
|
23
23
|
|
|
24
24
|
```typescript
|
|
25
25
|
web.onDispose(
|
package/docs/features.md
CHANGED
|
@@ -63,7 +63,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
63
63
|
- **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.
|
|
64
64
|
- **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`.
|
|
65
65
|
- **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.
|
|
66
|
-
- **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.
|
|
66
|
+
- **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.
|
|
67
67
|
- **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`.
|
|
68
68
|
- **Design.** On by default (Menu → **Extensions** turns it off). A canvas beside the chat for Pi's HTML designs: prototypes, screens, one-pagers, and slide decks. A design is an artifact, so versions, the sandbox, saved state, and share links work as they do for any artifact. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open` (with an artifact's id to open that one). On a wide screen the panel sits beside the chat; on a phone it covers the chat, and the way back keeps the canvas as it was. Since 0.26.0.
|
|
69
69
|
- **The canvas.** A picker of the session's HTML artifacts (newest first, variations together); the page in the artifact sandbox, at phone (390×844), tablet (820×1180), desktop (1280×800), or a custom size; fit or zoom, and a light, dark, or theme backdrop. A new design that Pi makes opens by itself, unless you are in a mode, have a draft, or it is a variation of the open design.
|
|
@@ -74,7 +74,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
74
74
|
- **Variations.** Artifacts of one group show as a grid of live thumbnails. **Use this one** puts a message about it in the message box.
|
|
75
75
|
- **Export and share.** PNG, PDF, PPTX (decks), and an HTML zip, from the menu. The file is written in the session's `exports/` folder and the browser downloads it. **Share a link** is the artifact viewer's Share. There is no Canva export.
|
|
76
76
|
- **What Pi does.** Its guide, `src/server/guides/design.md`, which Pi reads before it makes or changes a design (a short prompt section, only while the module is on, points to it), gives Pi an order of work, after Claude Design's (since 0.27.0): one round of questions when the work is new or unclear, then a start from what exists (the design system, the code, the screens) rather than a mock from scratch, a first version early, iterations, a check, and a short reply. A screen that exists is redesigned from itself: Pi reads its code and data first, makes version 1 the screen as it is today (in its place in the app, compared with a screenshot of the real one when it can get one), and then changes it in new versions, within what the code supports; a change that needs new data or server work is marked in the design and named in the reply, and a different direction becomes a new artifact in the same group. The product's own type sizes, spacing, and density win over the guide's craft defaults. It also gives Pi a page skeleton and craft rules: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs bound to the system's tokens, assets for images and fonts, variations as a group of 2 to 4 artifacts, a link to `ds/tokens.css` when the project has a design system, and a check with `design_preview` before it replies. When the project has a system, the prompt section carries a summary of it (roles and components first) as untrusted project data. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes, or the sizes asked for, and returns screenshots and a short report (see **Checks**); its options are `checks` (on by default), `tweaks`, `colorScheme`, `page` (another page of the bundle), and `actions` (hover, click, or focus on a selector before the screenshot). `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; it also takes `tweaks`, a custom `viewport`, and, for a deck's PNG, `slide` (a number, or `"all"` for a zip of every slide). A page's PDF is as wide as its viewport, and PPTX slide images have twice the pixels. `design_system` reads, scans, and changes the project's design system (see **The design system**). The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. Renders run 2 at once, and more wait their turn; each has 90 seconds.
|
|
77
|
-
- **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, breakpoints, and dark mode, from CSS custom properties and rules in CSS, SCSS, Less, and page style blocks, Sass and Less variables with literal values, Tailwind's `@theme` and a `tailwind.config` theme read as a literal, and DTCG, Style Dictionary, and Tokens Studio JSON files; a browser renders the project's pages to fill in what the files leave out), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
|
|
77
|
+
- **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, breakpoints, and dark mode, from CSS custom properties and rules in CSS, SCSS, Less, and page style blocks, Sass and Less variables with literal values, Tailwind's `@theme` and a `tailwind.config` theme read as a literal, and DTCG, Style Dictionary, and Tokens Studio JSON files; a browser renders the project's pages to fill in what the files leave out), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `resync` (bring a saved system up to date with code that changed: it adds the tokens the code now defines and the system lacks, keeps every token people wrote or changed, and lists the values that differ and the tokens that are no longer in the code (as not seen in this scan when the scan read only part of the project); without `apply` it only reports), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A resync records where its tokens came from in `$extensions["com.pi-pocket"].source` on `tokens.json`, so a system carries its own provenance. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
|
|
78
78
|
- **The System view.** The first row of the design picker (or `/design-open system`, or the launcher's "Open the design system") shows the system: **Colors** (role cards with contrast badges first, a live sample card, and the palette as ramp strips in a folded group), **Type**, **Spacing**, **Radii**, **Shadows** (each with its value), **Motion** (durations and easings that play), **Components** (every state, in a frame that runs nothing and loads nothing), and **Guidelines**. A section's count is its role tokens; the palette and component tokens show their own counts inside it. Modes show one at a time or side by side, and a mode's value says whether it is its own or inherited from the default. People who steer change a color, a size, a time, a weight, a font, an easing, or a shadow's layers in place, or link a token to another; the open design shows each change live when it uses the system's variables. The editor lists every contrast pair of a color (an exempt pair shows as exempt, not as a failure). **Undo** and **Redo** step through the changes, **Discard** gives them up, and **Save** writes the files and the generated CSS with no run of Pi (it refuses a change that the checks refuse, or one made on a system that changed meanwhile). The menu publishes the documentation page as a design, exports the generated files as a zip, and adds or removes a mode. People who only view see everything and change nothing. **Focus mode** hides the conversation for wide work. On a phone, the canvas fits the screen's width, and until a size is chosen it takes the size of its panel. The Design module loads only a small shell at app start; the workspace and the System view load when first opened.
|
|
79
79
|
- **Checks.** A design's **Check** tab and `design_preview` render the page on the server and judge only what the author's CSS sets, never the browser's defaults. They report values that are not the system's (colors, fonts, and sizes, each with the exact CSS edit and the nearest token of the matching role), contrast (WCAG 2.2 AA, judged only where the background is certain), non-text contrast of focus rings and icon buttons (3:1), tap targets (an error under 24 px, a warning under 44 px), sideways overflow, image alt text, heading order, a missing `lang`, form controls with no label (a placeholder is not a label), links, buttons, and widgets with no accessible name, no `main` landmark, fonts that did not load, a missing viewport tag, missing `data-pid`s, elements with no visible focus style, long motion with no `prefers-reduced-motion` rule, and author-set input text under 16 px on a phone. A check runs in any mode of the system. The tab follows the mode and size on the canvas, puts a pin on each element, and **Send to Pi** puts one message with every finding in the message box. **Fix N exact matches** rewrites literals that equal a token exactly to `var(--token)` and saves a new version with no run of Pi. On a phone, the tab starts as a bar with the counts, so the page keeps most of the screen.
|
|
80
80
|
- **The documentation page.** The System view's menu (and `design_system`) makes a documentation page of the system as a design: navigation, a filter of names and values, and links to every section; color roles with their values, contrast, and copy buttons for the CSS variable and the Tailwind class; the contrast pairs in every mode (exempt pairs labelled); palettes, type specimens, spacing, radii, shadows, and motion demos; component state grids with their code; guidelines; every token with a column for each mode; and a list of the generated files with how to use them. Component states are drawn in shadow roots after an allowlist sanitizer, under a nonce-only script policy, so they paint in screenshots and PDFs and run nothing. It runs in the artifact sandbox with no network, so it can be shared with a link or exported like any design.
|
|
@@ -125,7 +125,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
125
125
|
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (in the provider controls), 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.
|
|
126
126
|
- **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. 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.
|
|
127
127
|
- **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.
|
|
128
|
-
- **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_inline` call 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.
|
|
128
|
+
- **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.
|
|
129
129
|
- **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.
|
|
130
130
|
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, Tailscale, or Tailscale Serve. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
|
|
131
131
|
|