pi-pocket 0.28.0-beta.5 → 0.28.0-beta.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/SECURITY.md +1 -1
- package/docs/architecture.md +15 -1
- package/docs/customizing.md +2 -2
- package/docs/{desktop.md → embedders.md} +33 -28
- package/docs/examples/clock.ts +3 -5
- package/docs/examples/my-words.ts +2 -2
- package/docs/examples/quiet-note.ts +4 -4
- package/docs/examples/read-page.ts +4 -6
- package/docs/extensions/first-extension.md +2 -2
- package/docs/extensions/hooks.md +4 -0
- package/docs/extensions/linked-sessions.md +1 -1
- package/docs/extensions/policies/api-stability.md +1 -0
- package/docs/extensions/prompt-sections.md +4 -0
- package/docs/extensions/reference/api-versions.md +3 -0
- package/docs/extensions/reference/host.md +36 -1
- package/docs/extensions/reference/theme-surface.md +2 -1
- package/docs/extensions/sessions.md +37 -0
- package/docs/extensions/tools.md +3 -3
- package/docs/extensions.md +3 -2
- package/docs/features.md +14 -12
- package/docs/index.md +1 -1
- package/docs/map.md +18 -15
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +103 -58
- package/package.json +9 -7
- package/src/launcher/main.ts +25 -9
- package/src/launcher/serve.ts +19 -14
- package/src/server/alerts.ts +8 -8
- package/src/server/app.ts +98 -41
- package/src/server/background.ts +10 -2
- package/src/server/commands.ts +84 -7
- package/src/server/custom-providers.ts +721 -0
- package/src/server/design/index.ts +68 -61
- package/src/server/design/scan-fig-nodes.ts +13 -4
- package/src/server/design/scan-fig.ts +119 -47
- package/src/server/design/scan-infer.ts +8 -1
- package/src/server/design/scan-tree.ts +12 -1
- package/src/server/design/system.ts +77 -74
- package/src/server/entry-format.ts +5 -0
- package/src/server/extension-document-imports.ts +9 -1
- package/src/server/extension-pi-ai-compat.ts +22 -0
- package/src/server/extension-sessions.ts +238 -0
- package/src/server/extensions/agent-teams.ts +33 -27
- package/src/server/extensions/artifacts.ts +64 -66
- package/src/server/extensions/ask-someone.ts +13 -10
- package/src/server/extensions/ask.ts +34 -32
- package/src/server/extensions/background.ts +20 -18
- package/src/server/extensions/browser.ts +100 -92
- package/src/server/extensions/codemode.ts +107 -13
- package/src/server/extensions/memory.ts +19 -15
- package/src/server/extensions/pip.ts +162 -162
- package/src/server/extensions/plan.ts +3 -1
- package/src/server/extensions/prompt.ts +6 -6
- package/src/server/extensions/schedules.ts +21 -19
- package/src/server/extensions/subagents.ts +59 -31
- package/src/server/extensions/tool-search.ts +82 -29
- package/src/server/extensions/triggers.ts +14 -14
- package/src/server/host.ts +34 -0
- package/src/server/http/api.ts +44 -1
- package/src/server/http/events.ts +5 -1
- package/src/server/http/push-routes.ts +1 -1
- package/src/server/http.ts +6 -6
- package/src/server/linked-sessions.ts +28 -25
- package/src/server/model-refresh.ts +5 -5
- package/src/server/pi-sessions.ts +261 -51
- package/src/server/pip-compact.ts +11 -0
- package/src/server/pip.ts +5 -1
- package/src/server/projection.ts +11 -2
- package/src/server/providers.ts +62 -11
- package/src/server/push.ts +5 -5
- package/src/server/reload.ts +69 -5
- package/src/server/resend.ts +4 -1
- package/src/server/room.ts +103 -20
- package/src/server/running.ts +2 -2
- package/src/server/tool-schema.ts +20 -0
- package/types/pocket.d.ts +33 -0
- package/web/agent-tile.js +4 -1
- package/web/app.js +2 -2
- package/web/composer.js +14 -36
- package/web/diff.js +4 -3
- package/web/{desktop.js → embedder.js} +33 -20
- package/web/history.js +10 -12
- package/web/home.js +11 -0
- package/web/host.js +3 -3
- package/web/model-refresh.js +30 -20
- package/web/notify.js +5 -5
- package/web/person-storage.js +99 -0
- package/web/pip-attachments.js +5 -2
- package/web/pip.js +99 -27
- package/web/quote-reply.js +109 -21
- package/web/sheets/appearance.js +14 -0
- package/web/sheets/custom-providers.js +278 -0
- package/web/sheets/menu.js +6 -6
- package/web/sheets/model.js +1 -3
- package/web/sheets/providers.js +207 -21
- package/web/store.js +288 -40
- package/web/style.css +297 -22
- package/web/subagents-board.js +17 -2
- package/web/subagents.js +25 -1
- package/web/theme-surface.js +1 -0
- package/web/theme.js +2 -0
- package/web/transcript.js +16 -6
- package/web/ui.js +58 -0
- package/web/window-controls.js +3 -3
package/README.md
CHANGED
|
@@ -52,7 +52,7 @@ The launcher asks how your devices should connect, then prints a sign-in link an
|
|
|
52
52
|
|
|
53
53
|
While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
|
|
54
54
|
|
|
55
|
-
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0
|
|
55
|
+
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 and 0.28.0 upgrade the data one way, so going back needs the backup.
|
|
56
56
|
|
|
57
57
|
### Other ways to run it
|
|
58
58
|
|
package/SECURITY.md
CHANGED
|
@@ -13,7 +13,7 @@ Pi Pocket runs a coding agent that executes commands on the machine it runs on,
|
|
|
13
13
|
- **Anyone who can steer can do what you can.** Through Pi, they reach your files, Pi Pocket's settings and tokens, and its code. An invite to one session limits what someone sees in the app, not what Pi can reach. Neither do git worktrees or spend limits: a worktree keeps a session's files apart, and a run is stopped only after the request that crosses its limit.
|
|
14
14
|
- **Approvals.** Lancet Guard approvals can come from anyone who can steer, including the person who asked, unless the owner turns on "Approvals need someone else" (Menu → Extensions); then, when nobody is known to have asked, only the owner can allow. A notification offers Allow only for a call that fits on one short line; anything longer opens the app first. Since 0.22.0, an extension can ask a question on the same kind of card (a sign-in, a code): only the person Pi works for fills it in, what they type goes to that extension and never to Pi or the transcript, and its notification has no Allow. Values an extension hides show as `[label]` in command output, tool results, and messages to Pi; that keeps them out by accident, not from a command or a model that leaks them on purpose. A "Done when" check command runs after every answer without asking, so with Lancet Guard on it must be one the guard allows outright.
|
|
15
15
|
- **The built-in browser** reaches what this machine reaches: `localhost`, your network, and the internet. Anyone who can steer can use it from the Browser panel, and Pi from its `browser` tool; Lancet Guard does not check either, and pages can hold whatever they show. The addresses people open show in the session's chat. Its pages run in Chromium on the server, not in your browser, so they cannot reach the app or its cookies. Only the owner opens files from the address bar or sees which servers run on the machine. If steering guests should not reach your network, turn Browser off in Menu → Extensions.
|
|
16
|
-
- **Models** are a person's to choose. Pi starts subagents only on their session's model, or on models the owner allowed (Providers →
|
|
16
|
+
- **Models** are a person's to choose. Pi starts subagents only on their session's model, or on models the owner allowed (Providers → Subagent models); PiP passes a model only when its person named it; titles and summaries use the session's own model. Subagents on another model, and PiP, ask a model's sign-in afresh first and use none whose sign-in expired; a session's own run, a subagent on its model, titles, and summaries just try the model, and a run that fails on an expired sign-in marks it. This guards spending against Pi's choices, not against a person: anyone who can steer can pick a session's model, and Pi, which runs commands, can reach Pi's sign-ins and Pi Pocket's files like anything else on the machine.
|
|
17
17
|
- **Linked sessions** (Agent Teams, off until the owner turns it on) widen what prompt injection can reach. A session that read something hostile (a page, a file, an issue) can pass it on to the other sessions of its team in a message, and a message makes Pi work in the target for the person Pi worked for in the sender, with that person's access, in a session where other people may have written. Pi is told to take a linked session's message as a request, not as an order from a person, and to do nothing destructive or with credentials only because one asks; that is guidance to the model, not a boundary. A message is fenced, and a team stops at the starting session's spend limit. Since 0.19.0, no count of messages or sessions stops a team, so set a session budget for a session that starts one; a link gives no access to a session someone cannot already see.
|
|
18
18
|
- **Plan mode** keeps Pi to planning; it is not a boundary. Programs that people configured to run on their own, such as a git diff driver, run as they would for anyone.
|
|
19
19
|
- **Drop-in extensions** in `~/.pi-pocket/extensions/` run inside the server with the owner's rights. They stay off until the owner turns them on. One with a browser module also runs code in the app's own page, with the rights of whoever's tab loads it: the owner's alone unless the module opens it to others (never to someone invited to one session). The page's content security policy keeps that code from loading scripts and styles from another site or fetching from one, but code in the page could still send data out in other ways (navigating the page elsewhere, for one): turn on only browser modules you trust, as with the server part. What a module's route throws with `web.error` reaches everyone who may use that route as it is; anything else it throws, only the owner reads. Every file of a web type (`.js`, `.mjs`, `.css`, `.json`, images, and `.woff2` fonts) in a browser module's folder can be read by everyone the module is for. A module's conversation command is offered to everyone who can steer that session, people invited to only that session included, and its handler runs with the owner's rights: treat its arguments as untrusted, and check who runs it. A global command is the owner's alone.
|
package/docs/architecture.md
CHANGED
|
@@ -7,10 +7,12 @@ How Pi Pocket's parts depend on each other, and the orderings the code relies on
|
|
|
7
7
|
Pi Durable owns the lasting state of conversations: conversations, entries, tasks, and Pi Pocket's documents (`docs.ts`), in `pocket.sqlite`. People and settings, push subscriptions, uploads, and worktrees are files beside it ([map.md](map.md#data-pi-pocket-or-pi_pocket_dir)). What `PocketApp` keeps in memory about conversations is read back from storage:
|
|
8
8
|
|
|
9
9
|
- At startup, `#recover` reads each conversation's run, agent, chat, subagents, and who Pi works for in it.
|
|
10
|
-
- After that, every commit goes through `#committed`, which keeps the memory up to date.
|
|
10
|
+
- After that, every stored commit goes through `#committed`, which keeps the memory up to date.
|
|
11
11
|
|
|
12
12
|
Pi Durable 1.4.0 migrates SQLite storage to schema version 2 when it opens. Older Durable versions cannot open that database. Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.21.0.
|
|
13
13
|
|
|
14
|
+
Pi Durable 1.5.0 keeps schema version 2, but it stores `pi.live` at version 3, and its tool and generation tasks at newer versions, as soon as a conversation runs. An older Pi Pocket then does not start on that data folder: it stops with "Document … (pi.live) has newer version 3 than 1". Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.28.0, and do not go back to an older version with the same folder.
|
|
15
|
+
|
|
14
16
|
Scheduled messages, PR watches, repository watches, and PiP reports held while PiP is off use durable `sleepUntil()` checkpoints. A sleeping task holds no invocation and resumes at its saved phase when the harness clock reaches its deadline. The task graph includes these tasks with status `sleeping`.
|
|
15
17
|
|
|
16
18
|
Some state lives in this process alone, and a restart forgets it. For example:
|
|
@@ -55,6 +57,10 @@ Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose funct
|
|
|
55
57
|
|
|
56
58
|
`FolderFavoritesDoc` (`pocket.folder-favorites`) stores each person's ordered favorite working folders in SQLite. `folder-favorites.ts` reads and changes only the signed-in person's list; explicit star/unstar operations run inside one harness transaction, so concurrent devices do not overwrite unrelated changes. The commit coordinator sends each connected client only its person's list as a `folder-favorites` event. `hello.folderFavorites` supplies the initial list and refreshes it on reconnect. The folder picker shows only what the server committed, so a failed save leaves its list as it was.
|
|
57
59
|
|
|
60
|
+
## Ordinary sessions an extension starts
|
|
61
|
+
|
|
62
|
+
`ExtensionSessions` (`extension-sessions.ts`, `app.extensionSessions`, `host.sessions` as `SessionsApi`) starts a top-level session for the person Pi works for in the source, the same kind New session makes. It writes nothing to `linkedFrom`. The owner's list of models for subagents does not apply: a named model must be known and usable now, and a start that names none keeps the default a new session would get. The call's record is an item of `LinkedSessionCallsDoc` under its own token (`session:<source>:<key>`, hashed, apart from the tokens of linked sessions), kept and pruned by `recordOf`, and written in the commit that makes the session. A repeat reads the record first: it returns that session for the record's person, without the checks again. Its first message, when given, goes through `Commands.submit` as that person's own words (a `u:` request id), and a repeat finds that submission. A source past its spend limit, an invited person, a PiP source, and a blank message are refused before anything is made. A message to a session with no model is refused in the creation commit, which then makes nothing. Since 0.28.0, experimental.
|
|
63
|
+
|
|
58
64
|
## Linked sessions
|
|
59
65
|
|
|
60
66
|
`LinkedSessions` (`linked-sessions.ts`, `app.linkedSessions`, `host.linkedSessions` as `LinkedSessionsApi`) starts a session from another and carries messages between them; Agent Teams (`extensions/agent-teams.ts`, off by default) is its only user. A linked session is an ordinary ownerless session in the source's folder. Its session entry's `linkedFrom` names the session that started it, and nothing else follows from it: it is not in `SubagentsDoc`, `parentOf`, or `rootOf`, so it gives no access, and stopping or archiving one leaves the other as it was.
|
|
@@ -96,6 +102,8 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
|
|
|
96
102
|
- **PiP** passes a model, or names one in what it sends, only when its person named it in their own words (`pip.ts`, with `model-names.ts`): their own messages (`u:` request ids, from the authors document) since PiP's last new context (with those its last compaction kept), and the standing instructions of the watches and webhooks to PiP that they set up; never a watch PiP set up, what was posted, or what GitHub said.
|
|
97
103
|
- **Sign-ins:** `Providers` asks subscriptions' sign-ins afresh (the owner's Providers sheet, a model a subagent on another model or PiP is about to use, a run that failed on one, a run answered by a marked one) and keeps, in memory, the ones their provider refused to renew. Only subagents on another model (`resolveModel`, `modelProblem`), PiP, and linked sessions as they start (`Providers.problem`) check before use, and refuse their models. Everything else tries the model: a session's own run and a subagent on its session's model fail where people see them, and a run that failed on an expired sign-in marks it; a title that fails is only logged. `modelList` and `agentInfo` mark them, and the owner is told. A check that began before a sign-in or sign-out here marks nothing.
|
|
98
104
|
|
|
105
|
+
**OpenAI-compatible endpoints.** `app.customProviders` (`custom-providers.ts`) is the owner's only (`/api/custom-providers`, `requireOwner`). Changes run one after another. Each reads Pi's `models.json`, refuses to rewrite one that is not plain JSON or that Pi's own check (`ModelRuntime.create({ refreshOnCreate: false })`) refuses, writes the whole file at once (temporary file, rename, mode 600), then reloads only that provider (`models.refresh({ providers: [id], allowNetwork: false })`) and sends `models`. It manages only entries with `api: "openai-completions"`, a `baseUrl`, and an id that is not built in; it keeps fields it does not set. A key goes through `models.login(id, "api_key")` into `auth.json`, never into `models.json`; an endpoint without a key gets `apiKey: "none"`. Discovery reaches any address, a private one too, because only the owner can ask, and such servers are often local; its errors are fixed messages, never the fetch error, which can carry the key.
|
|
106
|
+
|
|
99
107
|
**Manual model refresh.** `Providers.modelRefresh` (`model-refresh.ts`) shares one in-flight refresh across owner tabs. `POST /api/models/refresh` requires the owner and the normal `X-Pocket` header; `hello.server.refreshModels` gates the UI against an older server. It checks local configuration with Pi’s public runtime API before reloading it, then refreshes each configured provider in parallel with a separate eight-second limit and `force: true` (network stays off under `PI_OFFLINE`). Each completed provider sends the existing `models` event and refreshes room views, so a slow provider does not hold back a healthy one. Pi owns cache publication and cancellation generations; failed catalog fetches keep its cached/static models. Refresh never configures a conversation or changes the default or subagent allow-list. Counts compare available provider/id keys before and after; provider errors are safe fixed messages, not raw exceptions that could contain credentials.
|
|
100
108
|
|
|
101
109
|
`PocketApp.modelList` resolves Pi’s `enabledModels` through the SDK’s `resolveModelScopeWithDiagnostics` against available models, then `modelList` marks scope membership alongside sign-in state. Both `hello` and providers’ `models` updates use that list. Manual refresh rereads Pi settings before recomputing the scope; malformed scope values are ignored so the picker still opens. The model picker’s Scoped / All state lasts only while it is open and filters the list without changing Pi’s settings, the session’s model, or its default. Empty scopes mean all available models, not a ban on picking models.
|
|
@@ -159,6 +167,8 @@ Pi Durable publishes each commit's changes in no set order. `#committed` handles
|
|
|
159
167
|
- Document changes go to `#documentCommitted`. It tracks busy and ended runs, agents, the session list, and the documents the rooms show (`ROOM_DOCS`).
|
|
160
168
|
- Submissions go to `attribution.submissionCommitted`.
|
|
161
169
|
|
|
170
|
+
It gets each commit once it is stored (`Harness.observeCommits`). Since Pi Durable 1.5, a partial answer and running tool output are stored later than they are shown: with the next commit that reads `pi.live` (the end of the answer, a tool that settles, the end of a run), and at the latest after `settings.progress.persistWithinMs` (1 second). A room's watch of its conversation's view (`Conversation.watch`) shows each at once. A crash loses up to about a second of a streamed answer. Pi Durable detaches an observer that throws, so `#committed` catches what one commit throws, and the app keeps hearing of the next ones.
|
|
171
|
+
|
|
162
172
|
Everything here is synchronous. A commit listener may not call the harness's session APIs, so a write it causes (noting a message's author, or moving a session up the list when Pi starts work there) runs in `setImmediate`. Keep this one coordinator: separate listeners would make their registration order a billing rule nobody can see.
|
|
163
173
|
|
|
164
174
|
Updates to tabs are coalesced:
|
|
@@ -175,6 +185,8 @@ The message Pi is writing goes as what changed since the tab's last update (`liv
|
|
|
175
185
|
|
|
176
186
|
A tab's connection names what its code understands (`p`, `PROTOCOL` in `web/store.js`). 2 keeps the queue when an update leaves it out; 3 takes the message as what changed; 4 takes a full view with only the newest entries; 5 takes them light at first; 6 names what it kept of the session and takes the order as what comes after it. A tab below 3 gets the whole message with each update, and one that names none (older code, as a tab asleep through an update keeps) also gets the queue with each update, because its code drops a queue that an update leaves out.
|
|
177
187
|
|
|
188
|
+
A room keeps the active context's entries itself. Since Pi Durable 1.5, a conversation's view holds only a window of the newest 50 to 100 entries of the whole history. The room reads the active context from `Conversation.context()` as it opens, after each new head marker (a compaction, a reset), and when the window no longer reaches the newest entry the room has. Between these reads, it adds the entries the window adds.
|
|
189
|
+
|
|
178
190
|
A full view for a tab of protocol 4 has the order of every entry in the active context, but only the entries of the newest 80 rows (`firstEntries` in `projection.ts`), with the turn the oldest of them is in, so the tab knows which groups are open there. The tab draws 60 of the rows, and the panel for PiP draws 80. Earlier entries come from `GET /api/c/<id>/context?before=<entry>`, with `rows=<n>` or `from=<entry>` (`Room.entriesBefore`, `loadEarlier` in `web/store.js`), when the person shows earlier messages, opens Find, or jumps to a message that is not loaded yet. The server marks the entries it left out as sent, so an update does not send them. A full view of the same session, as after a reconnect, keeps the entries the tab loaded. A session of 6,000 entries was one event of 8 to 10 MB: on a phone, the tab stopped for most of a second each time to read it, and only its last rows are drawn.
|
|
179
191
|
|
|
180
192
|
A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
|
|
@@ -183,6 +195,8 @@ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`:
|
|
|
183
195
|
|
|
184
196
|
The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
|
|
185
197
|
|
|
198
|
+
Browser drafts use `web/person-storage.js`: `pocket.person.<person>:…` keys, readable after `/api/me` or an event-stream hello identifies the person. An account signal invalidates answers already on their way, including at startup. Sign-out stops the device cache and attachments before the server request; after it finishes, it clears this storage, changes `pocket.person`, broadcasts the account change, and goes to `/`. Other tabs stop their cache on the early `pocket.signedOut` signal, but reload only on the completed account change. On Back, a cover checks `/api/me` before reconnecting; the same person keeps the document and drafts. Each check has a 10 s timeout; failures retry with backoff up to 30 s, or at once with Retry.
|
|
199
|
+
|
|
186
200
|
A tab whose server says it can (`hello.server.switches`) goes to another session on the connection it has: `POST /api/switch` with the connection id its `hello` carried, the session (`c`, none for the list), what it kept of it (`have`, as above), and a number (`seq`) that grows with each switch, so the server drops one that arrives after a newer one (`PocketApp.switchTo`). The server takes the tab out of the old session's room, answers `switched` with that number, and sends the new session as a new connection gets it (`#enter`): its view, chat, notes, and browser. A connection opened anew sent its person's profile, the session list, and PiP's state again, and its person left the app and came back in every other tab's list of who is here, and the session showed "connecting" until all of it came. Until `switched` comes, the tab drops events about a session (its view, chat, notes, people, browser, and missing): the server sent those of the session it left before it heard of the switch. A view or `missing` of another session than the one shown is dropped too. A switch the server cannot take (the connection closed, or the server started again) opens a new connection, which names the session, as before; a server without `switches` gets that too.
|
|
187
201
|
|
|
188
202
|
The session list goes to a tab only when it differs from the one that tab last got (`Client.sessionsSent`): it is large, and it is worked out again for many changes that leave it as it was.
|
package/docs/customizing.md
CHANGED
|
@@ -65,7 +65,7 @@ Use a template for a message that people send often. Use a skill for steps that
|
|
|
65
65
|
|
|
66
66
|
## Models and providers
|
|
67
67
|
|
|
68
|
-
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
|
|
68
|
+
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 an OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, a proxy), the owner taps **Add** on the **OpenAI Compatible** row in Providers: a name, a base URL, an API key (or **No key**), and models picked from the endpoint's list (**Find models**) or typed by hand. Pi Pocket writes the endpoint into Pi's `models.json`, which it makes, with its folder, when missing, and keeps the key in `auth.json`. **Edit** and **Remove** change it later. A `models.json` with comments, or one Pi refuses, is left alone. To add another model or provider that Pi does not know, or the fields the form does not set (headers, compat, costs), add it to `models.json` as Pi's `models.md` says; the form keeps those fields when it edits the endpoint. 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).
|
|
69
69
|
|
|
70
70
|
**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.
|
|
71
71
|
|
|
@@ -80,7 +80,7 @@ People sign in to providers in Menu → **Providers**, and pick a model for each
|
|
|
80
80
|
|
|
81
81
|
Models are the person's choice, never Pi's:
|
|
82
82
|
|
|
83
|
-
- A subagent runs on its session's model, unless the owner allows models under **
|
|
83
|
+
- A subagent runs on its session's model, unless the owner allows models under **Subagent models** in the Providers sheet (a pane on the right on wide screens, at the top on phones). By default, there are none. Once some are allowed, subagents and linked sessions run only on those: on the session's model when it is one of them and Pi names none, else on a model Pi chooses from them (Pi must name one when the session's is not among them).
|
|
84
84
|
- PiP gives a model only when its person named it.
|
|
85
85
|
|
|
86
86
|
Instructions, skills, and `AGENTS.md` cannot change this. Tell the person where the setting is instead.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Embedders
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An **embedder** is an app that shows Pi Pocket's web app inside itself: an Electron or Tauri wrapper on a computer, for example, or a phone app with a web view, with notifications, a badge, or a menu of its own. [Pi Pocket GUI](https://github.com/vitalNohj/pi-pocket-gui) is one. Pi Pocket stays a web app on its server; the embedder loads the server's address, and the person signs in there as in a browser.
|
|
4
4
|
|
|
5
|
-
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **
|
|
5
|
+
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **app bridge** joins the two: the embedder puts `window.pocketHost` in the page, and Pi Pocket uses what it offers. Pi Pocket knows nothing else about the embedder: not its name, not what kind of app it is, not what it runs on. In a browser there is no app bridge, and nothing changes.
|
|
6
6
|
|
|
7
7
|
## Finding Pi Pocket
|
|
8
8
|
|
|
@@ -12,46 +12,51 @@ A browser tab cannot do some things that such an app can, and Web Push does not
|
|
|
12
12
|
{ "name": "pi-pocket", "bridge": 1 }
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
`bridge` is the version of the
|
|
15
|
+
`bridge` is the version of the app bridge that this server's web app speaks. The answer never has Pi Pocket's version. A server older than the app bridge answers 401 there; its web app manifest (`/manifest.webmanifest`) still has `"name": "Pi Pocket"`.
|
|
16
16
|
|
|
17
|
-
## The bridge
|
|
17
|
+
## The app bridge
|
|
18
18
|
|
|
19
|
-
The app
|
|
19
|
+
The app bridge is experimental (since 0.28.0): it can change in a minor release ([API stability](extensions/policies/api-stability.md)). Before 0.28.0-beta.7 these docs were `docs/desktop.md`.
|
|
20
|
+
|
|
21
|
+
The embedder (in Electron, its preload script) puts one object in the top page of the server's origin, and nowhere else: never in a frame (artifacts run in frames), never on another origin.
|
|
20
22
|
|
|
21
23
|
```js
|
|
22
24
|
window.pocketHost = {
|
|
23
|
-
kind: "
|
|
25
|
+
kind: "my-app", // which embedder; for logs only
|
|
24
26
|
apiVersion: 1,
|
|
25
27
|
capabilities: ["menu", "badge", "notify", "visibility", "pinned", "open"],
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
menuTitle(), // the heading of the embedder's group in the menu, such as its name; optional
|
|
30
|
+
menuItems(), // [{ id, label, hint? }]: the items of that group, at the menu's end
|
|
28
31
|
invoke(id), // one of them was chosen; false when it could not be done
|
|
29
32
|
setBadge(count), // sessions that need you, as the home-screen icon counts them
|
|
30
|
-
notify(message), // a notification for the
|
|
31
|
-
visible(), // whether the
|
|
33
|
+
notify(message), // a notification for the embedder to show (below)
|
|
34
|
+
visible(), // whether the embedder's window shows: false while hidden in a tray or minimized
|
|
32
35
|
setPinned(list), // [{ id, title, state, label, url }]: the pinned sessions, in order
|
|
33
|
-
subscribe(listener), // the
|
|
36
|
+
subscribe(listener), // the embedder's events (below)
|
|
34
37
|
};
|
|
35
38
|
```
|
|
36
39
|
|
|
37
|
-
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the
|
|
40
|
+
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the embedder throws. `web/embedder.js` does the rest. Pi Pocket uses only the capabilities the embedder names, and ignores ones it does not know. A newer app bridge keeps version 1's calls.
|
|
38
41
|
|
|
39
42
|
### Capabilities
|
|
40
43
|
|
|
41
|
-
| Capability | What Pi Pocket does
|
|
42
|
-
| ------------ |
|
|
43
|
-
| `menu` | Shows `menuItems()` in a
|
|
44
|
-
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes.
|
|
45
|
-
| `notify` | Opens its event stream with `
|
|
46
|
-
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab.
|
|
47
|
-
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these bridge names. `label` says it in words. |
|
|
48
|
-
| `open` | Opens what the
|
|
44
|
+
| Capability | What Pi Pocket does |
|
|
45
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
46
|
+
| `menu` | Shows `menuItems()` in a group of their own at the end of the menu, below its App part, under `menuTitle()` (up to 40 characters); without a title, the group has no heading. Choosing one calls `invoke(id)`. Pi Pocket GUI offers **GUI Settings…** under its name. |
|
|
47
|
+
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes. |
|
|
48
|
+
| `notify` | Opens its event stream with `embedder=notify`. The server then sends this connection every notification it would push to the person (`embedder-notify`), and the page passes each to `notify(message)`. |
|
|
49
|
+
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab. |
|
|
50
|
+
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these app bridge names. `label` says it in words. |
|
|
51
|
+
| `open` | Opens what the embedder asks for (an `open` event), also without `notify`. |
|
|
52
|
+
|
|
53
|
+
A page from before 0.28.0-beta.7, still open after the server updates, asks with `host=notify` and listens for `desktop-notify`: the server still sends it those, until the page reloads.
|
|
49
54
|
|
|
50
55
|
A page in an Electron window keeps running at full speed while the window hides in the tray, so `document.visibilityState` stays `visible` there. That is why `visible()` exists: without it, the server would think the person is looking, and hold every notification back.
|
|
51
56
|
|
|
52
57
|
### Notifications
|
|
53
58
|
|
|
54
|
-
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their
|
|
59
|
+
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their embedders' connections (`PocketApp.notifyEmbedders`). An embedder that is not running gets nothing: nothing waits for it.
|
|
55
60
|
|
|
56
61
|
```js
|
|
57
62
|
{
|
|
@@ -69,11 +74,11 @@ The server decides as for Web Push (`alerts.ts`): who can see the session, the k
|
|
|
69
74
|
}
|
|
70
75
|
```
|
|
71
76
|
|
|
72
|
-
The
|
|
77
|
+
The embedder chooses how much of an approval to show and whether to offer **Allow**, from `may`, `allow`, and `call`. It always offers **Deny**. The server checks again, when the answer comes, that the person may give it.
|
|
73
78
|
|
|
74
|
-
### The
|
|
79
|
+
### The embedder's events
|
|
75
80
|
|
|
76
|
-
`subscribe(listener)` takes one function. The
|
|
81
|
+
`subscribe(listener)` takes one function. The embedder calls it with:
|
|
77
82
|
|
|
78
83
|
- `{ type: "visibility" }`: its window was shown or hidden. The page reads `visible()` again.
|
|
79
84
|
- `{ type: "open", url }`: open this, such as a notification or a tray item that was clicked. Only addresses of the server's own origin open.
|
|
@@ -81,7 +86,7 @@ The app chooses how much of an approval to show and whether to offer **Allow**,
|
|
|
81
86
|
|
|
82
87
|
## The window's buttons
|
|
83
88
|
|
|
84
|
-
An
|
|
89
|
+
An embedder that hides its title bar, and shows Pi Pocket up to its window's top edge with the window's own buttons over it (close, minimize, zoom), tells the page where they are through the web's standard for it, the Window Controls Overlay (`navigator.windowControlsOverlay`). An installed web app with `"display_override": ["window-controls-overlay"]` does the same. The app bridge is not needed for it.
|
|
85
90
|
|
|
86
91
|
`web/window-controls.js` makes room only under the buttons, and only as much as they take; the rest of the layout keeps its whole height:
|
|
87
92
|
|
|
@@ -92,14 +97,14 @@ An app that hides its title bar, and shows Pi Pocket up to its window's top edge
|
|
|
92
97
|
|
|
93
98
|
The page reads the layout, not the screen: a window, a bar, or a panel that opens (the subagents board, Design, Files, Browser, People) has its room and its cut before the frame that first shows it, and a window that pops in is measured where it lands. Nothing shows under the buttons first and moves after.
|
|
94
99
|
|
|
95
|
-
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an
|
|
100
|
+
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an embedder can tell that it makes its own room. For a page without it (an older Pi Pocket, a sign-in page), Pi Pocket GUI instead sets a top safe-area inset as tall as the buttons, which Pi Pocket's bars have long kept clear of on phones.
|
|
96
101
|
|
|
97
102
|
## Security
|
|
98
103
|
|
|
99
|
-
The bridge is only as safe as the
|
|
104
|
+
The app bridge is only as safe as the embedder that offers it. An embedder must:
|
|
100
105
|
|
|
101
106
|
- put it only in the top frame of the server's origin, and take it away when that frame goes elsewhere;
|
|
102
107
|
- check, in its main process, the frame and origin of every call that comes from the page: the sender frame's own origin (`senderFrame.origin`), not its `url`, because the server's origin also serves sandboxed artifact pages, whose origin is opaque;
|
|
103
108
|
- give the page no Node.js, and keep its sandbox and context isolation on.
|
|
104
109
|
|
|
105
|
-
Pi Pocket gives the bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the
|
|
110
|
+
Pi Pocket gives the app bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the page.
|
package/docs/examples/clock.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A clock tool, and a /clock-zone command that sets the time zone it uses in a session. An example drop-in extension:
|
|
3
3
|
* copy it into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, opt, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -22,10 +22,8 @@ const clock = defineTool({
|
|
|
22
22
|
name: "clock",
|
|
23
23
|
description:
|
|
24
24
|
"The date and time now, in a time zone such as Europe/Berlin (by default, the session's or the server's).",
|
|
25
|
-
parameters:
|
|
26
|
-
zone:
|
|
27
|
-
Type.String({ description: "An IANA time zone, such as America/Chicago" }),
|
|
28
|
-
),
|
|
25
|
+
parameters: obj({
|
|
26
|
+
zone: opt(str({ description: "An IANA time zone, such as America/Chicago" })),
|
|
29
27
|
}),
|
|
30
28
|
// It only reads the clock: running it again after a restart cut it off is harmless.
|
|
31
29
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Web } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -13,7 +13,7 @@ function countWords(text: string): number {
|
|
|
13
13
|
const wordCount = defineTool({
|
|
14
14
|
name: "my_word_count",
|
|
15
15
|
description: "Count the words in a text.",
|
|
16
|
-
parameters:
|
|
16
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
17
17
|
replay: "safe",
|
|
18
18
|
execute: async (args) => ({
|
|
19
19
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A note the transcript can fold: one line in the app, and the whole message for the model.
|
|
3
3
|
* An example drop-in: copy it and `quiet-note.js` into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -14,9 +14,9 @@ const leaveNote = defineTool({
|
|
|
14
14
|
name: "quiet_note",
|
|
15
15
|
description:
|
|
16
16
|
"Leave a note in this session. The app may show one line; you still read the whole note.",
|
|
17
|
-
parameters:
|
|
18
|
-
text:
|
|
19
|
-
summary:
|
|
17
|
+
parameters: obj({
|
|
18
|
+
text: str({ description: "The whole note" }),
|
|
19
|
+
summary: str({ description: "A few words for the one line" }),
|
|
20
20
|
}),
|
|
21
21
|
// The request id is this call's, so a replay finds the note instead of leaving another.
|
|
22
22
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Reads a public web page for Pi: a read_page tool that fetches only public addresses and fences the page's text.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { num, obj, opt, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Host } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -30,11 +30,9 @@ export default function createReadPage(host: Host) {
|
|
|
30
30
|
const readPage = defineTool({
|
|
31
31
|
name: "read_page",
|
|
32
32
|
description: "Read the text of a public web page (http or https).",
|
|
33
|
-
parameters:
|
|
34
|
-
url:
|
|
35
|
-
maxChars:
|
|
36
|
-
Type.Number({ description: "The text to give at most (default 20000)" }),
|
|
37
|
-
),
|
|
33
|
+
parameters: obj({
|
|
34
|
+
url: str({ description: "The page's address" }),
|
|
35
|
+
maxChars: opt(num({ description: "The text to give at most (default 20000)" })),
|
|
38
36
|
}),
|
|
39
37
|
replay: "safe",
|
|
40
38
|
execute: async (args) => {
|
|
@@ -18,7 +18,7 @@ In the drop-in folder, make the file `my-words.ts` with this text:
|
|
|
18
18
|
/**
|
|
19
19
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
20
20
|
*/
|
|
21
|
-
import {
|
|
21
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
22
22
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
23
23
|
import type { Web } from "./_pocket.d.ts";
|
|
24
24
|
|
|
@@ -30,7 +30,7 @@ function countWords(text: string): number {
|
|
|
30
30
|
const wordCount = defineTool({
|
|
31
31
|
name: "my_word_count",
|
|
32
32
|
description: "Count the words in a text.",
|
|
33
|
-
parameters:
|
|
33
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
34
34
|
replay: "safe",
|
|
35
35
|
execute: async (args) => ({
|
|
36
36
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
package/docs/extensions/hooks.md
CHANGED
|
@@ -36,6 +36,10 @@ There are two kinds of hooks:
|
|
|
36
36
|
|
|
37
37
|
The calls of codemode scripts also go through `beforeTool`.
|
|
38
38
|
|
|
39
|
+
## Read a result
|
|
40
|
+
|
|
41
|
+
`afterTool(call, result, api, context)` gets each result before it is stored, and can return a changed one. Since Pi 1.5 (Pi Pocket 0.28.0), it also gets the error results that Pi Durable writes itself: for a tool that is not there, invalid arguments, a block, an interruption, and an abort. Their `result.diagnostics` say which, with a `code` such as `invalid_arguments` or `blocked`. A hook that reads `call.arguments` or `structuredOutput` checks `result.diagnostics` first. In the calls of codemode scripts, `api.entry` and `api.entries` reject.
|
|
42
|
+
|
|
39
43
|
## Send Pi on
|
|
40
44
|
|
|
41
45
|
`onYield(answer, api, context)` runs after Pi's last answer. To send Pi on with another message, return `{ continue: "the message" }`. Done when does this ([goals.ts](../../src/server/extensions/goals.ts)).
|
|
@@ -18,7 +18,7 @@ A linked session is an ordinary session. The session list shows it under the ses
|
|
|
18
18
|
|
|
19
19
|
- `cwd` selects an existing working folder using the same path rules as the folder picker (including `~`). Prefer an absolute path. A blank `cwd` counts as no `cwd`. A relative `cwd` resolves against the folder of the server process, not the folder of the source. The child loads that folder's project context and tools; the source stays in its own folder. A missing path or a file is rejected before a session is created. Since 0.19.0: an older Pi Pocket ignores `cwd` and uses the source's folder, so a gallery entry that needs it sets `minPocket` to `0.19.0`.
|
|
20
20
|
- Without `title`, the title is the first line of the message.
|
|
21
|
-
- `model` is `provider/modelId`. While the owner's list (Menu → Providers →
|
|
21
|
+
- `model` is `provider/modelId`. While the owner's list (Menu → Providers → Subagent models) is empty, it must be the source's model. Once the list has models, it must be one of them, and the source's own model counts only when it is listed. Without `model`, the session uses the source's model if the list is empty or has it. If the list does not have it, the call is refused with an error that names the allowed models: the caller must choose one (the error is a 400 for a human route).
|
|
22
22
|
- `send` refuses a session that runs on a model off the list (a person changed it, or the owner changed the list), when the list is not empty. A message from a linked session to the session that started it is a reply, not work: it goes whatever model that session runs on.
|
|
23
23
|
- `thinking` can be any level, also one above the source's. Without it, the session uses the source's level. Pi Pocket lowers it to the highest level that the model has, or uses the lowest level of the model when it has none that low.
|
|
24
24
|
- When a model cannot be used now, Pi Pocket refuses the call before it makes anything.
|
|
@@ -48,6 +48,7 @@ These members are public:
|
|
|
48
48
|
- `skillPaths()`, `skills(cwd)`
|
|
49
49
|
- `heldBack(conversationId)`, `onLimitsChanged(listener)`
|
|
50
50
|
- `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental)); `stop`, `archive` (experimental, since 0.28.0)
|
|
51
|
+
- `sessions.start` (experimental, since 0.28.0: [Starting an ordinary session](../sessions.md))
|
|
51
52
|
- `text`: `quoted`, `defang`
|
|
52
53
|
- `thinkingLevels`
|
|
53
54
|
- `fetchPublic(url, init)` (experimental, since 0.20.0)
|
|
@@ -28,6 +28,10 @@ Sections render before each request. Pi Pocket sends again only the sections tha
|
|
|
28
28
|
- Put the date in a section, not the time.
|
|
29
29
|
- Do not put counters in a section.
|
|
30
30
|
|
|
31
|
+
## A section for one tool
|
|
32
|
+
|
|
33
|
+
A section about a tool shows while `input.agent.tools` has the tool. In codemode's Only mode, scripts alone call most tools, so also show it when `input.agent.callable` has the tool with `callers` that leave out `"model"`, as `browser.ts` does.
|
|
34
|
+
|
|
31
35
|
## A section for one session
|
|
32
36
|
|
|
33
37
|
`input.conversationId` is the session. `input.read.snapshot(Doc, input.conversationId, context)` reads a document of that session. Use them to write a section that depends on the session.
|
|
@@ -14,6 +14,8 @@ The version goes up only when a change breaks something that modules use. Additi
|
|
|
14
14
|
|
|
15
15
|
Since 0.21.0, document definitions should name `checkpointWhen` in every `defineDoc` or `defineDocFamily` call. When it is missing, Pi Pocket supplies `checkpointWhen: () => false` for older drop-ins, and logs the module and the document kind. Explicit policies stay as they are. Since 0.21.0 (Pi Durable 1.4), a task must not use `TaskRuntime.sleep()`: it must wait with durable `sleepUntil()` checkpoints.
|
|
16
16
|
|
|
17
|
+
Since 0.28.0 (Pi 1.5), the main entry of `@earendil-works/pi-ai` does not export TypeBox's `Type`. A drop-in that imports `Type` from it still gets it: Pi Pocket gives drop-ins pi-ai with TypeBox's `Type` added, so their tool schemas stay as they were. New code builds its schemas with `@earendil-works/pi-schema` ([Tools](../tools.md#define-a-tool)). Since then, a watch listener (`api.watchDoc`) gets one call: `watch.start(async (call, context) => …)`, with `call.value`, `call.ops`, and `call.retired` when `call.kind` is `"value"`. A document that is retired does not end its watch with a `null` value any more: the next call has `retired: true`.
|
|
18
|
+
|
|
17
19
|
## `pocketApi`
|
|
18
20
|
|
|
19
21
|
A module can export `pocketApi`: the server module, the browser module, or both.
|
|
@@ -91,3 +93,4 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
91
93
|
| Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
|
|
92
94
|
| Read-only conversation and descendant usage: `ConversationWebRequest.conversationUsage` (experimental) | 0.28.0 |
|
|
93
95
|
| How a run stopped: `outcome` and `failure` on `run.ended`, and `failed` on a linked session (experimental) | 0.28.0 |
|
|
96
|
+
| `host.sessions.start` (experimental) | 0.28.0 |
|
|
@@ -108,7 +108,7 @@ subagentModels(): readonly string[];
|
|
|
108
108
|
|
|
109
109
|
Since 0.13.1 · Stable
|
|
110
110
|
|
|
111
|
-
The models that the owner lets subagents use, as `provider/modelId`. While the list is empty (the default), a subagent runs on the model of its own session. Once it has models, subagents and linked sessions run only on those: the model of the session when it is listed and none is named; when it is not listed, the caller must name a listed model. The owner sets it in Menu → Providers →
|
|
111
|
+
The models that the owner lets subagents use, as `provider/modelId`. While the list is empty (the default), a subagent runs on the model of its own session. Once it has models, subagents and linked sessions run only on those: the model of the session when it is listed and none is named; when it is not listed, the caller must name a listed model. The owner sets it in Menu → Providers → Subagent models.
|
|
112
112
|
|
|
113
113
|
### `modelProblem`
|
|
114
114
|
|
|
@@ -403,6 +403,41 @@ What `fetchPublic` takes besides the address.
|
|
|
403
403
|
- `maxBytes`: the size of the body at most, after it is decoded.
|
|
404
404
|
- `timeoutMs`: the time for the whole request at most, the body included.
|
|
405
405
|
|
|
406
|
+
## Ordinary sessions
|
|
407
|
+
|
|
408
|
+
### `sessions`
|
|
409
|
+
|
|
410
|
+
```ts
|
|
411
|
+
readonly sessions: Sessions;
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
Since 0.28.0 · Experimental
|
|
415
|
+
|
|
416
|
+
Lets an extension start an ordinary session, the same kind a person gets from New session. [Starting an ordinary session](../sessions.md) tells you who it acts for, what it checks, and what the new session is.
|
|
417
|
+
|
|
418
|
+
The call acts as the person that Pi works for in `source`, and that person's checks apply. Give it a `key` that stays the same when the call runs again. A second call with the same `key` returns the session the first call made, and sends its message once. It acts for the person of the first call, and it does not check the model, the folder, or the spend limit again. A `key` of `linkedSessions.start` never finds a session of this API.
|
|
419
|
+
|
|
420
|
+
#### `sessions.start`
|
|
421
|
+
|
|
422
|
+
```ts
|
|
423
|
+
start(
|
|
424
|
+
source: ConversationId,
|
|
425
|
+
request: { title?: string; cwd?: string; model?: string; thinking?: string; message?: string },
|
|
426
|
+
key: string,
|
|
427
|
+
): Promise<{ session: ConversationId }>;
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Since 0.28.0 · Experimental
|
|
431
|
+
|
|
432
|
+
Makes a top-level session and, when `message` is given, sends that text as its first message. It returns the new session's id.
|
|
433
|
+
|
|
434
|
+
- The new session works in `cwd` when supplied, otherwise the server's default folder. `cwd` must name an existing folder and uses the normal folder-picker path rules. A missing folder is refused before a session is made.
|
|
435
|
+
- `model` is `provider/modelId`. It must be a model known here whose provider can be used now. Without it, the session starts on the model a new session would get. The owner's list of models for subagents does not apply.
|
|
436
|
+
- `thinking` is any level. Pi Pocket lowers it to the highest level the model has, or uses the model's lowest when it has none that low. Without it, the session keeps the thinking level it started with.
|
|
437
|
+
- The new session has no `linkedFrom`. It is its own row in the session list, and it can start linked sessions of its own.
|
|
438
|
+
- A source past its spend limit, a person invited to one session, and a PiP source are refused, and nothing is made.
|
|
439
|
+
- A blank `message` is refused, and nothing is made. A `message` is also refused when the session gets no model: no `model` and no default model.
|
|
440
|
+
|
|
406
441
|
## Linked sessions
|
|
407
442
|
|
|
408
443
|
### `linkedSessions`
|
|
@@ -128,6 +128,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
128
128
|
| `home` | The home screen on wide screens |
|
|
129
129
|
| `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
|
|
130
130
|
| `home-actions` | Its buttons |
|
|
131
|
+
| `home-menu` | Its menu button, top right: the menu without a session's items |
|
|
131
132
|
| `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
|
|
132
133
|
| `home-list` | The session list as a phone's home screen |
|
|
133
134
|
| `pane` | The conversation's window (or the subagents board, or an extension's page) |
|
|
@@ -190,7 +191,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
190
191
|
| `sheet-head`, `sheet-body` | Its title bar, and what it holds |
|
|
191
192
|
| `menu` | The menu, on wide screens (it is the sheet `menu` on phones) |
|
|
192
193
|
| `session-menu` | The right-click menu on a session row (since 0.27.0) |
|
|
193
|
-
| `quote-reply-button` | The
|
|
194
|
+
| `quote-reply-button` | The pill that shows over selected text, with Reply and (with PiP on) Ask PiP (since 0.27.0) |
|
|
194
195
|
| `launcher` | The launcher (Ctrl/⌘+K) |
|
|
195
196
|
| `launcher-input`, `launcher-filters` | Its search field, and the search types under it |
|
|
196
197
|
| `launcher-group`, `launcher-row` | A group's heading, and each result |
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Starting an ordinary session
|
|
2
|
+
|
|
3
|
+
An extension can start an ordinary session, the same kind a person gets from New session. Use `host.sessions.start`. Its shape is in [the host reference](reference/host.md).
|
|
4
|
+
|
|
5
|
+
**Experimental, since 0.28.0.** It can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)). A module for an older server checks that `host.sessions` is there, and a gallery entry that needs it sets `minPocket` to `0.28.0`.
|
|
6
|
+
|
|
7
|
+
## What the call does
|
|
8
|
+
|
|
9
|
+
`start(source, { title?, cwd?, model?, thinking?, message? }, key)` makes a session and returns `{ session }`, its id.
|
|
10
|
+
|
|
11
|
+
- The session is top-level. It has no `linkedFrom`, and it shows as its own row in the session list. It can itself start linked sessions.
|
|
12
|
+
- It works in `cwd` when supplied, otherwise the server's default folder. `cwd` uses the same path rules as the folder picker, including `~`. A missing path or a file is rejected before a session is created.
|
|
13
|
+
- Without `title`, the title is the folder's name, as for New session.
|
|
14
|
+
- `model` is `provider/modelId`. It must be a model known here, and its provider must be usable now. Without `model`, the session starts on the model a new session would get. The owner's list of models for subagents does not apply: this is an ordinary session, not a subagent and not a linked session.
|
|
15
|
+
- `thinking` is any level. Pi Pocket lowers it to the highest level the model has, or uses the model's lowest when it has none that low, as it does for a linked session. This is the named model, or the default model when `model` is not given. Without `thinking`, the session keeps the thinking level it started with.
|
|
16
|
+
- With `message`, that text is the session's first message. It is an ordinary message from the person Pi works for in `source`, not a message sent for them.
|
|
17
|
+
|
|
18
|
+
## Who it acts for
|
|
19
|
+
|
|
20
|
+
The call acts for the person Pi works for in `source`. That person must be able to see the source, steer, and start sessions.
|
|
21
|
+
|
|
22
|
+
Pi Pocket refuses the call, and makes nothing, when:
|
|
23
|
+
|
|
24
|
+
- nobody is the person Pi works for in the source, or that person cannot see the source;
|
|
25
|
+
- the source is a PiP conversation;
|
|
26
|
+
- that person was invited to one session;
|
|
27
|
+
- the source is past its spend limit;
|
|
28
|
+
- `model` is unknown, or its provider cannot be used now;
|
|
29
|
+
- `cwd` does not name an existing folder;
|
|
30
|
+
- `cwd` is a remote workspace, and that person is not the owner;
|
|
31
|
+
- `message` is blank, or the session gets no model to send it to (no `model` and no default model).
|
|
32
|
+
|
|
33
|
+
## Once
|
|
34
|
+
|
|
35
|
+
Give the call a `key` that stays the same when it runs again, such as `${api.taskId}:${api.callId}`. A second call with the same `key` from the same source returns the session the first call made. It acts for the person the first call acted for, also when someone else wrote in the source since then. It does not check the model, the folder, or the spend limit again: a source that has reached its spend limit since then still gets its session back. When `message` is given, it is sent once: the repeat finds the message the first call sent.
|
|
36
|
+
|
|
37
|
+
The keys of this call are apart from those of `linkedSessions.start`. The same `key` given to both starts two sessions, one of each kind.
|
package/docs/extensions/tools.md
CHANGED
|
@@ -10,7 +10,7 @@ Use `defineTool` from `@earendil-works/pi-durable`, and give the tool to your ex
|
|
|
10
10
|
const wordCount = defineTool({
|
|
11
11
|
name: "my_word_count",
|
|
12
12
|
description: "Count the words in a text.",
|
|
13
|
-
parameters:
|
|
13
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
14
14
|
replay: "safe",
|
|
15
15
|
execute: async (args) => ({
|
|
16
16
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -27,8 +27,8 @@ export default function createMyWords() {
|
|
|
27
27
|
|
|
28
28
|
- `name` must be different from the name of each other tool ([Names](reference/names.md)). Use a prefix of your own.
|
|
29
29
|
- `description` and `parameters` go to the model with each request. Keep them short and exact.
|
|
30
|
-
- `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at
|
|
31
|
-
- `parameters` is a
|
|
30
|
+
- `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at 11,000 characters (about 4,000 tokens) in a plain session.
|
|
31
|
+
- `parameters` is a JSON Schema object. Build it with the builders of `@earendil-works/pi-schema`: `obj`, `str`, `num`, `int`, `bool`, `arr`, `union`, and `opt` for a property that can be left out. `obj` makes a closed object (`additionalProperties: false`); `obj(properties, { open: true })` lets other properties through. Pi Durable checks the arguments against the schema before `execute` runs. Since Pi 1.5 (Pi Pocket 0.28.0), pi-schema does the check, and the model gets its messages, such as `- path: missing`. A drop-in written before can keep TypeBox's `Type` from `@earendil-works/pi-ai` ([API versions](reference/api-versions.md)).
|
|
32
32
|
- `execute(args, api, context)` does the work.
|
|
33
33
|
|
|
34
34
|
## Return a result
|