pi-pocket 0.25.0 → 0.26.0
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/AGENTS.md +2 -0
- package/README.md +5 -3
- package/docs/architecture.md +21 -0
- package/docs/design/design-mode.md +108 -0
- package/docs/design/notes-a.md +106 -0
- package/docs/design/notes-b.md +123 -0
- package/docs/design/notes-c.md +92 -0
- package/docs/design/notes-d.md +78 -0
- package/docs/design/release-notes-design.md +46 -0
- package/docs/extensions/browser-modules.md +2 -0
- package/docs/extensions/policies/api-stability.md +2 -0
- package/docs/extensions/reference/api-versions.md +1 -0
- package/docs/extensions/reference/host.md +1 -1
- package/docs/extensions/reference/limits.md +4 -0
- package/docs/extensions/reference/names.md +2 -2
- package/docs/extensions/reference/pocket.md +38 -0
- package/docs/features.md +19 -5
- package/docs/map.md +75 -54
- package/docs/release-notes.md +1 -1
- package/docs/self-editing.md +1 -1
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/launcher/main.ts +20 -9
- package/src/server/app.ts +113 -4
- package/src/server/background.ts +3 -3
- package/src/server/cache-keeper.ts +605 -0
- package/src/server/compaction.ts +68 -15
- package/src/server/design/bundle.ts +65 -0
- package/src/server/design/export.ts +118 -0
- package/src/server/design/files.ts +49 -0
- package/src/server/design/guide.ts +56 -0
- package/src/server/design/index.ts +232 -0
- package/src/server/design/pptx.ts +304 -0
- package/src/server/design/render.ts +593 -0
- package/src/server/design/system.ts +248 -0
- package/src/server/docs.ts +55 -0
- package/src/server/extensions/artifacts.ts +202 -18
- package/src/server/extensions/design/canvas.js +304 -0
- package/src/server/extensions/design/comments.js +15 -0
- package/src/server/extensions/design/data.js +263 -0
- package/src/server/extensions/design/devices.js +70 -0
- package/src/server/extensions/design/docks.js +647 -0
- package/src/server/extensions/design/edits.js +37 -0
- package/src/server/extensions/design/index.js +326 -0
- package/src/server/extensions/design/messages.js +92 -0
- package/src/server/extensions/design/parts.js +160 -0
- package/src/server/extensions/design/state.js +146 -0
- package/src/server/extensions/design/style.css +1332 -0
- package/src/server/extensions/design/tweaks.js +161 -0
- package/src/server/extensions/design/views.js +375 -0
- package/src/server/extensions/design/workspace.js +723 -0
- package/src/server/extensions/design.ts +620 -0
- package/src/server/extensions/plan.ts +11 -9
- package/src/server/extensions/prompt.ts +11 -3
- package/src/server/extensions/subagents.ts +7 -1
- package/src/server/extensions/updates/index.js +16 -6
- package/src/server/extensions/updates.ts +2 -2
- package/src/server/http/artifact-assets.ts +216 -0
- package/src/server/http/artifact-inspect.ts +1281 -0
- package/src/server/http/artifacts.ts +89 -14
- package/src/server/http/conversation-routes.ts +46 -1
- package/src/server/http.ts +12 -4
- package/src/server/main.ts +4 -0
- package/src/server/npm-install.ts +82 -0
- package/src/server/npm-update.ts +100 -0
- package/src/server/reload.ts +5 -0
- package/src/server/room.ts +2 -0
- package/src/server/spend.ts +73 -9
- package/src/server/update-state.ts +257 -8
- package/src/server/updates.ts +268 -33
- package/src/server/zip.ts +163 -0
- package/types/pocket.d.ts +32 -0
- package/web/activity-fold.js +28 -0
- package/web/artifact-bridge.js +506 -82
- package/web/extension-ui.js +21 -1
- package/web/pip.js +46 -9
- package/web/sessions.js +1 -1
- package/web/sheets/appearance.js +10 -0
- package/web/sheets/viewers.js +26 -1
- package/web/style.css +11 -0
- package/web/taps.js +26 -0
- package/web/theme.js +6 -0
- package/web/transcript.js +19 -10
- package/src/server/http/public.ts +0 -30
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Stream D: Design agent tools
|
|
2
|
+
|
|
3
|
+
## Built
|
|
4
|
+
|
|
5
|
+
- `src/server/design/index.ts` exports `designTools(host)`, `designGuide(host)`, and `designRoutes(web, host)`.
|
|
6
|
+
- `design_preview` returns PNG image blocks and bounded console/request diagnostics. It defaults to mobile and desktop. Optional slide numbers start at 1. Deck previews show slide 1 by default and fit the requested device size.
|
|
7
|
+
- `design_export` and the POST export route both call `saveDesignExport` in `export.ts`. That function renders and writes the file, then returns `{ path, name, size }`. It writes PNG, PDF, PPTX, or an HTML ZIP inside the session folder. The default is `exports/<id>-v<version>.<ext>`. Existing files are replaced atomically. Directory links and outside paths are refused.
|
|
8
|
+
- Deck slides use B's 1920×1080 layout by default. A `pocket-slide-size` meta overrides it within the renderer's supported 320–3840 bounds. Preview, PNG, PDF, and PPTX override slide margins, min/max dimensions, and overflow to match B's canvas layout.
|
|
9
|
+
- PPTX contains full-bleed slide images and searchable speaker notes. Default slides remain 16:9. Custom sizes preserve their aspect ratio. It includes the OPC relationships, theme, masters, layout, and content types. It has no external dependencies.
|
|
10
|
+
- PNG exports the full page, up to 2560 × 16000 pixels. A deck PNG shows slide 1 at its slide size, up to 3840 pixels wide. PDF exports every slide on a separate page at the deck's size.
|
|
11
|
+
- Hidden deck slides retain their authored flex/grid display. CDP matched styles recover the base display below hiding rules.
|
|
12
|
+
- HTML ZIP contains the original page and binary assets. Its entry page is `index.html`. If an asset uses that name, the entry becomes `pocket-design.html`, with a numeric suffix if needed.
|
|
13
|
+
- `design_system` reads and writes `<session folder>/.pi/design-system.md`. It bounds text to 16 KB. Reads reject nonregular files and final links. Reads and writes reject a linked `.pi` folder. Writes use an adjacent exclusive temporary file and atomic rename.
|
|
14
|
+
- `designGuide` gives the complete authoring workflow. It includes existing design-system text as fenced, defanged, untrusted project data.
|
|
15
|
+
- The read-only preview tool is replay-safe. File-writing tools do not claim replay safety or read-only access.
|
|
16
|
+
|
|
17
|
+
## Rendering and access
|
|
18
|
+
|
|
19
|
+
Each render launches a separate headless Chromium process with its own temporary profile. It never uses the browser that people watch.
|
|
20
|
+
|
|
21
|
+
A temporary HTTP server binds only to `127.0.0.1`. A random 256-bit bearer path serves only the selected committed bundle. Relative assets resolve below that path. The endpoint closes after the render. Chromium receives no session cookie, user token, or app URL.
|
|
22
|
+
|
|
23
|
+
This deliberately replaces the plan's proposed authenticated `/a/...` request to the live server. It avoids granting untrusted page scripts an app credential. The private endpoint sends the exact `/a/` sandbox CSP, plus a second stricter render-only CSP. The browser enforces both policies together. Every bundle response also sends `X-Content-Type-Options: nosniff`. It serves raw HTML without the interactive app bridge or saved state.
|
|
24
|
+
|
|
25
|
+
External document navigation is refused before any public fetch. A page cannot replace its render CSP with a public document. Other nonbundle requests must use HTTPS and pass through `host.fetchPublic`. Public HTTP resources are refused. Its connection-time DNS and redirect checks refuse private network addresses. Only GET and HEAD requests pass. Chromium cannot open frames, workers, popups, or sockets through the render CSP. A pre-document script removes RTC and WebTransport APIs with immutable properties. Chromium also disables nonproxied WebRTC UDP. This closes a WebRTC bypass that the fresh review reproduced.
|
|
26
|
+
|
|
27
|
+
Limits: 2 concurrent renders, 90 seconds per render, 400 requests, 20 concurrent external requests, 5 MB per external resource, and 50 MB external resources total. Console and request diagnostics each keep at most 100 entries of 2000 characters. PPTX accepts 1–100 deck slides and at most 100 MB of slide images.
|
|
28
|
+
|
|
29
|
+
The renderer closes Chromium and the endpoint on success, failure, or cancellation. It removes the profile with retries and always releases its concurrency slot.
|
|
30
|
+
|
|
31
|
+
## Interfaces for integration
|
|
32
|
+
|
|
33
|
+
### Stream A
|
|
34
|
+
|
|
35
|
+
The coordinator's later integration contract replaces the earlier injected reader. `bundle.ts` reads `ArtifactsDoc`, the selected `ArtifactBodyDoc`, and each manifest asset from the session-scoped `ArtifactAssetDoc` by hash. It returns `{ meta, version: number, content, assets: { name, type, bytes: Buffer }[] }` with raw content.
|
|
36
|
+
|
|
37
|
+
Tools use the tool API snapshot reader. The route uses the host snapshot reader after checking session visibility. The reader validates the artifact ID, selected version, and HTML type. No optional host capability or asset-free fallback is necessary.
|
|
38
|
+
|
|
39
|
+
After merging `feat/design`, both `pptx.ts` and `export.ts` use A's real `src/server/zip.ts`. The temporary `src/server/design/zip.ts` adapter is removed. The shared signature is `zip(entries: { name: string; bytes: Buffer }[]): Buffer`.
|
|
40
|
+
|
|
41
|
+
The merge preserves the integrator's document-backed reader and verifies stored binary assets byte for byte.
|
|
42
|
+
|
|
43
|
+
### Stream C and the HTTP layer
|
|
44
|
+
|
|
45
|
+
Register the returned tools and prompt section in C's `design.ts` module.
|
|
46
|
+
|
|
47
|
+
`designRoutes(web, host)` registers `POST /api/x/design/export` with steer access. JSON body fields:
|
|
48
|
+
|
|
49
|
+
- `conversation`: a session ID in the signed-in person's current session list.
|
|
50
|
+
- `id`: the artifact's kebab-case ID.
|
|
51
|
+
- `version`: an optional positive integer.
|
|
52
|
+
- `format`: `png`, `pdf`, `pptx`, or `html`.
|
|
53
|
+
- `viewport`: optional `mobile`, `tablet`, `desktop`, or `WIDTHxHEIGHT`. Width is 320–2560; height is 240–2560.
|
|
54
|
+
|
|
55
|
+
The route writes `exports/<id>-v<version>.<ext>` in the visible session's authoritative working folder. It returns JSON `{ path, relative, name, size }`, where `path` is absolute, `relative` is `exports/<name>`, and `size` is bytes. It ignores any supplied output path, so browsers cannot select arbitrary files to replace.
|
|
56
|
+
|
|
57
|
+
Extension routes remain JSON-only. C imports D's real tools and routes directly. It posts the export request, then uses core's `GET /api/c/:conversation/download?path=...` route with the returned relative path. Core checks session access and file bounds.
|
|
58
|
+
|
|
59
|
+
## Documentation to merge
|
|
60
|
+
|
|
61
|
+
- `features.md`: describe private previews; PNG, PDF, image-slide PPTX with text notes, HTML ZIP; project design systems; and the preview-before-reply workflow. Explain that PPTX slides are images, not editable vector shapes. Canva export is not included.
|
|
62
|
+
- `map.md`: list the new `src/server/design/` tools, prompt guide, private renderer, document-backed bundle reader, and PPTX writer. Document the Design module's imports and export route.
|
|
63
|
+
- Release notes: include design previews at phone and desktop sizes, portable exports, deck presentations, and reusable project design systems.
|
|
64
|
+
|
|
65
|
+
## Checks and remaining work
|
|
66
|
+
|
|
67
|
+
- Focused D tests: 45 pass after the deck alignment changes; the 2 shared ZIP checks also pass, including real Chromium, token-scoped assets, allowed public HTTPS, blocked public HTTP, private HTTPS/metadata ranges, private UDP, external navigation, preserved hidden-slide layout, device fitting, cancellation cleanup, file bounds, links, FIFO rejection, prompt fencing, ZIP structure, document-backed readers, and JSON POST export contracts. New regressions cover a captured bottom-right pixel at 1920×1080, conflicting size constraints, uncropped 3840×2160 PNG, PDF page sizes/counts, custom PPTX proportions, and every requested guide fact.
|
|
68
|
+
- `npm run format`: passed.
|
|
69
|
+
- After merging `feat/design`, `npm run check` and `npm run lint` pass without local baseline changes. The committed brace fix in `prompt.ts` came from the integrator's branch. The earlier local check-only fix is gone.
|
|
70
|
+
- The deck alignment checks passed all 47 focused tests. The complete updated suite passed with `node --test --test-concurrency=4 test/*.test.ts`: 894 passed, 0 failed, 0 skipped, exit 0.
|
|
71
|
+
- A fresh strong-model review reproduced and checked the remaining deck constraints, wide-image cropping, custom PPTX proportions, and obsolete API tests. The fixes and regressions address each finding. The final review independently checked Chromium corner pixels and the complete square PPTX export path. It found no remaining task blocker.
|
|
72
|
+
- Before the deck alignment merge, the complete suite ran with concurrency 4: 853 of 855 tests passed. `artifact-bridge-ui.test.ts:347` timed out on saved-state reopening. `design-bridge-ui.test.ts:577` timed out on slide fitting. No D test failed. A serial retry of both complete UI test files passed all 26 tests.
|
|
73
|
+
- Before the final contract changes, full `npm test` passed all 788 tests twice. Later unbounded runs had changing timing failures in existing UI and background tests outside D. The isolated mobile, extension UI, and artifact bridge retries passed. The final complete suite passed with `node --test --test-concurrency=4 test/*.test.ts`: 789 passed, 0 failed, 0 skipped, exit 0.
|
|
74
|
+
- The throwaway copy ran with `node test/serve.ts 8904 127.0.0.2`. The mobile page loaded without console errors. The copy was stopped. C's canvas was not present in this isolated branch.
|
|
75
|
+
- Generated and visually inspected a deck PNG. Chromium PDF has 2 widescreen pages with searchable text. After the deck alignment changes, LibreOffice 26.8 opened fresh default and square PPTX exports. It produced 2 pages at 960×540 points for the default and 960×960 points for the square. `unzip -t` passed. PowerPoint and Keynote were not available for direct checks.
|
|
76
|
+
- A strong-model read-only review found 3 defects. The implementation and regression tests address all 3. A follow-up review reproduced a navigation-based TURN-over-TCP bypass. The final review repeated that probe after the fix: 0 public document fetches, 0 private TCP connections, and 0 bytes. It found no remaining blocker. A further review of the injected reader, JSON POST export, public HTTPS restriction, and combined CSP policies also found no blocker. The final shared-export refactor passed another read-only review and all 4 tool-contract tests.
|
|
77
|
+
|
|
78
|
+
The document-backed reader, shared ZIP, core download route, and C's module registration are now present after the merge. The earlier host-reader integration gap is gone. No npm dependencies, live-server changes, restart, push, or pull request are part of this stream.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Design mode: sections for the 0.26.0 release notes
|
|
2
|
+
|
|
3
|
+
These are the Design parts of the 0.26.0 notes. Merge them into the body of pull request 177 under the same headings, and follow [../release-notes.md](../release-notes.md). Add "Design mode" to the title. Update the checks at the end after the release swarm runs.
|
|
4
|
+
|
|
5
|
+
### Highlights
|
|
6
|
+
|
|
7
|
+
- **Design mode.** A canvas beside the chat where you point at a part of a design, comment, edit text, tweak it live, compare versions, and export. Pi checks its own work first.
|
|
8
|
+
- **Artifacts can carry files.** Images, fonts, styles, scripts, data, and more pages load in the viewer, in an inline card, in an artifact's own tab, and in a shared link.
|
|
9
|
+
|
|
10
|
+
### New
|
|
11
|
+
|
|
12
|
+
- **Design mode.** Pi's HTML designs (prototypes, screens, one-pagers, slide decks) open on a canvas beside the chat, at phone, tablet, and desktop sizes. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open`.
|
|
13
|
+
- **Comment:** tap an element, write a note, and it becomes a pin. Comments are shared with the session and last across restarts. **Send to Pi** puts them all in your message box.
|
|
14
|
+
- **Edit text** in the page itself, and **Tweaks**: sliders, colors, and switches that change the design live, kept for each person. Pi writes the changes into a new version when you ask.
|
|
15
|
+
- **Versions:** a timeline, side-by-side compare, and **Go back to this one**, which makes a new version without asking Pi.
|
|
16
|
+
- **Variations and decks.** Variations of one design show as a grid, and **Use this one** tells Pi which to carry on. A deck gets a slide strip and a full-screen present mode.
|
|
17
|
+
- **Pi checks its designs.** Before it replies, Pi renders a design at phone and desktop sizes in a private browser and fixes the errors it finds. The browser you watch stays out of it.
|
|
18
|
+
- **Export.** PNG, PDF, PowerPoint (for decks), and an HTML zip, saved in the session's `exports/` folder and downloaded from the canvas. PowerPoint slides are images, with the slide text as notes.
|
|
19
|
+
- **Project design systems.** Pi reads a codebase or brand files you point at, writes the rules to `.pi/design-system.md` in the session's folder, and follows them in later designs.
|
|
20
|
+
- **Bundles for artifacts.** An artifact version can hold up to 200 files, 5 MB each and 20 MB in all. A new version keeps the files of the last one. Pages can link to each other, and a shared link serves the files too. Old artifacts work as they did.
|
|
21
|
+
|
|
22
|
+
### Known limits
|
|
23
|
+
|
|
24
|
+
- The static preview of an inline card shows no bundle files until you tap **Run**.
|
|
25
|
+
- The inspector adds about 36 KB to each HTML artifact page.
|
|
26
|
+
- A second page inside the frame, or a page that navigates itself, has no bridge. Comments, edits, and tweaks go quiet there.
|
|
27
|
+
- Shadow DOM and nested iframes cannot be picked.
|
|
28
|
+
- A comment shows only on the version it was made on.
|
|
29
|
+
- There is no Canva export.
|
|
30
|
+
|
|
31
|
+
### For theme and extension authors
|
|
32
|
+
|
|
33
|
+
- **Artifact tools.** `artifact` and `artifact_inline` take `assets`, `removeAssets`, `group`, and `kind` (`page` or `deck`). `ArtifactVersion` has an optional `assets` map, and `ArtifactMeta` has optional `group` and `kind`. Assets are stored once for each content hash in the new `pocket.artifact-asset` documents. (experimental)
|
|
34
|
+
- **New built-in tools and module.** `design_preview`, `design_export`, and `design_system` belong to the `design` module. A drop-in cannot use these names.
|
|
35
|
+
- **New stored kind.** `pocket.design-comments` holds a design's comments, each person's tweaks, and the versions made by going back.
|
|
36
|
+
- **Routes.** `POST /api/x/design/c/:conversation/export` writes an export and answers `{ path, relative, name, size }`. The core route `GET /api/c/:id/download?path=<relative>` streams a file of the session folder as an attachment for the people that the file viewer lets read it. `/pub/<token>/<name>` serves a shared bundle's files, and `src/server/http/public.ts` is gone.
|
|
37
|
+
- **Asset addresses.** A private page reaches its assets through a signed address that lasts 12 hours. It permits only the version's files.
|
|
38
|
+
- **The bridge.** The app sends `pocket-inspect`, `pocket-edit-text`, `pocket-tweak-set`, `pocket-highlight`, and `pocket-goto` to the page. The page answers with `pocket-picked`, `pocket-text-edited`, `pocket-tweaks`, and `pocket-deck`, only from the inspector, and the app checks each one. `web/artifact-bridge.js` exports `useArtifactBridge`, `attachBridge`, `sendToFrame`, `checkPageMessage`, and `checkAppMessage`. (experimental)
|
|
39
|
+
- **Page markup.** `data-pid` names an element. `<script type="application/json" id="pocket-tweaks">` declares up to 40 knobs; a name that starts with `--` sets that CSS custom property, and any other name fires `pocket:tweak` on `window`. A deck is `<meta name="pocket-kind" content="deck">` with `<section class="slide">` slides at 1920×1080, or the size in `<meta name="pocket-slide-size" content="WxH">`. (experimental)
|
|
40
|
+
|
|
41
|
+
### Checks to add to "How this release was checked"
|
|
42
|
+
|
|
43
|
+
- Design was built in 4 parts, each with its own strong-model security review. The reviews found bugs, all fixed and checked again.
|
|
44
|
+
- A real Chromium loads bundle fonts, images, styles, and modules through the viewer, an inline card, an artifact's own tab, and a shared link.
|
|
45
|
+
- LibreOffice opened a generated PowerPoint file, and a Chromium PDF of a deck had one page for each slide.
|
|
46
|
+
- **Not tested:** PowerPoint and Keynote.
|
|
@@ -127,6 +127,8 @@ These, and slots, came in 0.19.0, and are experimental: they can change in a min
|
|
|
127
127
|
|
|
128
128
|
**`composerButton({ id, title, icon or iconPath, … })`** adds a button on the left of the message box's row. **`insertText(text)`** puts text into the message box for the person to send: a prompt template, a snippet, a screenshot's description. It never sends.
|
|
129
129
|
|
|
130
|
+
**`pip.ask(text, { send })`** gives the person's PiP, their assistant, a message of the module's: the findings of an analyser, a question about what the module shows. By default it opens PiP and puts the text in its message box, for the person to read, edit, and send. With `send: true` it sends at once, but only just after the person tapped or pressed a key anywhere in the app (so send only from their own action, such as a button's `run`); elsewhere the answer is `{ ok: false, reason }`. It never throws for a person who has no PiP, and resolves with `{ ok: false, reason: "PiP is not available" }`. The text starts with a line that names the module, and PiP reads it as the person's own message, so fence what the module did not write (a session's title, a web page) as untrusted data. It came in 0.26.0, and is experimental. Check for it first: `pocket.pip?.ask`.
|
|
131
|
+
|
|
130
132
|
**`composerKey({ id, keys, label, run(box) })`** adds a key in the message boxes, the session's and PiP's: Ctrl+W to delete a word, Alt+Backspace, keys of an editor you are used to. It comes before the box's own keys. `run` gets the box's `text`, its selection (`start`, `end`), and `set(text, caret)`, which edits the box as typing does. It came in 0.20.0, and is experimental. A browser tab never gets some keys, such as Ctrl+W, which closes the tab: they reach the page only in an installed app's window, if at all.
|
|
131
133
|
|
|
132
134
|
**`onConversation(listener)`**, **`messages({ before, limit, signal })`**, and **`reveal(id)`** let a module follow the session the tab shows, read its people's messages a page at a time, and scroll the transcript to one: an outline of a long session, a list of its questions. The app loads earlier history for `reveal`, and the server checks access for each page. They came in 0.20.0, and are experimental.
|
|
@@ -159,6 +159,8 @@ Since 0.19.0, these `pocket` members are experimental too: `panel`, `openPanel`,
|
|
|
159
159
|
|
|
160
160
|
Since 0.22.0, these are experimental too: `web.publicPage` and `web.links`; `host.ask`, `hide`, `commandEnv`, and `browser`; `host.on`; `web.provide`, `use`, `onService`, `settings`, `setting`, and `onSettings`; `pocket.settings` and `onSettings`; and their types. So are the `browser` tool's `action` and target arguments, for hooks.
|
|
161
161
|
|
|
162
|
+
Since 0.26.0, `pocket.pip` (`ask`) is experimental, with `PipApi` and `PipAskResult`.
|
|
163
|
+
|
|
162
164
|
Since 0.20.0, the session list's extension points are experimental: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, and `sessionSearch`, `WebRequest.sessions`, and their types. So is `pocket.composerKey`, with `ComposerKeySpec` and `ComposerBox`, and so are `pocket.onConversation`, `messages`, and `reveal`, with `MessagesOptions`, `MessagePage`, and `MessageInfo`. So are `host.registerModelProvider`, and `host.fetchPublic` with `PublicFetchInit`.
|
|
163
165
|
|
|
164
166
|
### Deprecated
|
|
@@ -84,3 +84,4 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
84
84
|
| Public pages: `web.publicPage` and `web.links` (experimental) | 0.22.0 |
|
|
85
85
|
| People's values and the browser: `host.ask`, `hide`, `commandEnv`, `browser` (experimental) | 0.22.0 |
|
|
86
86
|
| Events, services, and settings: `host.on`, `web.provide`, `use`, `onService`, `settings`, `setting`, `onSettings`, `pocket.settings`, `onSettings` (experimental) | 0.22.0 |
|
|
87
|
+
| Give PiP a message: `pocket.pip.ask` (experimental) | 0.26.0 |
|
|
@@ -689,4 +689,4 @@ The host has more members, for Pi Pocket's built-in modules only. They are not i
|
|
|
689
689
|
- `pip`: what the tools of PiP, the owner's assistant, do.
|
|
690
690
|
- `pipCompaction`: PiP's own summaries when its context is compacted.
|
|
691
691
|
- `gallery`: the extension gallery, for its own routes.
|
|
692
|
-
- `updates`: updates of Pi Pocket itself, for the Updates module's routes.
|
|
692
|
+
- `updates`: updates of Pi Pocket itself, for the Updates module's routes. Its status says how the copy was installed (`installKind`: `git`, `npm-global`, `npm-local`, `npx`, or `unknown`) and what stands in the way of an update from the app.
|
|
@@ -51,6 +51,7 @@ All the numbers that limit a module, in one place. Each group links to the guide
|
|
|
51
51
|
- **Pages and sheets that a module opens or closes:** past 300 in 1 s, the module stops. With no task between them, it stops past 1000, or at 5 or more over more than 1 s.
|
|
52
52
|
- **Redraws in a hidden tab:** by a timer of 100 ms, which the browser can make slower.
|
|
53
53
|
- **Notices from `pocket.notify`:** 5 every 5 s for a module, for all its versions together. The app drops the rest.
|
|
54
|
+
- **The text of `pocket.pip.ask`:** 1 to 100,000 characters. Others throw. A send needs a tap just before it: it serves for 5 s and for one send.
|
|
54
55
|
- **Rail buttons of modules:** no limit of their own. A rail with more buttons than room scrolls as a whole, and fades the edge where more is. The folded rail keeps up to a third of the window for its sessions first.
|
|
55
56
|
- **A count on a rail button:** a count past 99, and `Infinity`, shows "99+".
|
|
56
57
|
- **Text on a rail button:** past 24 characters, it is cut to 23 characters and "…". A panel's badge is the same.
|
|
@@ -78,6 +79,9 @@ All the numbers that limit a module, in one place. Each group links to the guide
|
|
|
78
79
|
- **Saved state of an artifact (`pocket-state-set`):** 16 KB of JSON at most for one value. A schema is 1 to 64 letters, digits, and `. _ : -`.
|
|
79
80
|
- **Saves:** 20 in 10 s for one person and one artifact. Past that, the save fails.
|
|
80
81
|
- **Saved values of a session:** 300 at most, for all its artifacts and people together.
|
|
82
|
+
- **Assets of a version (since 0.26.0):** 200 files at most, 5 MB for one, 20 MB for all. A name is a relative path of 200 characters at most, with no `.` or `..` segment. A group is a lowercase kebab-case slug of 64 characters at most.
|
|
83
|
+
- **A private asset address:** it is valid for 12 hours.
|
|
84
|
+
- **Design:** a tweaks manifest has 40 knobs at most; a page sends 60 messages a second at most; 2 renders run at once and each takes 90 s at most; a design system file is 16 KB at most.
|
|
81
85
|
- **Shares of a session:** 100 at most at once. A share lasts 1 day, 7 days, or 30 days, or until it is ended (`hours` left out).
|
|
82
86
|
|
|
83
87
|
## Tool calls
|
|
@@ -7,7 +7,7 @@ The rules for the names that a module gives. These are the names of its file, ex
|
|
|
7
7
|
To install an extension with the name of an installed extension replaces that extension. A tool with the name of another tool replaces it in all sessions. Thus Pi Pocket refuses a drop-in that would take a name that Pi Pocket keeps, or a name that another module has. Menu → Extensions says why.
|
|
8
8
|
|
|
9
9
|
- **Extension names that Pi Pocket keeps:** `coding-tools`, and all names that start with `pocket-`, such as `pocket-core`, `pocket-prompt`, and `pocket-guard`. This is true also when that built-in module is off.
|
|
10
|
-
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact`, `artifact_inline`, `browser`, `subagent`, `team`, `schedule`, `codemode`, and `memory`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`.
|
|
10
|
+
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact`, `artifact_inline`, `browser`, `subagent`, `team`, `schedule`, `codemode`, and `memory`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`. Design's tools: `design_preview`, `design_export`, and `design_system`.
|
|
11
11
|
- **Names that another module has:** the first module to install an extension or tool keeps its name.
|
|
12
12
|
|
|
13
13
|
Give each extension and tool a name of your own, with a prefix: `example-clock`, `acme_lookup`. To change how a built-in tool works, do not replace it. Wrap it (`wrapTool` in Pi Durable's README), or check its calls with a hook.
|
|
@@ -16,7 +16,7 @@ Give each extension and tool a name of your own, with a prefix: `example-clock`,
|
|
|
16
16
|
|
|
17
17
|
- A module is a `.ts` file in the drop-in folder.
|
|
18
18
|
- Files that start with `_`, or that end in `.test.ts`, are not modules. Use them for helpers and tests.
|
|
19
|
-
- A drop-in with the name of a built-in module does not load. The built-in modules are `prompt`, `artifacts`, `browser`, `subagents`, `agent-teams`, `schedules`, `goals`, `plan`, `guard`, `codemode`, `memory`, `pip`, `triggers`, and `
|
|
19
|
+
- A drop-in with the name of a built-in module does not load. The built-in modules are `prompt`, `artifacts`, `browser`, `subagents`, `agent-teams`, `schedules`, `goals`, `plan`, `guard`, `codemode`, `memory`, `pip`, `triggers`, `gallery`, and `design`.
|
|
20
20
|
- `_pocket.d.ts` in the drop-in folder is Pi Pocket's link to its types. Do not use this name. See [Types for your editor](types.md).
|
|
21
21
|
|
|
22
22
|
What a module adds to the app uses the name of its file without `.ts`: `server-status.ts` is `server-status`, at `/api/x/server-status/` and `/x/server-status/`. File names are unique across the two folders of modules, so these addresses never collide. A module that adds to the app needs a name of letters, digits, `-`, and `_` that starts with a letter or digit.
|
|
@@ -558,6 +558,16 @@ Since 0.19.0 · Experimental
|
|
|
558
558
|
|
|
559
559
|
Puts text into the message box of the session that the tab shows, after what is there: on a new paragraph, or with `inline: true`, after a space. The person sends it, or not: it never sends. A sheet that shows closes, so the box shows. With no session open, it does nothing. Text past 100,000 characters throws.
|
|
560
560
|
|
|
561
|
+
### `pip`
|
|
562
|
+
|
|
563
|
+
```ts
|
|
564
|
+
readonly pip: PipApi;
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Since 0.26.0 · Experimental
|
|
568
|
+
|
|
569
|
+
The part of `pocket` that talks to the person's PiP, their assistant. It has one method, `pip.ask`. See [`PipApi`](#pipapi).
|
|
570
|
+
|
|
561
571
|
### `arrange`
|
|
562
572
|
|
|
563
573
|
```ts
|
|
@@ -1094,6 +1104,34 @@ Since 0.20.0 · Experimental
|
|
|
1094
1104
|
- `by`: who wrote it: their id and name, when known. A message from before Pi Pocket kept authors has neither.
|
|
1095
1105
|
- `at`: when it was sent, in milliseconds since 1970 on the server's clock, or null.
|
|
1096
1106
|
|
|
1107
|
+
### `PipApi`
|
|
1108
|
+
|
|
1109
|
+
```ts
|
|
1110
|
+
interface PipApi {
|
|
1111
|
+
ask(text: string, options?: { send?: boolean }): Promise<PipAskResult>;
|
|
1112
|
+
}
|
|
1113
|
+
```
|
|
1114
|
+
|
|
1115
|
+
Since 0.26.0 · Experimental
|
|
1116
|
+
|
|
1117
|
+
- `ask(text, options)`: gives PiP `text` as the person's own message. PiP sees it as it sees typed text.
|
|
1118
|
+
- The text starts with a line that names the module (`From the extension “Usage”:`), as an artifact's follow-up starts with its source. So the message never reads as a command, and the person and PiP know where it came from.
|
|
1119
|
+
- By default, it opens PiP and puts the text in PiP's message box, after what is there. The person reads it, edits it, and sends it, or not.
|
|
1120
|
+
- With `send: true`, it sends the text at once, but only just after the person tapped or pressed a key (other than Escape) anywhere in the app, as a tap serves an artifact's follow-up; it need not be on the module's own controls. One tap serves for 5 seconds and for one send, so ask only from the person's own action. Without a tap, nothing is sent or drafted, and the answer says why. If PiP cannot take the message (it is not ready, or the send fails), a notice says so and the text waits in the box.
|
|
1121
|
+
- It works for a person who has PiP. For anyone else, and while the app does not know yet, it does not throw: the answer is `{ ok: false, reason }`.
|
|
1122
|
+
- Text that is empty or past 100,000 characters throws, as `insertText` does.
|
|
1123
|
+
|
|
1124
|
+
### `PipAskResult`
|
|
1125
|
+
|
|
1126
|
+
```ts
|
|
1127
|
+
type PipAskResult = { ok: true; sent: boolean } | { ok: false; reason: string };
|
|
1128
|
+
```
|
|
1129
|
+
|
|
1130
|
+
Since 0.26.0 · Experimental
|
|
1131
|
+
|
|
1132
|
+
- `ok: true`: the text went to PiP. `sent` is true when it was sent, and false when it waits in PiP's message box.
|
|
1133
|
+
- `ok: false`: nothing happened. `reason` says why, in words for a person: `"PiP is not available"`, `"Sending needs a click or a key press just before"`, or that the module's version is no longer loaded. Do not match on the words: they can change.
|
|
1134
|
+
|
|
1097
1135
|
### `ComposerKeySpec`
|
|
1098
1136
|
|
|
1099
1137
|
```ts
|
package/docs/features.md
CHANGED
|
@@ -13,13 +13,13 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
13
13
|
- **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
|
|
14
14
|
- **The menu.** The top bar's **⋯** opens a 360px popover below it on wide screens, and a bottom sheet on phones. Three columns of rounded place tiles open Files, Changes, Browser, Artifacts, Chat, Find, Launcher (on touch screens), Branch, PiP, and Peeks when available; badges show counts or news, and open places are tinted. Session actions, Subagents, and App rows have right-aligned hints and separate groups. App includes **Keyboard shortcuts** (`?`). Arrows, Home/End, and Tab move through the controls; Esc, Back, Close, or a tap outside closes the menu. Back from a sheet it opened returns to the menu.
|
|
15
15
|
- **Keyboard.** Alt+1…9 jumps to a session (hold Alt to see the numbers), Alt+↑/↓ goes to the previous or next one, Alt+N starts a new one (where Ctrl/⌘+1…9 starts it in a favorite folder), Alt+B opens or closes the browser, Alt+E the Files tile, Alt+T turns Show thinking on or off, Alt+V starts or stops dictation, and `?` lists every shortcut. On a computer, a session opens with the caret in its message box, ready to type; on a touch screen it waits for a tap, so the keyboard does not cover the conversation, and on a Mac a session opened with Alt+1…9 or Alt+↑/↓ leaves the box alone, so the next Alt shortcut still works (Option types characters in a box).
|
|
16
|
-
- **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, until you open
|
|
16
|
+
- **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; queued messages can be withdrawn, and your own, tapped open, can move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card.
|
|
17
17
|
- **Getting around on a phone, with one hand.** Back (the swipe, Android's back button, the browser's) goes back to where you were: it closes what opened last (a sheet, the menu's next sheet back to the menu, a file back to the Files tree, back to Changes when the file was opened from there, the Files tile or the Browser panel, the drawer) before it leaves the session, and leaving goes to the session before or to the list, scrolled and searched as you left it. A session opened straight away (a link, a notification) has the list under it, so back does not leave the app. What you use most is a thumb's reach from the bottom edge: the button beside the message box (or a swipe up from it) opens the places, a short sheet of big tiles (Files, Changes, Browser, Artifacts, Chat, Find, Branch, Peeks) with the session menu below them. On the conversation, swipe left for Files and right to go back; in Files, swipe right to go back. Each swipe shows a mark that lights when letting go will act. The top bar leads back to the list (counting other sessions that wait for an approval) and keeps only the buttons with something to say. Every control is a thumb's size on a touch screen (small ones, such as a code block's Copy or a reply's Pin, keep their look and take a wider tap); a tap anywhere on the message box, off its one line of text, still goes to the text; a quick second tap does not land on whatever just slid in under it; tables in replies scroll sideways instead of crushing their columns; a diff's header keeps the file's name on a line of its own on a phone; and the command a peek tile asks about opens its session when tapped. The Files tile and the browser slide in as screens of their own and slide away on back, a file slides in over the tree, and the browser's tools sit on their own row under the address. Drag a sheet down, or the drawer left, to close it. In an iPhone home screen app, which has no back gesture of its own, swipe in from the left edge to go back.
|
|
18
18
|
- **Forks.** Tap Pi's reply → More → **Fork from here**: a new session with everything up to that reply, which then goes its own way. Tap one of your messages to **edit it and send it again**, or send any message again, to the same model or another one (a retry). Each makes a new session that forks just before the message; the original stays as it is. A fork gets its own chat (with the pins of what it inherited), a link back to where it came from, and optionally a git worktree of its own.
|
|
19
19
|
- **A new context.** Menu → **New context** (or `/reset [note]`): Pi starts fresh and no longer sees the messages so far, while everyone still does. An optional handoff note carries over what matters.
|
|
20
20
|
- **Instructions for Pi.** Menu → **Instructions for Pi** (or `/instructions …`): ground rules Pi gets with every message in this session, such as "use pnpm, not npm". Everyone in the session can see them.
|
|
21
21
|
- **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for everywhere: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), and everywhere's reach every session and PiP. Menu → **Memory** (its hint says how many apply here and everywhere) lists them in those two groups, each with who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, for this project or everywhere, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons and everywhere 30; past that, forget one first. Changes show as lines in the chat. Turn it off in Extensions.
|
|
22
|
-
- **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, other commands
|
|
22
|
+
- **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
|
|
23
23
|
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages**: Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only.
|
|
24
24
|
- **Done when.** `/until npm test`: after each of Pi's answers, the check runs in the session's folder; while it fails, Pi gets the end of its output and keeps going, for five checks at most. A bar above the message box shows how it stands. With Lancet Guard on, the check must be a command the guard allows outright. In plan mode the check waits until the plan is approved, and past a spend limit Pi stops going on. A check cut off by a server restart is not run again, as it may have done part of its work: Pi hears so, and its next answer is checked.
|
|
25
25
|
- **Mention files.** Type `@` in the message box to pick a file or folder from the session's folder: `@` alone lists its top, `@src/` a folder's own files, and anything else matches across the whole folder (`@srvapp` finds `src/server/app.ts`). Tab or Enter (or a tap) puts the path in, and a folder opens to its files. Pi gets the message as written, `@src/server/app.ts` and all, and reads what it names; or tap **Send them along** above the box to send the files' contents with the message, as Claude Code does (text files up to 100 KB each, images as images when the model takes them). The list is git's in a repository (so ignored files stay out), and a walk that skips hidden and dependency folders elsewhere; your browser fetches it once and matches as you type, so suggestions never wait on the network.
|
|
@@ -58,11 +58,25 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
58
58
|
- **Roles and invites.** An invite can let someone **steer** or make them **view only** (they read, react, and chat, but cannot send to Pi, approve, or upload). It can cover **every session** or **only this session**, and lasts 15 minutes, an hour, a day, or a week (**Expires after**); either way it works once, and a restart keeps it. Changing what the sheet's invite grants, or how long it lasts, ends the one it showed; **New invite** makes another and leaves the one before working. Only the owner can make an owner invite (**Sign in as me (owner)**): it makes no one new, but signs the device in with the owner's token, so it has full control, works once, and always expires in 15 minutes; rotating the owner token (`--rotate-token`) signs out every device signed in that way, and ends owner invites not yet used. Menu → **People** lists everyone, who is online, and when the others were last here. The owner can change what each person may do or remove them. The session list shows who is in each session, and a dot marks new chat messages.
|
|
59
59
|
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel, or `tailscale serve` in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`.
|
|
60
60
|
- **Built-in browser.** Menu → **Browser** (or Alt+B, `/browser localhost:5173`, or the globe in the top bar while a page is open; on a phone, a dot on the places button by the message box says so) opens a real Chromium page that runs on the server: beside the conversation on wide screens, full screen on phones. Type an address (`localhost:5173`, `example.com`), or (the owner) tap a row under **Running on this machine** on the start screen; a green dot in the rounded address field marks an open page. Tap, drag to scroll, and type into the page (the keyboard button sends text from a phone). The size button switches between fitting the panel (the page follows the panel when it changes size), desktop, phone, and tablet sizes, and the console button shows the page's logs and errors, with a warning-colored error count. Pi's `browser` tool uses the same page: it opens addresses (dev servers, HTML files on the machine, any site), reads a snapshot of the page's text and controls, clicks, types, takes screenshots it can see, reads the console, and runs JavaScript in the page, while everyone in the session watches. Each session has one page, in a browser context of its own; links that open a new tab open there instead, and dialogs are accepted. Anyone in the session can watch; using the page takes steering rights (and the wheel, while take turns is on), the addresses people open show in the chat, and only the owner opens files from the address bar. The browser reaches what the server reaches, `localhost` and its network included, and Lancet Guard does not check it (see SECURITY.md). A restart closes the pages, and each opens again at its last address and size. Where the panel covers the conversation, Esc closes it, unless the page has the keys (then Alt+B does). In plan mode Pi may look at pages but not click, type, or run scripts in them. It needs Chromium, Chrome, Brave, or Edge on the server (or `PI_POCKET_BROWSER`); the owner can turn it off in Extensions, which closes the panel too.
|
|
61
|
-
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type.
|
|
61
|
+
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. The `artifact_inline` tool is the same store for HTML only (`content` or `edits`, no path): its call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but `artifact_inline` refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `artifact_inline` only in sessions that have the tool, and says that only a direct call shows a card. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's.
|
|
62
|
+
- **Design.** On by default (Menu → **Extensions** turns it off). A canvas beside the chat for Pi's HTML designs: prototypes, screens, one-pagers, and slide decks. A design is an artifact, so versions, the sandbox, saved state, and share links work as they do for any artifact. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open` (with an artifact's id to open that one). On a wide screen the panel sits beside the chat; on a phone it covers the chat, and the way back keeps the canvas as it was. Since 0.26.0.
|
|
63
|
+
- **The canvas.** A picker of the session's HTML artifacts (newest first, variations together); the page in the artifact sandbox, at phone (390×844), tablet (820×1180), desktop (1280×800), or a custom size; fit or zoom, and a light, dark, or theme backdrop. A new design that Pi makes opens by itself, unless you are in a mode, have a draft, or it is a variation of the open design.
|
|
64
|
+
- **Versions.** A timeline of every version, side-by-side compare of two, and **Go back to this one**: it makes a new version that is a copy of the old one, assets included, and does not ask Pi. A repeated tap finds the version it made.
|
|
65
|
+
- **Comment.** Tap an element and write a note: it becomes a numbered pin. Comments are shared with everyone who sees the session, last across restarts, and belong to the version they were made on. **Send N to Pi** puts one message with all open comments (each with its element as JSON) in the message box for you to send. Only the author or the owner changes or deletes a comment.
|
|
66
|
+
- **Edit text.** Click text in the page and change it. The changes gather in a list, and **Apply N with Pi** puts one message in the message box.
|
|
67
|
+
- **Tweaks.** A page can declare knobs (colors, sizes, choices, switches) and the Tweaks tab shows them as controls that change the page live. Values are each person's own, kept for each design. **Keep these** puts them in the message box so that Pi writes them into the design.
|
|
68
|
+
- **Variations.** Artifacts of one group show as a grid of live thumbnails. **Use this one** puts a message about it in the message box.
|
|
69
|
+
- **Export and share.** PNG, PDF, PPTX (decks), and an HTML zip, from the menu. The file is written in the session's `exports/` folder and the browser downloads it. **Share a link** is the artifact viewer's Share. There is no Canva export.
|
|
70
|
+
- **What Pi does.** Its guide (a prompt section, only while the module is on) tells it to make each design one HTML artifact with `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs, assets for images and fonts, variations as a group of 2 to 4 artifacts, and to check its work with `design_preview` before it replies. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes by default and returns screenshots, console errors, and failed requests; `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; `design_system` reads and writes the project's design system, `.pi/design-system.md` in the session's folder (16 KB at most), which the guide then includes as untrusted project data. The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. It allows 2 renders at once and 90 seconds for each.
|
|
71
|
+
- **Decks.** A deck is a page with `<meta name="pocket-kind" content="deck">` and its slides as `<section class="slide">`, written at 1920×1080 (`<meta name="pocket-slide-size" content="1280x720">` changes that). The canvas shows one slide at a time, scaled to fit, with a slide strip, a full-screen present mode, arrow keys, and swipes, and the page needs no navigation script of its own. PNG, PDF, and PPTX exports use the same slide size. PPTX slides are images with the slide's text as speaker notes, not editable shapes. A deck opened in its own tab or published shows one slide at a time too, and printing it gives one page for each slide.
|
|
72
|
+
- **For page authors.** `data-pid` names an element for comments and pins. The tweaks manifest is `<script type="application/json" id="pocket-tweaks">[…]</script>`, an array of up to 40 knobs `{ name, label?, type: "range" | "color" | "select" | "toggle" | "text", value, min?, max?, step?, unit?, options? }`. A name that starts with `--` sets that CSS custom property on `:root`; any other name reaches the page as a `pocket:tweak` event on `window`. The app speaks to the page through the bridge's `pocket-inspect`, `pocket-edit-text`, `pocket-tweak-set`, `pocket-highlight`, and `pocket-goto` messages, and the page answers with `pocket-picked`, `pocket-text-edited`, `pocket-tweaks`, and `pocket-deck`. Only the app's inspector can send those answers, and the app checks their shape and length before it uses them.
|
|
73
|
+
- **Who.** People who see every session load the module; people who steer comment, edit, tweak, go back, and export; viewers read the canvas, versions, and comments. Someone invited to one session never loads it. While **Take turns** is on, only the driver writes.
|
|
74
|
+
- **Limits.** The static Preview of an inline card does not load a bundle's assets until you tap Run. The inspector adds about 36 KB to each HTML artifact page. A second HTML page inside the frame has no bridge, and neither has a page that navigates itself, so comments, edits, and tweaks go quiet there. Shadow DOM and nested iframes cannot be picked. A comment shows only on the version it was made on. On a phone, a 1280 px page at "fit" is small: use zoom or a custom size.
|
|
62
75
|
- **Agent Teams.** Off until the owner turns it on in Menu → **Extensions**. Pi starts work in a linked session: an ordinary session in the list, under the one that started it, with its own settings and life (stopping or archiving one leaves the other as it is). It works in the same folder, or in the folder an extension names with `cwd` (since 0.19.0; no worktree of its own) with the same model, thinking level, and agent settings, but none of the history, plan mode, or budget, so Pi gives it all it needs in its first message. With **Models for subagents** (Menu → Providers) empty, it runs on the starting session's model; with models checked there, it runs only on one of them: the session's model when that is checked and Pi names none, else a checked one that Pi must name (the refusal lists them), and Pi may name only a checked one. A linked session's reply to the session that started it goes whatever model that one runs on. A message to a linked session on a model that is no longer checked is refused. Pi may name any thinking level, also one above the session's (a level the model lacks becomes its nearest lower one, or its lowest); a model that cannot be used now is refused, with no session made. Pi's tool, `team`, starts linked sessions, lists them, and sends them messages, both ways: an answer does not go back by itself, so each one sends back what it was asked for. A message from a linked session shows as "via a linked session", and Pi takes it as a request, not as a person's order. Since 0.19.0, linked sessions write their messages and replies to each other in ASD-STE100 (Simplified Technical English), at about 80% adherence; their answers to messages from people stay as they were. The links above the transcript (**Started from**, **Linked session**, and past three, **+N more**) open the others. Each start and message acts as the person Pi works for, with their access, take turns, plan mode, and spend limit: a session someone cannot see stays out of their reach, and its name out of the list Pi gets, unless everyone in the session sees it. A link gives no access: someone who sees only the new session does not learn where it came from. A team has bounds: a linked session starts none, and the budget of the session that started the team covers what all of them spend. No count limits how many linked sessions a session starts, and no count of messages between them stops them (since 0.19.0; before, a session started 10 at most, and they stopped after 20 messages with no person writing). Unlike subagents, linked sessions report nothing by themselves, and a subagent cannot start them.
|
|
63
76
|
- **Session tags.** Off until the owner turns it on in Menu → **Extensions**. Shared labels on sessions, which show as chips under each row's title. To tag sessions, hover a row and click its tag button, hold a row (on a touch screen), or select rows (Ctrl/⌘+click, or **Select**) and choose **Edit tags**, or use **Edit this session's tags** in the launcher: add a tag, take one off, then Save. Tags are lowercase, up to 32 characters each, and 10 on a session at most; a change to several sessions saves on all of them or on none. The filter button in the session search, or a tap on a chip, shows only the sessions that have every chosen tag; the tab keeps its filter until it closes. **New** in the Sessions head, while the filter is on, gives the new session the chosen tags, so it stays in the list. The list's search and the launcher find sessions by their tags too. People who steer every session edit tags, viewers see them and filter by them, and people invited to one session do not see them. Each person sees only the tags of the sessions they can see. Since 0.20.0; it uses the session list's extension points, which other extensions can use too ([browser-modules.md](extensions/browser-modules.md#the-session-list)).
|
|
64
77
|
- **Ask someone.** Off until the owner turns it on in Menu → **Extensions**. When Pi needs an answer that only someone outside the chat can give (a manager, a client, an expert), **Ask someone** under one of Pi's answers puts a request in the message box, and Pi writes the question with its `ask_someone` tool so that it stands alone: the background, the question, the options, and its recommendation. Nothing goes anywhere yet: the draft waits in **Questions for others** (the status line under the message box, the session menu, or the launcher), where you edit it, **Copy text**, or **Create link** for a day, a week, or a month. The link opens a page with no sign-in, the question, and a box for one answer and an optional name; then it closes. **Copy link**, **Copy message**, and **Share…** (on a phone) send it on; **End link** takes the page down. When the answer comes, a notice says so, and **Give to Pi** puts it in the message box, quoted and marked as someone else's view, for you to send. People who steer every session use it; viewers and people invited to one session do not. Since 0.22.0.
|
|
65
78
|
- **Waiting out provider limits.** When a provider's limit stops a run (a 429 or an overload, a Claude or ChatGPT usage window, a model's cap), Pi Pocket waits for it to clear and goes on by itself, instead of failing. It waits until the reset time the provider gave (or, with none, tries again at growing intervals), then sends one request to find out; if that gets an answer, the sessions waiting on the same limit go on, one at a time. The live line says what Pi waits for, when it tries next, and when the limit resets, with **Retry now**; **Stop** or **Interrupt** end the wait at once, and a message you send meanwhile waits in the queue as always. The session's square is a hollow square with a dot, also on peek tiles, and a subagent's row says it waits. One push goes out when a wait of ten minutes or more begins (Menu → **Notifications** → **Waiting for a limit**). It survives a restart. The owner sets the longest wait (**Wait for a limit** in the Providers sheet: Off, 1, 6, 12, or 24 hours; default 6): what waits is any reset time within that longest wait, load with no time given (an ordinary 429 or an overload), which is tried again at growing intervals for up to 30 minutes, and, since 0.24.0, a plan's usage limit with no time given (OpenAI subscription sharing, Z.ai, MiniMax, OpenCode Go), which is tried again about every 15 minutes, up to the longest wait, counted from the first failure across restarts. What fails the run at once, with the reset in the message where there is one: a window of days (Claude's 7-day window, a Codex window of over 300 minutes), a reset after the longest wait, a usage limit that names a window of days (daily, weekly, monthly), with or without a reset time, and a sign-in that expired or billing. Retry now sends one try each 30 seconds. It never picks another model. Since 0.21.0.
|
|
79
|
+
- **Prompt cache keeper.** On by default; `PI_POCKET_CACHE_KEEPER=off` turns it off. While a run waits on a tool call, Pi Pocket replays the last request that ended in a tool call, with `maxTokens` 1, at 90% of the cache's lifetime or 10 seconds early, whichever is sooner. It does so only when the expected savings are more than the cost. It keeps the 5-minute cache only: no idle warming, no 1h cache, no request with `cacheRetention` none, and no Anthropic thinking set by a token budget. It stops on a real cached request, when the run ends (PiP's too), on an error, at shutdown, or after 30 minutes. A warm request does not wait for a provider limit. Its usage counts in `pi.usage` and in the spend of the person and session that were paying when it started, and spend limits are checked before each warm. A restart drops the warm timers and does not replay warm requests.
|
|
66
80
|
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.19.0, Pi writes its tasks for subagents in ASD-STE100 (Simplified Technical English) and asks for their reports in it too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. Pi picks no model on its own: until the owner allows models for subagents (**Models for subagents** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model.
|
|
67
81
|
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Open as a conversation** shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back.
|
|
68
82
|
- **Resize.** At widths of 768px and above, drag PiP's left edge, top edge, or top-left corner to resize it, with the bottom-right corner fixed. The same zones are finger-sized on touch screens. Its size is remembered for each account in this browser and fits back inside the viewport when it shrinks. Phones use a bottom sheet with rounded top corners and a grabber; the model, context meter, and all four header actions stay available.
|
|
@@ -93,10 +107,10 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
93
107
|
- **Drop-in extensions.** Put your own extension module (a `.ts` file that default-exports `(host, web) => Extension`, or a list, or nothing) in `~/.pi-pocket/extensions/`. It shows in the Extensions sheet, stays off until the owner turns it on, can import Pi Pocket's packages (Pi Durable, pi-ai, Pi's MCP client pi-mcp, and the rest) as the built-in modules do, and reloads when edited. One that would take the name of a built-in extension or tool, or of another drop-in's, is not loaded, and the sheet says why: installing it would replace that one.
|
|
94
108
|
- **Extensions in the app.** A module can add to the app itself, without changes to Pi Pocket's code: routes on the server, commands for the message box, and a browser module with buttons on the rail, pages in the conversation's place (as the subagents board shows), panels beside the conversation (where the Browser and Files panels dock, with a button in the top bar and the places), items in the status line under the message box (with a short form a narrow line takes), sheets, rows in the menu, and launcher actions, which work without asking Pi. A dashboard of a provider's usage, the server's load, or a machine's power and temperature, say: the route asks the service with a key that stays on the server, and the page shows what it says, live with the module's events. It is the owner's alone unless the module opens it to people who can steer, or to everyone who sees every session; someone invited to one session never gets it. A module can also show **public pages** to anyone with one of its links, with no sign-in (`/l/<token>`, since 0.22.0): each link closes at its time (30 days at most) or after the answers it takes, the page runs in a sandbox with no script, so whoever opens it while signed in lends it nothing, and Extensions says which modules have them ([docs/extensions/public-pages.md](extensions/public-pages.md)). Turning the module off takes away what it added, its pages included; an edit swaps the routes, and an edit to the browser module's files has tabs load it again. One that fails tells the owner why in a notice and in the Extensions sheet, and the rest of the app goes on; a tab opened with `?noext=1` loads none of their browser parts (safe mode), to turn off one that breaks the app. [docs/extensions.md](extensions/app.md) says how, with an example: a page with the server's load, memory, and uptime.
|
|
95
109
|
- **Extension workspace APIs (0.16.0).** A page can save its own durable catalog with request-lifetime document commits, or use a source-bound route to start linked sessions as the person who clicked Run. Current source access, turn, plan, spend, team, and model checks apply; explicit thinking choices are not silently lowered. Human history can open authorized sessions through `pocket.openConversation`. Extensions can read the running server's package version through `host.pocketVersion` or browser `pocket.pocketVersion`, without an updater or restart control; the extension API level remains 1.
|
|
96
|
-
- **Extensions hub.** Menu → **Extensions** opens **Discover**, **Installed**, and **Updates** for the owner while the gallery is on. Wide screens show the list and selected entry side by side; phones show one at a time, with Back returning to the filtered list. **Installed** (also tap "guard" in the status line) lists Pi Pocket's extensions with their tools, the routes, commands, and browser module they add to the app, and any load error, in this browser too. The owner can turn Artifacts, Browser, Subagents, Scheduled messages, Done when, Plan mode, Codemode, Memory, PiP, Triggers, Extension gallery, Pi Pocket updates, Agent Teams, Session tags, Lancet Guard, or a drop-in off and on, or reload one; the change applies to every session at once, stays after restarts (`disabledExtensions` and `enabledExtensions` in `~/.pi-pocket/config.json`), and everyone in a session sees who changed what. Turning Lancet Guard off first shows a warning card with **Keep it on** and **Turn off**; only **Turn off** applies the change. This leaves Pi's own setting (`~/.pi/lancet-guard.json`) alone. Under PiP, the owner picks when PiP compacts its context. The system prompt cannot be turned off.
|
|
110
|
+
- **Extensions hub.** Menu → **Extensions** opens **Discover**, **Installed**, and **Updates** for the owner while the gallery is on. Wide screens show the list and selected entry side by side; phones show one at a time, with Back returning to the filtered list. **Installed** (also tap "guard" in the status line) lists Pi Pocket's extensions with their tools, the routes, commands, and browser module they add to the app, and any load error, in this browser too. The owner can turn Artifacts, Design, Browser, Subagents, Scheduled messages, Done when, Plan mode, Codemode, Memory, PiP, Triggers, Extension gallery, Pi Pocket updates, Agent Teams, Session tags, Lancet Guard, or a drop-in off and on, or reload one; the change applies to every session at once, stays after restarts (`disabledExtensions` and `enabledExtensions` in `~/.pi-pocket/config.json`), and everyone in a session sees who changed what. Turning Lancet Guard off first shows a warning card with **Keep it on** and **Turn off**; only **Turn off** applies the change. This leaves Pi's own setting (`~/.pi/lancet-guard.json`) alone. Under PiP, the owner picks when PiP compacts its context. The system prompt cannot be turned off.
|
|
97
111
|
- **Extension settings.** A module can declare settings (on or off, text, a number, a choice, or a secret such as an API key); the owner changes them in Menu → Extensions under the module, with **Save settings**, and **Default** or **Clear** to put one back. A secret's value never leaves the server: the sheet shows only that it is set. Modules can also listen to what happens in the app (sessions made, renamed, and archived, messages, runs) and offer services to each other; Extensions says which ones offer a service. Since 0.22.0 ([docs/extensions/services-settings.md](extensions/services-settings.md)).
|
|
98
112
|
- **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**. An entry walks through three steps, each with its buttons: **Install** (it stays off), **Look it over** (**View source**, **Ask Pi to review**), and **Turn it on**, which asks once more, in place, before code runs; what it adds shows in plain words, with technical information folded below. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)).
|
|
99
|
-
- **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone.
|
|
113
|
+
- **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on) and **Install new versions by themselves** (off). An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
|
|
100
114
|
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (above Models for subagents), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
|
|
101
115
|
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them.
|
|
102
116
|
- **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact_inline` call shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
|