pi-pocket 0.28.0-beta.6 → 0.28.0-beta.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/docs/architecture.md +13 -4
- 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 +11 -3
- package/docs/extensions/reference/api-versions.md +2 -0
- package/docs/extensions/reference/host.md +3 -3
- package/docs/extensions/reference/limits.md +1 -0
- package/docs/extensions/reference/theme-surface.md +1 -1
- package/docs/extensions/tools.md +2 -2
- package/docs/extensions.md +2 -2
- package/docs/features.md +8 -7
- package/docs/index.md +1 -1
- package/docs/map.md +14 -13
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +103 -58
- package/package.json +9 -7
- package/src/launcher/main.ts +25 -9
- package/src/launcher/serve.ts +19 -14
- package/src/server/alerts.ts +8 -8
- package/src/server/app.ts +94 -43
- package/src/server/background.ts +10 -2
- package/src/server/commands.ts +58 -7
- package/src/server/custom-providers.ts +76 -16
- package/src/server/design/index.ts +68 -61
- package/src/server/design/scan-fig-nodes.ts +13 -4
- package/src/server/design/scan-fig.ts +119 -47
- package/src/server/design/scan-infer.ts +8 -1
- package/src/server/design/scan-tree.ts +12 -1
- package/src/server/design/system.ts +77 -74
- package/src/server/docs.ts +2 -1
- package/src/server/entry-format.ts +5 -0
- package/src/server/extension-document-imports.ts +9 -1
- package/src/server/extension-pi-ai-compat.ts +22 -0
- package/src/server/extensions/agent-teams.ts +47 -35
- package/src/server/extensions/artifacts.ts +53 -47
- package/src/server/extensions/ask-someone.ts +13 -10
- package/src/server/extensions/ask.ts +31 -24
- package/src/server/extensions/background.ts +20 -18
- package/src/server/extensions/browser.ts +92 -90
- package/src/server/extensions/codemode.ts +7 -3
- package/src/server/extensions/memory.ts +19 -15
- package/src/server/extensions/pip.ts +162 -162
- package/src/server/extensions/schedules.ts +20 -18
- package/src/server/extensions/subagents.ts +32 -24
- package/src/server/extensions/tool-search.ts +12 -9
- package/src/server/extensions/triggers.ts +14 -14
- package/src/server/host.ts +6 -2
- package/src/server/http/api.ts +14 -1
- package/src/server/http/events.ts +5 -1
- package/src/server/http/push-routes.ts +1 -1
- package/src/server/http.ts +6 -6
- package/src/server/linked-sessions.ts +155 -55
- package/src/server/pi-sessions.ts +261 -51
- package/src/server/pip-compact.ts +11 -0
- package/src/server/pip.ts +5 -1
- package/src/server/projection.ts +11 -2
- package/src/server/providers.ts +37 -0
- package/src/server/push.ts +5 -5
- package/src/server/reload.ts +69 -5
- package/src/server/resend.ts +4 -1
- package/src/server/room.ts +103 -20
- package/src/server/running.ts +2 -2
- package/src/server/tool-schema.ts +20 -0
- package/types/pocket.d.ts +5 -2
- package/web/agent-tile.js +4 -1
- package/web/app.js +2 -2
- package/web/composer.js +14 -36
- package/web/diff.js +4 -3
- package/web/{desktop.js → embedder.js} +33 -20
- package/web/history.js +10 -12
- package/web/host.js +3 -3
- package/web/notify.js +5 -5
- package/web/person-storage.js +99 -0
- package/web/pip-attachments.js +5 -2
- package/web/pip.js +99 -27
- package/web/quote-reply.js +109 -21
- package/web/sheets/appearance.js +14 -0
- package/web/sheets/menu.js +6 -6
- package/web/store.js +288 -40
- package/web/style.css +129 -14
- package/web/subagents-board.js +17 -2
- package/web/subagents.js +25 -1
- package/web/theme.js +2 -0
- package/web/transcript.js +16 -6
- package/web/ui.js +56 -0
- package/web/window-controls.js +3 -3
package/README.md
CHANGED
|
@@ -52,7 +52,7 @@ The launcher asks how your devices should connect, then prints a sign-in link an
|
|
|
52
52
|
|
|
53
53
|
While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
|
|
54
54
|
|
|
55
|
-
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0
|
|
55
|
+
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 and 0.28.0 upgrade the data one way, so going back needs the backup.
|
|
56
56
|
|
|
57
57
|
### Other ways to run it
|
|
58
58
|
|
package/docs/architecture.md
CHANGED
|
@@ -7,10 +7,12 @@ How Pi Pocket's parts depend on each other, and the orderings the code relies on
|
|
|
7
7
|
Pi Durable owns the lasting state of conversations: conversations, entries, tasks, and Pi Pocket's documents (`docs.ts`), in `pocket.sqlite`. People and settings, push subscriptions, uploads, and worktrees are files beside it ([map.md](map.md#data-pi-pocket-or-pi_pocket_dir)). What `PocketApp` keeps in memory about conversations is read back from storage:
|
|
8
8
|
|
|
9
9
|
- At startup, `#recover` reads each conversation's run, agent, chat, subagents, and who Pi works for in it.
|
|
10
|
-
- After that, every commit goes through `#committed`, which keeps the memory up to date.
|
|
10
|
+
- After that, every stored commit goes through `#committed`, which keeps the memory up to date.
|
|
11
11
|
|
|
12
12
|
Pi Durable 1.4.0 migrates SQLite storage to schema version 2 when it opens. Older Durable versions cannot open that database. Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.21.0.
|
|
13
13
|
|
|
14
|
+
Pi Durable 1.5.0 keeps schema version 2, but it stores `pi.live` at version 3, and its tool and generation tasks at newer versions, as soon as a conversation runs. An older Pi Pocket then does not start on that data folder: it stops with "Document … (pi.live) has newer version 3 than 1". Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.28.0, and do not go back to an older version with the same folder.
|
|
15
|
+
|
|
14
16
|
Scheduled messages, PR watches, repository watches, and PiP reports held while PiP is off use durable `sleepUntil()` checkpoints. A sleeping task holds no invocation and resumes at its saved phase when the harness clock reaches its deadline. The task graph includes these tasks with status `sleeping`.
|
|
15
17
|
|
|
16
18
|
Some state lives in this process alone, and a restart forgets it. For example:
|
|
@@ -61,11 +63,12 @@ Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose funct
|
|
|
61
63
|
|
|
62
64
|
## Linked sessions
|
|
63
65
|
|
|
64
|
-
`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.
|
|
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. Pi Pocket's harness settings (`#harnessSettings` in `app.ts`) default Pi's `steeringMode` and `followUpMode` to `all`, unless Pi's settings set them, so every message that waits goes in at one boundary: a team's messages and reports cost the lead one turn, not one each. 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.
|
|
65
67
|
|
|
66
|
-
- **Whom it acts for.** Each call acts as the person Pi works for in the source (`requesterOf`), with their checks: seeing the source, steering, the turn, spend, and, to start one, access to every session. The source in plan mode starts and sends nothing. A message goes through `Commands.submit` as sent for that person (a `p:` request id), with `[via linked session …]` and the message fenced (`defang`), so its text is never a slash command and Pi reads it as a request; the target's checks apply there too. The transcript knows such a message by that label and fence, not by the words before the fence.
|
|
68
|
+
- **Whom it acts for.** Each call acts as the person Pi works for in the source (`requesterOf`), with their checks: seeing the source, steering, the turn, spend, and, to start one, access to every session. The source in plan mode starts and sends nothing. A message goes through `Commands.submit` as sent for that person (a `p:` request id), with `[via linked session …]` and the message fenced (`defang`), so its text is never a slash command and Pi reads it as a request; the target's checks apply there too. It steers (lands at the target's next tool round) unless `send` is told `steer: false`. The transcript knows such a message by that label and fence, not by the words before the fence.
|
|
69
|
+
- **Its end of run reports itself.** `LinkedSessions.watch` listens to `run.ended` (`app-events.ts`): a linked session's own run (not a subagent's) sends its lead, unless archived, one message through the same path, keyed `run-end:<outcome>:<last entry id>` so a run reports once and a replay finds it: its newest assistant entry's text (`MAX_REPORT` characters at most), its failure line, or that it was stopped. The words before the fence say which. A report the lead cannot take becomes a notice there. Only that route reports itself: a message's preface promises it only when the source started the target (`#leads`), and otherwise asks for a reply; `send` returns that as `answers`, and the `team` tool tells Pi. The listener runs after the commit that ended the run, in this process: a crash between the two loses that report.
|
|
67
70
|
- **Once.** Each call's key is hashed with the source into an item of `LinkedSessionCallsDoc` (`pocket.linked-session-calls`), which records the session it made or messaged, whom it acted for, and when. A start writes it in the same commit as the session, then sends the first message; a message's request id is made from the same hash, so a replay finds the session and the message it made. Records are kept 30 days, and the newest 1000.
|
|
68
|
-
- **Bounds.** A linked session starts none. Since 0.19.0 no count limits how many a session starts (before, at most 10, counted in the commit that made one). `LinkedSessionRelayDoc` (`pocket.linked-session-relay`)
|
|
71
|
+
- **Bounds.** A linked session starts none. Since 0.19.0 no count limits how many a session starts (before, at most 10, counted in the commit that made one). Before 0.19.0 `LinkedSessionRelayDoc` (`pocket.linked-session-relay`) counted messages between a team's sessions and refused past 20; since 0.28.0 nothing writes it (its definition stays, for the stored copies). `Spend` counts a team against its top session's budget: the top session, every session linked under it, and their subagents.
|
|
69
72
|
- **What it shows.** Sessions know each other by addresses of their own (`LinkedSessionPeersDoc`, `pocket.linked-session-peers`), so no session id goes into a shared transcript; a fork starts with none. `list` reaches only the sessions the person sees, and names them only when everyone who sees the source sees them too. The session list (`PocketApp.sessions`) gives someone who cannot see the origin `linkedOrigin: true` in place of `linkedFrom`; a scoped person's tabs get their own list in every broadcast, not a filter of everyone's.
|
|
70
73
|
- **Models.** A start copies the source's agent settings (model, thinking, instructions, tools), not its history. It takes only a model on the owner's list for subagents (with no list, only the source's model); a start that names none gets the source's model when it is listed, and is refused when it is not (`ChooseModelError`: Pi must choose from the list, which the error gives). At the thinking level of the source unless the start names another (any level; the model's nearest lower one when it lacks it), and only after `Providers.problem` asks its provider afresh: nothing is made with a model that is not allowed or cannot be used now.
|
|
71
74
|
|
|
@@ -165,6 +168,8 @@ Pi Durable publishes each commit's changes in no set order. `#committed` handles
|
|
|
165
168
|
- Document changes go to `#documentCommitted`. It tracks busy and ended runs, agents, the session list, and the documents the rooms show (`ROOM_DOCS`).
|
|
166
169
|
- Submissions go to `attribution.submissionCommitted`.
|
|
167
170
|
|
|
171
|
+
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.
|
|
172
|
+
|
|
168
173
|
Everything here is synchronous. A commit listener may not call the harness's session APIs, so a write it causes (noting a message's author, or moving a session up the list when Pi starts work there) runs in `setImmediate`. Keep this one coordinator: separate listeners would make their registration order a billing rule nobody can see.
|
|
169
174
|
|
|
170
175
|
Updates to tabs are coalesced:
|
|
@@ -181,6 +186,8 @@ The message Pi is writing goes as what changed since the tab's last update (`liv
|
|
|
181
186
|
|
|
182
187
|
A tab's connection names what its code understands (`p`, `PROTOCOL` in `web/store.js`). 2 keeps the queue when an update leaves it out; 3 takes the message as what changed; 4 takes a full view with only the newest entries; 5 takes them light at first; 6 names what it kept of the session and takes the order as what comes after it. A tab below 3 gets the whole message with each update, and one that names none (older code, as a tab asleep through an update keeps) also gets the queue with each update, because its code drops a queue that an update leaves out.
|
|
183
188
|
|
|
189
|
+
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.
|
|
190
|
+
|
|
184
191
|
A full view for a tab of protocol 4 has the order of every entry in the active context, but only the entries of the newest 80 rows (`firstEntries` in `projection.ts`), with the turn the oldest of them is in, so the tab knows which groups are open there. The tab draws 60 of the rows, and the panel for PiP draws 80. Earlier entries come from `GET /api/c/<id>/context?before=<entry>`, with `rows=<n>` or `from=<entry>` (`Room.entriesBefore`, `loadEarlier` in `web/store.js`), when the person shows earlier messages, opens Find, or jumps to a message that is not loaded yet. The server marks the entries it left out as sent, so an update does not send them. A full view of the same session, as after a reconnect, keeps the entries the tab loaded. A session of 6,000 entries was one event of 8 to 10 MB: on a phone, the tab stopped for most of a second each time to read it, and only its last rows are drawn.
|
|
185
192
|
|
|
186
193
|
A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
|
|
@@ -189,6 +196,8 @@ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`:
|
|
|
189
196
|
|
|
190
197
|
The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
|
|
191
198
|
|
|
199
|
+
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.
|
|
200
|
+
|
|
192
201
|
A tab whose server says it can (`hello.server.switches`) goes to another session on the connection it has: `POST /api/switch` with the connection id its `hello` carried, the session (`c`, none for the list), what it kept of it (`have`, as above), and a number (`seq`) that grows with each switch, so the server drops one that arrives after a newer one (`PocketApp.switchTo`). The server takes the tab out of the old session's room, answers `switched` with that number, and sends the new session as a new connection gets it (`#enter`): its view, chat, notes, and browser. A connection opened anew sent its person's profile, the session list, and PiP's state again, and its person left the app and came back in every other tab's list of who is here, and the session showed "connecting" until all of it came. Until `switched` comes, the tab drops events about a session (its view, chat, notes, people, browser, and missing): the server sent those of the session it left before it heard of the switch. A view or `missing` of another session than the one shown is dropped too. A switch the server cannot take (the connection closed, or the server started again) opens a new connection, which names the session, as before; a server without `switches` gets that too.
|
|
193
202
|
|
|
194
203
|
The session list goes to a tab only when it differs from the one that tab last got (`Client.sessionsSent`): it is large, and it is worked out again for many changes that leave it as it was.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Embedders
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An **embedder** is an app that shows Pi Pocket's web app inside itself: an Electron or Tauri wrapper on a computer, for example, or a phone app with a web view, with notifications, a badge, or a menu of its own. [Pi Pocket GUI](https://github.com/vitalNohj/pi-pocket-gui) is one. Pi Pocket stays a web app on its server; the embedder loads the server's address, and the person signs in there as in a browser.
|
|
4
4
|
|
|
5
|
-
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **
|
|
5
|
+
A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **app bridge** joins the two: the embedder puts `window.pocketHost` in the page, and Pi Pocket uses what it offers. Pi Pocket knows nothing else about the embedder: not its name, not what kind of app it is, not what it runs on. In a browser there is no app bridge, and nothing changes.
|
|
6
6
|
|
|
7
7
|
## Finding Pi Pocket
|
|
8
8
|
|
|
@@ -12,46 +12,51 @@ A browser tab cannot do some things that such an app can, and Web Push does not
|
|
|
12
12
|
{ "name": "pi-pocket", "bridge": 1 }
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
`bridge` is the version of the
|
|
15
|
+
`bridge` is the version of the app bridge that this server's web app speaks. The answer never has Pi Pocket's version. A server older than the app bridge answers 401 there; its web app manifest (`/manifest.webmanifest`) still has `"name": "Pi Pocket"`.
|
|
16
16
|
|
|
17
|
-
## The bridge
|
|
17
|
+
## The app bridge
|
|
18
18
|
|
|
19
|
-
The app
|
|
19
|
+
The app bridge is experimental (since 0.28.0): it can change in a minor release ([API stability](extensions/policies/api-stability.md)). Before 0.28.0-beta.7 these docs were `docs/desktop.md`.
|
|
20
|
+
|
|
21
|
+
The embedder (in Electron, its preload script) puts one object in the top page of the server's origin, and nowhere else: never in a frame (artifacts run in frames), never on another origin.
|
|
20
22
|
|
|
21
23
|
```js
|
|
22
24
|
window.pocketHost = {
|
|
23
|
-
kind: "
|
|
25
|
+
kind: "my-app", // which embedder; for logs only
|
|
24
26
|
apiVersion: 1,
|
|
25
27
|
capabilities: ["menu", "badge", "notify", "visibility", "pinned", "open"],
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
menuTitle(), // the heading of the embedder's group in the menu, such as its name; optional
|
|
30
|
+
menuItems(), // [{ id, label, hint? }]: the items of that group, at the menu's end
|
|
28
31
|
invoke(id), // one of them was chosen; false when it could not be done
|
|
29
32
|
setBadge(count), // sessions that need you, as the home-screen icon counts them
|
|
30
|
-
notify(message), // a notification for the
|
|
31
|
-
visible(), // whether the
|
|
33
|
+
notify(message), // a notification for the embedder to show (below)
|
|
34
|
+
visible(), // whether the embedder's window shows: false while hidden in a tray or minimized
|
|
32
35
|
setPinned(list), // [{ id, title, state, label, url }]: the pinned sessions, in order
|
|
33
|
-
subscribe(listener), // the
|
|
36
|
+
subscribe(listener), // the embedder's events (below)
|
|
34
37
|
};
|
|
35
38
|
```
|
|
36
39
|
|
|
37
|
-
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the
|
|
40
|
+
`web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the embedder throws. `web/embedder.js` does the rest. Pi Pocket uses only the capabilities the embedder names, and ignores ones it does not know. A newer app bridge keeps version 1's calls.
|
|
38
41
|
|
|
39
42
|
### Capabilities
|
|
40
43
|
|
|
41
|
-
| Capability | What Pi Pocket does
|
|
42
|
-
| ------------ |
|
|
43
|
-
| `menu` | Shows `menuItems()` in a
|
|
44
|
-
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes.
|
|
45
|
-
| `notify` | Opens its event stream with `
|
|
46
|
-
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab.
|
|
47
|
-
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these bridge names. `label` says it in words. |
|
|
48
|
-
| `open` | Opens what the
|
|
44
|
+
| Capability | What Pi Pocket does |
|
|
45
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
46
|
+
| `menu` | Shows `menuItems()` in a group of their own at the end of the menu, below its App part, under `menuTitle()` (up to 40 characters); without a title, the group has no heading. Choosing one calls `invoke(id)`. Pi Pocket GUI offers **GUI Settings…** under its name. |
|
|
47
|
+
| `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes. |
|
|
48
|
+
| `notify` | Opens its event stream with `embedder=notify`. The server then sends this connection every notification it would push to the person (`embedder-notify`), and the page passes each to `notify(message)`. |
|
|
49
|
+
| `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab. |
|
|
50
|
+
| `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these app bridge names. `label` says it in words. |
|
|
51
|
+
| `open` | Opens what the embedder asks for (an `open` event), also without `notify`. |
|
|
52
|
+
|
|
53
|
+
A page from before 0.28.0-beta.7, still open after the server updates, asks with `host=notify` and listens for `desktop-notify`: the server still sends it those, until the page reloads.
|
|
49
54
|
|
|
50
55
|
A page in an Electron window keeps running at full speed while the window hides in the tray, so `document.visibilityState` stays `visible` there. That is why `visible()` exists: without it, the server would think the person is looking, and hold every notification back.
|
|
51
56
|
|
|
52
57
|
### Notifications
|
|
53
58
|
|
|
54
|
-
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their
|
|
59
|
+
The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their embedders' connections (`PocketApp.notifyEmbedders`). An embedder that is not running gets nothing: nothing waits for it.
|
|
55
60
|
|
|
56
61
|
```js
|
|
57
62
|
{
|
|
@@ -69,11 +74,11 @@ The server decides as for Web Push (`alerts.ts`): who can see the session, the k
|
|
|
69
74
|
}
|
|
70
75
|
```
|
|
71
76
|
|
|
72
|
-
The
|
|
77
|
+
The embedder chooses how much of an approval to show and whether to offer **Allow**, from `may`, `allow`, and `call`. It always offers **Deny**. The server checks again, when the answer comes, that the person may give it.
|
|
73
78
|
|
|
74
|
-
### The
|
|
79
|
+
### The embedder's events
|
|
75
80
|
|
|
76
|
-
`subscribe(listener)` takes one function. The
|
|
81
|
+
`subscribe(listener)` takes one function. The embedder calls it with:
|
|
77
82
|
|
|
78
83
|
- `{ type: "visibility" }`: its window was shown or hidden. The page reads `visible()` again.
|
|
79
84
|
- `{ type: "open", url }`: open this, such as a notification or a tray item that was clicked. Only addresses of the server's own origin open.
|
|
@@ -81,7 +86,7 @@ The app chooses how much of an approval to show and whether to offer **Allow**,
|
|
|
81
86
|
|
|
82
87
|
## The window's buttons
|
|
83
88
|
|
|
84
|
-
An
|
|
89
|
+
An embedder that hides its title bar, and shows Pi Pocket up to its window's top edge with the window's own buttons over it (close, minimize, zoom), tells the page where they are through the web's standard for it, the Window Controls Overlay (`navigator.windowControlsOverlay`). An installed web app with `"display_override": ["window-controls-overlay"]` does the same. The app bridge is not needed for it.
|
|
85
90
|
|
|
86
91
|
`web/window-controls.js` makes room only under the buttons, and only as much as they take; the rest of the layout keeps its whole height:
|
|
87
92
|
|
|
@@ -92,14 +97,14 @@ An app that hides its title bar, and shows Pi Pocket up to its window's top edge
|
|
|
92
97
|
|
|
93
98
|
The page reads the layout, not the screen: a window, a bar, or a panel that opens (the subagents board, Design, Files, Browser, People) has its room and its cut before the frame that first shows it, and a window that pops in is measured where it lands. Nothing shows under the buttons first and moves after.
|
|
94
99
|
|
|
95
|
-
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an
|
|
100
|
+
On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an embedder can tell that it makes its own room. For a page without it (an older Pi Pocket, a sign-in page), Pi Pocket GUI instead sets a top safe-area inset as tall as the buttons, which Pi Pocket's bars have long kept clear of on phones.
|
|
96
101
|
|
|
97
102
|
## Security
|
|
98
103
|
|
|
99
|
-
The bridge is only as safe as the
|
|
104
|
+
The app bridge is only as safe as the embedder that offers it. An embedder must:
|
|
100
105
|
|
|
101
106
|
- put it only in the top frame of the server's origin, and take it away when that frame goes elsewhere;
|
|
102
107
|
- check, in its main process, the frame and origin of every call that comes from the page: the sender frame's own origin (`senderFrame.origin`), not its `url`, because the server's origin also serves sandboxed artifact pages, whose origin is opaque;
|
|
103
108
|
- give the page no Node.js, and keep its sandbox and context isolation on.
|
|
104
109
|
|
|
105
|
-
Pi Pocket gives the bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the
|
|
110
|
+
Pi Pocket gives the app bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the page.
|
package/docs/examples/clock.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A clock tool, and a /clock-zone command that sets the time zone it uses in a session. An example drop-in extension:
|
|
3
3
|
* copy it into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, opt, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -22,10 +22,8 @@ const clock = defineTool({
|
|
|
22
22
|
name: "clock",
|
|
23
23
|
description:
|
|
24
24
|
"The date and time now, in a time zone such as Europe/Berlin (by default, the session's or the server's).",
|
|
25
|
-
parameters:
|
|
26
|
-
zone:
|
|
27
|
-
Type.String({ description: "An IANA time zone, such as America/Chicago" }),
|
|
28
|
-
),
|
|
25
|
+
parameters: obj({
|
|
26
|
+
zone: opt(str({ description: "An IANA time zone, such as America/Chicago" })),
|
|
29
27
|
}),
|
|
30
28
|
// It only reads the clock: running it again after a restart cut it off is harmless.
|
|
31
29
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Web } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -13,7 +13,7 @@ function countWords(text: string): number {
|
|
|
13
13
|
const wordCount = defineTool({
|
|
14
14
|
name: "my_word_count",
|
|
15
15
|
description: "Count the words in a text.",
|
|
16
|
-
parameters:
|
|
16
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
17
17
|
replay: "safe",
|
|
18
18
|
execute: async (args) => ({
|
|
19
19
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* A note the transcript can fold: one line in the app, and the whole message for the model.
|
|
3
3
|
* An example drop-in: copy it and `quiet-note.js` into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
6
6
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
7
7
|
// A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
|
|
8
8
|
import type { Web } from "../../types/pocket.d.ts";
|
|
@@ -14,9 +14,9 @@ const leaveNote = defineTool({
|
|
|
14
14
|
name: "quiet_note",
|
|
15
15
|
description:
|
|
16
16
|
"Leave a note in this session. The app may show one line; you still read the whole note.",
|
|
17
|
-
parameters:
|
|
18
|
-
text:
|
|
19
|
-
summary:
|
|
17
|
+
parameters: obj({
|
|
18
|
+
text: str({ description: "The whole note" }),
|
|
19
|
+
summary: str({ description: "A few words for the one line" }),
|
|
20
20
|
}),
|
|
21
21
|
// The request id is this call's, so a replay finds the note instead of leaving another.
|
|
22
22
|
replay: "safe",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Reads a public web page for Pi: a read_page tool that fetches only public addresses and fences the page's text.
|
|
3
3
|
*/
|
|
4
|
-
import {
|
|
4
|
+
import { num, obj, opt, str } from "@earendil-works/pi-schema";
|
|
5
5
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
6
6
|
import type { Host } from "../../types/pocket.d.ts";
|
|
7
7
|
|
|
@@ -30,11 +30,9 @@ export default function createReadPage(host: Host) {
|
|
|
30
30
|
const readPage = defineTool({
|
|
31
31
|
name: "read_page",
|
|
32
32
|
description: "Read the text of a public web page (http or https).",
|
|
33
|
-
parameters:
|
|
34
|
-
url:
|
|
35
|
-
maxChars:
|
|
36
|
-
Type.Number({ description: "The text to give at most (default 20000)" }),
|
|
37
|
-
),
|
|
33
|
+
parameters: obj({
|
|
34
|
+
url: str({ description: "The page's address" }),
|
|
35
|
+
maxChars: opt(num({ description: "The text to give at most (default 20000)" })),
|
|
38
36
|
}),
|
|
39
37
|
replay: "safe",
|
|
40
38
|
execute: async (args) => {
|
|
@@ -18,7 +18,7 @@ In the drop-in folder, make the file `my-words.ts` with this text:
|
|
|
18
18
|
/**
|
|
19
19
|
* Counts the words in a text: a tool for Pi, and a /my-words command for people.
|
|
20
20
|
*/
|
|
21
|
-
import {
|
|
21
|
+
import { obj, str } from "@earendil-works/pi-schema";
|
|
22
22
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
23
23
|
import type { Web } from "./_pocket.d.ts";
|
|
24
24
|
|
|
@@ -30,7 +30,7 @@ function countWords(text: string): number {
|
|
|
30
30
|
const wordCount = defineTool({
|
|
31
31
|
name: "my_word_count",
|
|
32
32
|
description: "Count the words in a text.",
|
|
33
|
-
parameters:
|
|
33
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
34
34
|
replay: "safe",
|
|
35
35
|
execute: async (args) => ({
|
|
36
36
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
package/docs/extensions/hooks.md
CHANGED
|
@@ -36,6 +36,10 @@ There are two kinds of hooks:
|
|
|
36
36
|
|
|
37
37
|
The calls of codemode scripts also go through `beforeTool`.
|
|
38
38
|
|
|
39
|
+
## Read a result
|
|
40
|
+
|
|
41
|
+
`afterTool(call, result, api, context)` gets each result before it is stored, and can return a changed one. Since Pi 1.5 (Pi Pocket 0.28.0), it also gets the error results that Pi Durable writes itself: for a tool that is not there, invalid arguments, a block, an interruption, and an abort. Their `result.diagnostics` say which, with a `code` such as `invalid_arguments` or `blocked`. A hook that reads `call.arguments` or `structuredOutput` checks `result.diagnostics` first. In the calls of codemode scripts, `api.entry` and `api.entries` reject.
|
|
42
|
+
|
|
39
43
|
## Send Pi on
|
|
40
44
|
|
|
41
45
|
`onYield(answer, api, context)` runs after Pi's last answer. To send Pi on with another message, return `{ continue: "the message" }`. Done when does this ([goals.ts](../../src/server/extensions/goals.ts)).
|
|
@@ -40,9 +40,17 @@ Check for `web.conversationRoute` at runtime and set gallery `minPocket: "0.16.0
|
|
|
40
40
|
|
|
41
41
|
`send(source, { to, message, steer? }, key)` sends `message` to the linked session at the address `to`.
|
|
42
42
|
|
|
43
|
-
-
|
|
43
|
+
- Since 0.28.0 the message lands at the session's next pause, after its current tool round, as `steer: true` did before. With `steer: false` it waits for the session's run to end. Before 0.28.0 the default was to wait.
|
|
44
44
|
- `send` returns when the session takes the message, not when it answers.
|
|
45
|
-
-
|
|
45
|
+
- It returns `{ answers }` (since 0.28.0; before, nothing): whether the target's final answer comes back to the source by itself, which it does only when the source started the target (see below).
|
|
46
|
+
- 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 write to. From the session that started it, they say its final answer goes back by itself; from any other session (a linked session writing to its lead, or to a sibling), they ask it to send its answer to that address when the message asks for one.
|
|
47
|
+
- Every message that waits in a session's queue goes in together at its next pause (Pi Pocket sets Pi's `steeringMode` and `followUpMode` to `all` unless the owner set them in Pi's settings): a queue of agents' messages costs one turn, not one each.
|
|
48
|
+
|
|
49
|
+
## A session's final answer comes back by itself
|
|
50
|
+
|
|
51
|
+
Since 0.28.0, when a linked session's run ends, Pi Pocket sends the session that started it one message from the linked session's address: its final answer, up to 6,000 characters (more says how much is in the session), or why it failed, or that it was stopped. It lands at the lead's next pause, once for each run, through the same path as `send`, so the same checks apply there: a lead that cannot take it (plan mode, a spend limit, someone else's turn) gets a notice instead, and nothing waits in silence. An archived lead gets nothing.
|
|
52
|
+
|
|
53
|
+
So a tool that starts linked sessions need not ask them to report, and need not poll: the lead ends its turn, and the answers wake it. The report's fence shows as a linked session's card, like a message. Only the session that started one hears its end of run: a linked session that asks its lead, or a sibling, gets an answer only when that session sends one, and the message tells it to.
|
|
46
54
|
|
|
47
55
|
## Stop a run
|
|
48
56
|
|
|
@@ -81,7 +89,7 @@ Pi Pocket keeps a team small. Past these limits ([Limits](reference/limits.md#li
|
|
|
81
89
|
|
|
82
90
|
- A linked session can send messages to the other sessions of its team. It cannot start sessions.
|
|
83
91
|
- Since 0.19.0, no count limits the sessions that a session starts. Before 0.19.0, a session started a limited number.
|
|
84
|
-
- Since 0.19.0, no count of messages between the sessions of a team stops them. Before 0.19.0, they stopped after a limited number until a person wrote in one of them.
|
|
92
|
+
- Since 0.19.0, no count of messages between the sessions of a team stops them, and since 0.28.0 none counts them. Before 0.19.0, they stopped after a limited number until a person wrote in one of them.
|
|
85
93
|
- The budget of the session that started a team covers all of the team. What its linked sessions spend counts against it.
|
|
86
94
|
- A message and a title have a length limit. A title is one line, without invisible or direction characters.
|
|
87
95
|
|
|
@@ -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.
|
|
@@ -479,14 +479,14 @@ send(
|
|
|
479
479
|
source: ConversationId,
|
|
480
480
|
request: { to: string; message: string; steer?: boolean },
|
|
481
481
|
key: string,
|
|
482
|
-
): Promise<
|
|
482
|
+
): Promise<{ answers: boolean }>;
|
|
483
483
|
```
|
|
484
484
|
|
|
485
485
|
Since 0.14.0 · Experimental
|
|
486
486
|
|
|
487
|
-
Sends `message` to the linked session at the address `to`.
|
|
487
|
+
Sends `message` to the linked session at the address `to`. The session gets it at its next pause (since 0.28.0; before, only with `steer: true`). With `steer: false`, it waits for the session's run to end. `send` returns when the session takes the message, not when it answers, with `{ answers }` (since 0.28.0): whether the session's final answer comes back to the source by itself, which it does only when the source started it.
|
|
488
488
|
|
|
489
|
-
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
|
|
489
|
+
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 write to, and say that its final answer goes back by itself when its run ends ([linked-sessions.md](../linked-sessions.md#a-sessions-final-answer-comes-back-by-itself)).
|
|
490
490
|
|
|
491
491
|
#### `linkedSessions.stop`
|
|
492
492
|
|
|
@@ -35,6 +35,7 @@ All the numbers that limit a module, in one place. Each group links to the guide
|
|
|
35
35
|
- **Sessions that one session starts:** no limit, since 0.19.0. Before 0.19.0, 10 at most. A linked session cannot start sessions.
|
|
36
36
|
- **Messages between the sessions of a team:** no limit, since 0.19.0. Before 0.19.0, 20 at most since a person last wrote in one of them. The spend limit of the session that started the team still applies.
|
|
37
37
|
- **A message:** 20,000 characters at most.
|
|
38
|
+
- **A final answer's report** to the session that started it: the first 6,000 characters, and how much more is in the session. Since 0.28.0.
|
|
38
39
|
- **A title:** one line of 120 characters at most.
|
|
39
40
|
- **A call's key:** Pi Pocket keeps the record of a `key` for 30 days, and the records of the last 1,000 calls of each session.
|
|
40
41
|
|
|
@@ -191,7 +191,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
191
191
|
| `sheet-head`, `sheet-body` | Its title bar, and what it holds |
|
|
192
192
|
| `menu` | The menu, on wide screens (it is the sheet `menu` on phones) |
|
|
193
193
|
| `session-menu` | The right-click menu on a session row (since 0.27.0) |
|
|
194
|
-
| `quote-reply-button` | The
|
|
194
|
+
| `quote-reply-button` | The pill that shows over selected text, with Reply and (with PiP on) Ask PiP (since 0.27.0) |
|
|
195
195
|
| `launcher` | The launcher (Ctrl/⌘+K) |
|
|
196
196
|
| `launcher-input`, `launcher-filters` | Its search field, and the search types under it |
|
|
197
197
|
| `launcher-group`, `launcher-row` | A group's heading, and each result |
|
package/docs/extensions/tools.md
CHANGED
|
@@ -10,7 +10,7 @@ Use `defineTool` from `@earendil-works/pi-durable`, and give the tool to your ex
|
|
|
10
10
|
const wordCount = defineTool({
|
|
11
11
|
name: "my_word_count",
|
|
12
12
|
description: "Count the words in a text.",
|
|
13
|
-
parameters:
|
|
13
|
+
parameters: obj({ text: str({ description: "The text to count" }) }),
|
|
14
14
|
replay: "safe",
|
|
15
15
|
execute: async (args) => ({
|
|
16
16
|
output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
|
|
@@ -28,7 +28,7 @@ export default function createMyWords() {
|
|
|
28
28
|
- `name` must be different from the name of each other tool ([Names](reference/names.md)). Use a prefix of your own.
|
|
29
29
|
- `description` and `parameters` go to the model with each request. Keep them short and exact.
|
|
30
30
|
- `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at 11,000 characters (about 4,000 tokens) in a plain session.
|
|
31
|
-
- `parameters` is a
|
|
31
|
+
- `parameters` is a JSON Schema object. Build it with the builders of `@earendil-works/pi-schema`: `obj`, `str`, `num`, `int`, `bool`, `arr`, `union`, and `opt` for a property that can be left out. `obj` makes a closed object (`additionalProperties: false`); `obj(properties, { open: true })` lets other properties through. Pi Durable checks the arguments against the schema before `execute` runs. Since Pi 1.5 (Pi Pocket 0.28.0), pi-schema does the check, and the model gets its messages, such as `- path: missing`. A drop-in written before can keep TypeBox's `Type` from `@earendil-works/pi-ai` ([API versions](reference/api-versions.md)).
|
|
32
32
|
- `execute(args, api, context)` does the work.
|
|
33
33
|
|
|
34
34
|
## Return a result
|
package/docs/extensions.md
CHANGED
|
@@ -69,13 +69,13 @@ A module is one `.ts` file with a default export: a function. Pi Pocket calls it
|
|
|
69
69
|
* A clock tool: the date and time now, in any time zone. The first sentence of this comment is the module's
|
|
70
70
|
* description in the Extensions sheet.
|
|
71
71
|
*/
|
|
72
|
-
import { Type } from "@earendil-works/pi-ai";
|
|
73
72
|
import { defineExtension, defineTool } from "@earendil-works/pi-durable";
|
|
73
|
+
import { obj, opt, str } from "@earendil-works/pi-schema";
|
|
74
74
|
|
|
75
75
|
const clock = defineTool({
|
|
76
76
|
name: "clock",
|
|
77
77
|
description: "The date and time now, in a time zone such as Europe/Berlin.",
|
|
78
|
-
parameters:
|
|
78
|
+
parameters: obj({ zone: opt(str()) }),
|
|
79
79
|
replay: "safe",
|
|
80
80
|
execute: async (args) => ({
|
|
81
81
|
output: [
|