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
package/docs/map.md
CHANGED
|
@@ -4,7 +4,7 @@ Where things are in Pi Pocket, for agents working on it. [index.md](index.md) li
|
|
|
4
4
|
|
|
5
5
|
## Processes
|
|
6
6
|
|
|
7
|
-
`bin/pi-pocket.js` checks Node, then runs `src/launcher/main.ts`. In an npm install, Node strips no types from files in `node_modules`: `bin/strip-types.js` does it for Pi Pocket's own files there, in the launcher and (with `--import`) in the server. The launcher reads its options (`options.ts`), asks how devices connect (`access.ts`: this device, LAN, Cloudflare quick tunnel, Tailscale), runs the server (`src/server/main.ts`) as a child, restarts it on exit code 75 or a crash, and keeps the tunnel up. When a server stops before it is ready while an update from the app is under way, it goes back to the version before (`rollBackUpdate` in `src/server/update-state.ts`, the one server module it imports). `term.ts` draws its menu, panel, and QR code in the terminal. The server takes the data folder's lock, opens one `PocketApp`, and serves it with `http.ts`.
|
|
7
|
+
`bin/pi-pocket.js` checks Node, then runs `src/launcher/main.ts`. In an npm install, Node strips no types from files in `node_modules`: `bin/strip-types.js` does it for Pi Pocket's own files there, in the launcher and (with `--import`) in the server. The launcher reads its options (`options.ts`), asks how devices connect (`access.ts`: this device, LAN, Cloudflare quick tunnel, Tailscale), runs the server (`src/server/main.ts`) as a child, restarts it on exit code 75 or a crash, and keeps the tunnel up. When a server stops before it is ready while an update from the app is under way, it goes back to the version before: the commit and packages of a git checkout, or the kept copy of a global npm install (`rollBackUpdate` in `src/server/update-state.ts`, the one server module it imports). `term.ts` draws its menu, panel, and QR code in the terminal. The server takes the data folder's lock, opens one `PocketApp`, and serves it with `http.ts`.
|
|
8
8
|
|
|
9
9
|
## Data (`~/.pi-pocket/`, or `PI_POCKET_DIR`)
|
|
10
10
|
|
|
@@ -18,23 +18,25 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
18
18
|
|
|
19
19
|
### The core
|
|
20
20
|
|
|
21
|
-
| File | Owns
|
|
22
|
-
| ----------------------- |
|
|
23
|
-
| `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler`
|
|
24
|
-
| `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off |
|
|
25
|
-
| `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup
|
|
26
|
-
| `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`)
|
|
27
|
-
| `projection.ts` | Entries as compact JSON for browsers; `usageCost`
|
|
28
|
-
| `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed
|
|
29
|
-
| `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions
|
|
30
|
-
| `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
21
|
+
| File | Owns |
|
|
22
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler` |
|
|
24
|
+
| `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off Bundle readers for artifacts (`artifactBundle`: the page and its assets by hash, `artifactAsset`: one manifest asset), which callers must check access for. |
|
|
25
|
+
| `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup |
|
|
26
|
+
| `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`) |
|
|
27
|
+
| `projection.ts` | Entries as compact JSON for browsers; `usageCost` |
|
|
28
|
+
| `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed |
|
|
29
|
+
| `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions |
|
|
30
|
+
| `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait |
|
|
31
|
+
| `cache-keeper.ts` | The prompt cache keeper around every model stream: replays a tool-call request with one output token just before its 5-minute cache expires, when that costs less than a rebill; stops on a real request, run end, error, shutdown, or 30 minutes; warm usage counts in spend |
|
|
32
|
+
| `entry-format.ts` | The kinds of Pi Pocket's own entries, and the markers it writes into message text (`[from: …]`, attached files). Stored data and the web app depend on their exact values |
|
|
33
|
+
| `fence.ts` | Text from elsewhere between tags as data, for Pi: no closing tag survives inside it |
|
|
34
|
+
| `docs.ts` | Every durable document Pi Pocket defines The design workspace's `pocket.design-comments` (comments, tweaks, restores) and the artifact bundle documents (`pocket.artifact-asset`, by content hash). |
|
|
35
|
+
| `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
|
|
36
|
+
| `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
|
|
37
|
+
| `lock.ts` | One process per data folder |
|
|
38
|
+
| `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
|
|
39
|
+
| `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
|
|
38
40
|
|
|
39
41
|
`extension-request.ts` owns extension routes' request-lifetime document/context capabilities and fresh person/source authorization. `http/extension-routes.ts` binds named source parameters and supplies human linked-session capabilities. `linked-sessions.ts` keeps the short final-admission lease; its child context watches policy publications and checks current config when Durable enters admission. `models.ts` supplies exact local `host.modelInfo` metadata. `versions.ts` supplies `host.pocketVersion` and `hello.server.pocketVersion`, read by browser `pocket.pocketVersion`; `pocket.openConversation` delegates to normal `store.navigate`.
|
|
40
42
|
|
|
@@ -78,7 +80,7 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
78
80
|
| `github.ts` | GitHub through `gh`: running it unattended, repository and PR names in every form, and whether `gh`'s account can push to a repository |
|
|
79
81
|
| `memory.ts` | Memory: lessons Pi keeps across sessions, each for a project (a repository with its worktrees, or a folder) or everywhere; the lessons in force for a session, and people's view, writes, and approvals |
|
|
80
82
|
| `folder-favorites.ts` | Each person's favorite folders (`/api/folder-favorites`): starring and unstarring one in a transaction, and each person's list sent only to their own tabs |
|
|
81
|
-
| `share.ts` | Artifact shares (`/api/c/:id/shares`): publishing one artifact version, or the newest, to anyone with a link, ending it, and what a published token shows now (needs no sign-in); only people who see every session publish or end one
|
|
83
|
+
| `share.ts` | Artifact shares (`/api/c/:id/shares`): publishing one artifact version, or the newest, to anyone with a link, ending it, and what a published token shows now (needs no sign-in); only people who see every session publish or end one A published bundle's files are served by `http/artifact-assets.ts`. |
|
|
82
84
|
| `public-links.ts` | Extension modules' public links (`web.links`): made, listed, and ended for their own module only, each closing at its time or after its uses; a use counts before the page handler runs and comes back when the page refuses the post (needs no sign-in) |
|
|
83
85
|
| `hidden.ts` | Values extensions hide (`host.hide`) from command output as it streams and from every tool's result, and the variables they add to each command (`host.commandEnv`), both through the environment each conversation's commands run in (`wrapEnv`) |
|
|
84
86
|
| `extension-points.ts` | `host.ask`, an extension's question on an approval card whose typed values go to the asker alone, and `host.browser`, a session's page for extensions with `fill` and controls as data, but no script |
|
|
@@ -101,24 +103,25 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
101
103
|
|
|
102
104
|
### HTTP: `http.ts` and `http/`
|
|
103
105
|
|
|
104
|
-
| File | Owns
|
|
105
|
-
| ----------------------------- |
|
|
106
|
-
| `http.ts` | The one request handler: which part answers a path, and the error boundary that turns what it throws into a status
|
|
107
|
-
| `http/api.ts` | `/api`: signing in, the `X-Pocket` header, and the app-wide routes (people, sessions, Pi's sessions from the terminal, peeks, the subagents board, spend, folders, settings, the models for subagents, extensions, providers, invites, restart)
|
|
108
|
-
| `http/conversation-routes.ts` | `/api/c/:id`: one conversation's routes, after the API checked that the person may see it
|
|
109
|
-
| `http/browser-routes.ts` | `/api/c/:id/browser`: the Browser panel's frames, console, and input
|
|
110
|
-
| `http/push-routes.ts` | `/api/push`: this device's subscription, what to notify about, a test
|
|
111
|
-
| `http/hook-routes.ts` | `/hook/:id/:secret`: posts to webhooks, with no sign-in
|
|
112
|
-
| `http/events.ts` | Each tab's events: the event stream (`/api/events`), or long polling (`/api/poll`) where a tunnel holds streams back
|
|
113
|
-
| `http/assets.ts` | The web app's files (with an ETag, and compressed), the vendored modules, the app's content security policy, and image files
|
|
114
|
-
| `http/compress.ts` | Which encoding a request accepts (brotli, else gzip), and compressing an answer, a kept file, or an event stream
|
|
115
|
-
| `http/theme-routes.ts` | `/themes/:id/:rev/…`, a theme's files for everyone signed in: its CSS as checked, from memory; its fonts and images from disk, opened as checked and sniffed
|
|
116
|
-
| `http/sign-in.ts` | `/login`, `/join/:code`, and `/share` before the service worker takes shares
|
|
117
|
-
| `http/artifacts.ts` | `/a/…`: an artifact as its own page, in a sandbox; `/a/frame`, the page a reply's HTML runs in once someone taps Run; `artifactResponse`, the page both routes and a published one serve
|
|
118
|
-
| `http/
|
|
119
|
-
| `http/
|
|
120
|
-
| `http/
|
|
121
|
-
| `http/
|
|
106
|
+
| File | Owns |
|
|
107
|
+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| `http.ts` | The one request handler: which part answers a path, and the error boundary that turns what it throws into a status `/pub/<token>/<name>` goes to `publicArtifactBundle`. |
|
|
109
|
+
| `http/api.ts` | `/api`: signing in, the `X-Pocket` header, and the app-wide routes (people, sessions, Pi's sessions from the terminal, peeks, the subagents board, spend, folders, settings, the models for subagents, extensions, providers, invites, restart) |
|
|
110
|
+
| `http/conversation-routes.ts` | `/api/c/:id`: one conversation's routes, after the API checked that the person may see it |
|
|
111
|
+
| `http/browser-routes.ts` | `/api/c/:id/browser`: the Browser panel's frames, console, and input |
|
|
112
|
+
| `http/push-routes.ts` | `/api/push`: this device's subscription, what to notify about, a test |
|
|
113
|
+
| `http/hook-routes.ts` | `/hook/:id/:secret`: posts to webhooks, with no sign-in |
|
|
114
|
+
| `http/events.ts` | Each tab's events: the event stream (`/api/events`), or long polling (`/api/poll`) where a tunnel holds streams back |
|
|
115
|
+
| `http/assets.ts` | The web app's files (with an ETag, and compressed), the vendored modules, the app's content security policy, and image files |
|
|
116
|
+
| `http/compress.ts` | Which encoding a request accepts (brotli, else gzip), and compressing an answer, a kept file, or an event stream |
|
|
117
|
+
| `http/theme-routes.ts` | `/themes/:id/:rev/…`, a theme's files for everyone signed in: its CSS as checked, from memory; its fonts and images from disk, opened as checked and sniffed |
|
|
118
|
+
| `http/sign-in.ts` | `/login`, `/join/:code`, and `/share` before the service worker takes shares |
|
|
119
|
+
| `http/artifacts.ts` | `/a/…`: an artifact as its own page, in a sandbox; `/a/frame`, the page a reply's HTML runs in once someone taps Run; `artifactResponse`, the page both routes and a published one serve With assets, it puts an absolute `<base href>` in the page, and a deck opened as a page of its own gets `withDeck`. |
|
|
120
|
+
| `http/artifact-assets.ts` | A bundle's files: safe names (`assetName`), the fixed extension-to-type table (`ASSET_TYPES`, `assetType`), the sandbox policy for assets (`ARTIFACT_CSP`), the 12-hour signed asset address that a sandboxed page uses (it has no cookie), the file route under `/a/…`, and `publicArtifactBundle`, the page and files of `/pub/<token>/…` (checked on every request) |
|
|
121
|
+
| `http/artifact-inspect.ts` | The page side of Design mode, as a script string (`ARTIFACT_INSPECT`) that the bridge script includes: inspect, text edit, tweaks, pins, and decks (one slide at a time, `withDeck`). Inert until the app turns a mode on. The script has no backtick, because it sits in a template string |
|
|
122
|
+
| `http/link-routes.ts` | `/l/<token>`: a module's public page (`web.publicPage`) for anyone with its link, with no sign-in, sent in a sandbox with no script; reads urlencoded forms only |
|
|
123
|
+
| `http/extension-routes.ts` | `/api/x/:module/…`, extension modules' routes (after the API's checks), and `/x/:module/:rev/…`, their browser modules' files |
|
|
124
|
+
| `http/io.ts` | What every route uses: reading a body, writing JSON, `ApiRequest`; a file to serve, read as it was checked (`readChecked`, `opened`); the policy an SVG is served with |
|
|
122
125
|
|
|
123
126
|
### The built-in browser: `browser.ts` and `browser/`
|
|
124
127
|
|
|
@@ -133,28 +136,43 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
133
136
|
| `browser/viewport.ts`, `browser/urls.ts` | Page sizes and their presets; what people and Pi type, made into addresses |
|
|
134
137
|
| `browser/local-servers.ts` | The web servers running on this machine, for the panel's start screen |
|
|
135
138
|
|
|
139
|
+
### Design: `design/`
|
|
140
|
+
|
|
141
|
+
The agent's side of Design mode. `extensions/design.ts` installs it (see Extensions below).
|
|
142
|
+
|
|
143
|
+
| File | Owns |
|
|
144
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| `design/index.ts` | `designTools(host)` (`design_preview`, `design_export`, `design_system`), `designGuide(host)` (the prompt section), and `designRoutes(web, host)` (`POST /api/x/design/c/:conversation/export`, steer access) |
|
|
146
|
+
| `design/bundle.ts` | `readBundle`: a version's page and assets from the artifact documents, by hash, in a tool call or a route (no `PocketApp` reader) |
|
|
147
|
+
| `design/render.ts` | Private headless Chromium renders: a process and profile for each render, a loopback endpoint under a random path that serves one bundle, public fetches only, limits (2 at once, 90 s); deck slide size and slides |
|
|
148
|
+
| `design/export.ts` | `saveDesignExport` (shared by the tool and the route): PNG, PDF, PPTX, and the HTML zip, written to `exports/` by default |
|
|
149
|
+
| `design/files.ts` | Where an export may be written: inside the session folder, never through a link, replaced atomically |
|
|
150
|
+
| `design/pptx.ts` | The PPTX writer: one image for each slide, at the deck's slide size (16:9 by default), with the slide's text as speaker notes, through `zip.ts` |
|
|
151
|
+
| `design/system.ts` | `design_system`: the project's `.pi/design-system.md`, bounded, read and written without following links |
|
|
152
|
+
| `design/guide.ts` | The prompt section: how to make designs, and the design system as fenced, untrusted data |
|
|
153
|
+
|
|
136
154
|
### Elsewhere
|
|
137
155
|
|
|
138
|
-
| File
|
|
139
|
-
|
|
|
140
|
-
| `providers.ts`, `net.ts`
|
|
141
|
-
| `public-fetch.ts`
|
|
142
|
-
| `gallery.ts`
|
|
143
|
-
| `gallery/entry.ts`
|
|
144
|
-
| `gallery/files.ts`, `gallery/fetch.ts`
|
|
145
|
-
| `gallery/diff.ts`, `gallery/share.ts`
|
|
146
|
-
| `gallery/themes.ts`
|
|
147
|
-
| `lancet.ts`
|
|
148
|
-
| `omarchy.ts`
|
|
149
|
-
| `themes.ts`, `themes/`
|
|
150
|
-
| `updates.ts`, `update-state.ts`
|
|
151
|
-
| `versions.ts`
|
|
156
|
+
| File | Owns |
|
|
157
|
+
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
158
|
+
| `providers.ts`, `net.ts` | Provider sign-ins, and those that need signing in again (a subscription its provider will not renew); HTTP settings for provider streams |
|
|
159
|
+
| `public-fetch.ts` | `host.fetchPublic`: fetch that reaches only public addresses, checked where each connection is made and at each redirect |
|
|
160
|
+
| `gallery.ts` | The extension gallery (`app.gallery`, `host.gallery`): its index read and kept in the data folder's `gallery/`, downloads checked against their pinned SHA-256, installs (off), updates with a diff, removal, the `<name>.gallery.json` provenance beside each, revoked versions, and Share's draft entries |
|
|
161
|
+
| `gallery/entry.ts` | The index's format, read strictly: entries, file names in the drop-in folder's rules, limits, compatibility, addresses. The index repository's checks import it too |
|
|
162
|
+
| `gallery/files.ts`, `gallery/fetch.ts` | An extension's files in the drop-in folder: names checked, never through a link, a version put in place all or none with an undo journal that `recover` replays before extensions load; reading from other sites, https only, within size and time limits |
|
|
163
|
+
| `gallery/diff.ts`, `gallery/share.ts` | A file's change as a unified diff, for updates; whether a drop-in stands on its own, and the draft of its entry, for Share |
|
|
164
|
+
| `gallery/themes.ts` | Themes from the gallery in the data folder's `themes/`: a version written to a hidden folder, checked with `readTheme`, then put in place in one rename; the `.gallery.json` provenance in each; recovery at the start |
|
|
165
|
+
| `lancet.ts` | Loads Lancet Guard from Pi's install, and downloads its model on request |
|
|
166
|
+
| `omarchy.ts` | The Omarchy desktop's current theme and wallpaper, read-only, for Follow desktop (`/api/theme`) |
|
|
167
|
+
| `themes.ts`, `themes/` | Theme folders (`app.themes`): the built-in ones in `web/themes/` and the owner's in the data folder's `themes/`, read and checked (`themes/format.ts`: `theme.json`, `colors.toml`, limits; `themes/css.ts`: CSS's tokens and the files it loads), each one's last good version, watching, Duplicate, Remove, Edit with Pi |
|
|
168
|
+
| `updates.ts`, `update-state.ts`, `npm-install.ts`, `npm-update.ts` | Updates of Pi Pocket itself (`app.updates`, `host.updates`): how the copy was installed (`installKind`), the newest version (the registry's `latest` for npm, GitHub for the notes and for a git checkout), what stands in the way, packages installed beside the checkout or a package staged beside a global npm install, the move forward or the swap, the restart, and `recover`; `update-state.ts` keeps `.pocket-update/` and the copy kept for a swap back, and the launcher imports it to go back; `npm-install.ts` tells how the copy was installed and whether npm's folders can be written, and `npm-update.ts` stages a version beside a global install |
|
|
169
|
+
| `versions.ts` | Pi Pocket's versions compared, for gallery entries' and themes' `minPocket` |
|
|
152
170
|
|
|
153
171
|
Outside `src/`: `flake.nix` and `nix/` build Pi Pocket with Nix (`nix/package.nix`) and run it as a NixOS service (`nix/module.nix`, with `nix/manage-extensions.sh` to copy declared drop-ins). `nix/tests/` runs only under Nix; `npm test` skips it. The container build is `docker/Dockerfile` and `docker/entrypoint.sh` (with `.dockerignore` for the build context), `docker-compose.yml` runs it, and `.env.example` lists the host-side variables for Compose; [docker.md](docker.md) explains them.
|
|
154
172
|
|
|
155
173
|
## Extensions: `src/server/extensions/`
|
|
156
174
|
|
|
157
|
-
Each default-exports `(host: PocketHost, web: ExtensionWeb) => Extension | Extension[] | void` (`web` adds to the app: [extensions/app.md](extensions/app.md)) and is installed in this order: `prompt` (system prompt, with where Pi Pocket's docs are), `artifacts` (the `artifact` and `artifact_inline` tools: one store, `publish`), `browser` (browser tool and its prompt section; through `host.browsers`), `subagents` (subagent tool and its tasks: anchors, reporters, and the courier that sends waiting reports to the parent together; a subagent runs on its session's model, or one the owner allowed, and the app rebuilds the module when that list changes), `agent-teams` (Agent Teams, off by default: the `team` tool and its prompt section, through `host.linkedSessions`; its browser module `agent-teams.js` describes the tool's calls with `pocket.toolCall`; it imports of Pi Pocket's only types and `model-facts.ts`, a pure helper that formats model facts), `schedules` (schedule tool and its four limits, as settings; installs the schedule task), `background` (the background tool and its one setting, through `host.background`; installs the watch task), `goals` (hook after each answer), `plan` (tool hook and prompt section), `anthropic-subscription` (Claude subscription billing), `guard` (tool hook that asks for approval), `codemode` (codemode tool; a script's calls go through the same hooks), `memory` (memory tool and the prompt section of lessons in force; through `host.memory`), `pip` (PiP's tools, prompt, and follow task, through `host.pip`; only PiP's conversation selects it, as `PocketApp`'s settings leave it out of every other conversation's), `triggers` (the PR and repository watch tasks and the `watch_pr` tool, through `host.watches` and `host.repoWatches`; webhooks need it on), `gallery` (the extension gallery's owner-only routes under `/api/x/gallery/`, through `host.gallery`, and its twice-daily look for revoked versions; it installs `pocket-gallery`, which tells the web app it is on), `session-tags` (Session tags, off by default: its `x.session-tags.tags` document, routes that check ids with `request.sessions()`, and its browser folder `session-tags/`, which uses the session list's extension points; it imports nothing of Pi Pocket's but types, as a drop-in would), `ask-someone` (Ask someone, off by default: the `ask_someone` tool, which saves a draft question in its `x.ask-someone.questions` document; routes to edit, share, and end them; a public page (`web.publicPage`) for one answer through each link; and its browser folder `ask-someone/`; it imports nothing of Pi Pocket's but types), `updates` (Updates of Pi Pocket itself: owner-only routes under `/api/x/updates/`, through `host.updates`, its two settings, the look every 6 hours and the install by itself, and its browser folder `updates/`, the menu row, launcher action, and sheet).
|
|
175
|
+
Each default-exports `(host: PocketHost, web: ExtensionWeb) => Extension | Extension[] | void` (`web` adds to the app: [extensions/app.md](extensions/app.md)) and is installed in this order: `prompt` (system prompt, with where Pi Pocket's docs are), `artifacts` (the `artifact` and `artifact_inline` tools: one store, `publish`, and bundles: `assets`, `removeAssets`, `group`, `kind`), `browser` (browser tool and its prompt section; through `host.browsers`), `subagents` (subagent tool and its tasks: anchors, reporters, and the courier that sends waiting reports to the parent together; a subagent runs on its session's model, or one the owner allowed, and the app rebuilds the module when that list changes), `agent-teams` (Agent Teams, off by default: the `team` tool and its prompt section, through `host.linkedSessions`; its browser module `agent-teams.js` describes the tool's calls with `pocket.toolCall`; it imports of Pi Pocket's only types and `model-facts.ts`, a pure helper that formats model facts), `schedules` (schedule tool and its four limits, as settings; installs the schedule task), `background` (the background tool and its one setting, through `host.background`; installs the watch task), `goals` (hook after each answer), `plan` (tool hook and prompt section), `anthropic-subscription` (Claude subscription billing), `guard` (tool hook that asks for approval), `codemode` (codemode tool; a script's calls go through the same hooks), `memory` (memory tool and the prompt section of lessons in force; through `host.memory`), `pip` (PiP's tools, prompt, and follow task, through `host.pip`; only PiP's conversation selects it, as `PocketApp`'s settings leave it out of every other conversation's), `triggers` (the PR and repository watch tasks and the `watch_pr` tool, through `host.watches` and `host.repoWatches`; webhooks need it on), `gallery` (the extension gallery's owner-only routes under `/api/x/gallery/`, through `host.gallery`, and its twice-daily look for revoked versions; it installs `pocket-gallery`, which tells the web app it is on), `session-tags` (Session tags, off by default: its `x.session-tags.tags` document, routes that check ids with `request.sessions()`, and its browser folder `session-tags/`, which uses the session list's extension points; it imports nothing of Pi Pocket's but types, as a drop-in would), `ask-someone` (Ask someone, off by default: the `ask_someone` tool, which saves a draft question in its `x.ask-someone.questions` document; routes to edit, share, and end them; a public page (`web.publicPage`) for one answer through each link; and its browser folder `ask-someone/`; it imports nothing of Pi Pocket's but types), `updates` (Updates of Pi Pocket itself: owner-only routes under `/api/x/updates/`, through `host.updates`, its two settings, the look every 6 hours and the install by itself, and its browser folder `updates/`, the menu row, launcher action, and sheet, which says in words how the copy was installed and shows the hints that the server gives for a local or npx install), and `design` (Design mode's workspace: its routes under `/api/x/design/` for comments, tweaks, "go back to this one", and the designs list, the `pocket.design-comments` document, the `/design-open` command, and the agent side from `../design/index.ts` (tools, prompt guide, export route); its browser folder `design/` is the canvas: `index.js` sets up the panel, rail button, and launcher action, `state.js` keeps the workspace in one store made at load, `workspace.js` is the picker, toolbar, and modes, `canvas.js` the frame and its bridge, `docks.js` the versions, comments, text edits, and tweaks, `views.js` compare, the variations grid, the slide strip, and present mode, `data.js` what it asks of the server, `parts.js` small pieces, and `style.css`; `devices.js`, `tweaks.js`, `edits.js`, `messages.js`, and `comments.js` are pure helpers; it imports the app's own `/store.js` and `/artifact-bridge.js`).
|
|
158
176
|
|
|
159
177
|
## Web: `web/` (Preact and htm, no build)
|
|
160
178
|
|
|
@@ -179,12 +197,13 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
|
|
|
179
197
|
| `voice.js` | Dictation: the browser's speech recognition into a message box (`useDictation`, words at the caret, the draft kept by the box's own saving), the mic (`MicButton`), and Alt+V (`toggleDictation`, the newest box) |
|
|
180
198
|
| `history.js` | What this browser sent, for ↑ and Ctrl+R |
|
|
181
199
|
| `box-keys.js` | Extensions' keys in the message boxes (`pocket.composerKey`): how a key is written and matched, the box a key's `run` gets, and the rows of the Keyboard shortcuts sheet. `extension-ui.js` gives it what modules added, so the boxes do not import the extensions' code. No imports, so Node tests it |
|
|
182
|
-
| `artifact-bridge.js` | What an artifact's page (or HTML run from a reply) may ask of the app through `postMessage`: a follow-up in the message box for the person to send, and its own saved state (`src/server/artifact-state.ts`); only over the channel the frame's first page opens (`ARTIFACT_BRIDGE` in `src/server/http/artifacts.ts`), while its session shows
|
|
200
|
+
| `artifact-bridge.js` | What an artifact's page (or HTML run from a reply) may ask of the app through `postMessage`: a follow-up in the message box for the person to send, and its own saved state (`src/server/artifact-state.ts`); only over the channel the frame's first page opens (`ARTIFACT_BRIDGE` in `src/server/http/artifacts.ts`), while its session shows Also Design mode's messages: `useArtifactBridge`, `attachBridge`, and `sendToFrame` send the app's modes, pins, tweak values, and slides to the page, and `checkAppMessage` and `checkPageMessage` check each shape and length; the page's answers (`pocket-picked`, `pocket-text-edited`, `pocket-tweaks`, `pocket-deck`) come only from the inspector (`src/server/http/artifact-inspect.ts`). |
|
|
201
|
+
| `taps.js` | Whether a person just tapped or pressed a key (a real event, which a script cannot make): `spendTap`, for actions that must come from a person, such as `pocket.pip.ask` with `send` |
|
|
183
202
|
| `files.js` | `@` mentions: the folder's file list, fetched once and checked in the background, and matched here as people type |
|
|
184
203
|
| `commands.js` | Slash commands (the app's own, and extensions'), and prompt templates |
|
|
185
204
|
| `trust.js` | Project trust: the bar that asks the owner whether to trust a session's project for its own skills and its `.pi/settings.json` model defaults, and the sheet (`/trust`, the menu) that shows and changes the answer |
|
|
186
205
|
| `sheets.js` | Which sheet is open, the component that shows it, and the nested-sheet back action supplied to `Sheet` through `SheetBack` |
|
|
187
|
-
| `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend, running now, schedules, webhooks, memory (the lessons Pi keeps, with the menu's hint), worktree, Pi's terminal sessions, appearance, shortcuts, the menu, a session's actions, the extension gallery (`gallery.js`: browsing, an entry, its source, an update, sharing; `galleryAvailable`)
|
|
206
|
+
| `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend, running now, schedules, webhooks, memory (the lessons Pi keeps, with the menu's hint), worktree, Pi's terminal sessions, appearance, shortcuts, the menu, a session's actions, the extension gallery (`gallery.js`: browsing, an entry, its source, an update, sharing; `galleryAvailable`), with the artifact viewer's **Open in Design** button (`viewers.js`) |
|
|
188
207
|
| `peeks.js` | Peek tiles: their switches (the top bar's and the rail's), which sessions get one and in what order (working, waiting, with subagents at work, finished, or pinned), the column and the strip, each tile's subagents at work (the first few as rows, the rest counted, opening the board at them) and their own peeks, the watch list |
|
|
189
208
|
| `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it |
|
|
190
209
|
| `clock.js` | The server's clock as a tab knows it, without the DOM: how far it is ahead of this browser's, fitted to what each hello proves, so a hello handled late (a tab woken from the background) moves no time shown |
|
|
@@ -261,6 +280,8 @@ The maskable icon places the 352 × 352 artwork on a 512 × 512 page with 80-pix
|
|
|
261
280
|
- Extensions reach the app only through `PocketHost`, and add to it only through `web` (`extension-web.ts`).
|
|
262
281
|
- A part of the web app that reaches a side edge of the screen keeps clear of a phone's notch with `var(--inset-l)` and `var(--inset-r)` (`style.css`; the safe-area insets, 0 on most screens). Give the part the inset, not the layout, so its background still runs to the edge.
|
|
263
282
|
- Server code is erasable TypeScript with `.ts` imports. Comments are plain sentences.
|
|
283
|
+
- The inspector script (`ARTIFACT_INSPECT` in `http/artifact-inspect.ts`) sits in a template string: it has no backtick of its own. The page-to-app Design messages come only from it; the app checks each shape and length and uses the data only as a person's own comment or edit.
|
|
284
|
+
- Artifact assets are served only by name from a version's manifest, never by hash, and each response has the sandbox policy and `nosniff`. A private page reaches them with a signed address that lasts 12 hours; never put it in a stored document, a tool result, or a log.
|
|
264
285
|
|
|
265
286
|
## Tests: `test/`
|
|
266
287
|
|
package/docs/release-notes.md
CHANGED
|
@@ -17,7 +17,7 @@ The notes are for people who run Pi Pocket, and some of them read on a phone. Ea
|
|
|
17
17
|
- **Credit at the end of the bullet**, in parentheses: `(#139, by @vitalNohj)`. For an issue that a person reported: `(#131, reported by @vitalNohj)`. Use "Fixes #N" where the release pull request should close the issue.
|
|
18
18
|
- **Leave out empty sections.** A small release can be a few bullets and the update steps.
|
|
19
19
|
- **Put anything one-way or risky in a `[!WARNING]` alert** at the top. Put needed steps (`npm install`, a restart) in a `[!IMPORTANT]` alert.
|
|
20
|
-
- **The app reads the warning.** Menu → Update Pi Pocket asks the owner to confirm a release whose notes have a `[!WARNING]` or `[!CAUTION]` alert, never installs it by itself, and does not go back from it by itself. So put every step that a person must do by hand, or that cannot be undone, in that alert. Updates run `npm ci` and restart by themselves.
|
|
20
|
+
- **The app reads the warning.** Menu → Update Pi Pocket asks the owner to confirm a release whose notes have a `[!WARNING]` or `[!CAUTION]` alert, never installs it by itself, and does not go back from it by itself. So put every step that a person must do by hand, or that cannot be undone, in that alert. Updates run `npm ci` (a git checkout) or `npm install -g` (a global npm install) and restart by themselves. A release must be on the npm registry's `latest` tag for an npm install to take it, and the notes come from the GitHub release of the same version.
|
|
21
21
|
- **Keep the review story short and folded** in a `<details>` block. Always say what was not tested.
|
|
22
22
|
|
|
23
23
|
## The template
|
package/docs/self-editing.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
People often change Pi Pocket from inside itself. You can run on the server that you change, and so can all the other people who use it. [AGENTS.md](../AGENTS.md) gives the rules in short; this page gives all of them.
|
|
4
4
|
|
|
5
|
-
Change a git checkout only. In a copy installed with npm (in a `node_modules` folder), the next update with npm replaces each edit, and the folder often belongs to another user.
|
|
5
|
+
Change a git checkout only. In a copy installed with npm (in a `node_modules` folder), the next update with npm replaces each edit, and the folder often belongs to another user. An update from the app (Menu → Update Pi Pocket) of a global npm install also swaps the whole package folder, so it removes edits there too.
|
|
6
6
|
|
|
7
7
|
Before you start, read [map.md](map.md) to find the code that you need, and the part of [architecture.md](architecture.md) about it. Say what you will change. Then wait for a yes, unless the person asked for exactly that change.
|
|
8
8
|
|
package/docs/systemd.md
CHANGED
|
@@ -100,7 +100,7 @@ sudo systemctl start pi-pocket@lan
|
|
|
100
100
|
|
|
101
101
|
If the unit file changed, copy it again and run `sudo systemctl daemon-reload` before starting.
|
|
102
102
|
|
|
103
|
-
Menu → **Update Pi Pocket** can also update the checkout from the app, when the service user owns it (`sudo chown -R pi-pocket: /opt/pi-pocket`). With the checkout owned by another user, as in the steps above, the sheet only says when a new version is out. An update from the app does not back up the data folder: for a release whose notes have a warning, back it up first, as above.
|
|
103
|
+
Menu → **Update Pi Pocket** can also update the checkout from the app, when the service user owns it (`sudo chown -R pi-pocket: /opt/pi-pocket`). With the checkout owned by another user, as in the steps above, the sheet only says when a new version is out. A global npm install (`npm install -g pi-pocket`) updates from the sheet the same way, when the service user can write the folder that holds the package. An update from the app does not back up the data folder: for a release whose notes have a warning, back it up first, as above.
|
|
104
104
|
|
|
105
105
|
## When it does not start
|
|
106
106
|
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-pocket",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"lockfileVersion": 3,
|
|
5
5
|
"requires": true,
|
|
6
6
|
"packages": {
|
|
7
7
|
"": {
|
|
8
8
|
"name": "pi-pocket",
|
|
9
|
-
"version": "0.
|
|
9
|
+
"version": "0.26.0",
|
|
10
10
|
"license": "MIT",
|
|
11
11
|
"dependencies": {
|
|
12
12
|
"@earendil-works/chord": "1.4.0",
|
package/package.json
CHANGED
package/src/launcher/main.ts
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { type ChildProcess, spawn } from "node:child_process";
|
|
9
9
|
import { once } from "node:events";
|
|
10
|
-
import {
|
|
10
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
11
11
|
import { homedir } from "node:os";
|
|
12
12
|
import { join, sep } from "node:path";
|
|
13
13
|
import { createInterface } from "node:readline";
|
|
@@ -27,7 +27,12 @@ import {
|
|
|
27
27
|
} from "./access.ts";
|
|
28
28
|
import { fail, parseArgs } from "./options.ts";
|
|
29
29
|
// The one server module the launcher runs itself: it imports only Node's own, so an update cannot break the launcher.
|
|
30
|
-
import {
|
|
30
|
+
import {
|
|
31
|
+
readPending,
|
|
32
|
+
restoreMissingNpmPackage,
|
|
33
|
+
rollBackUpdate,
|
|
34
|
+
stopMeansRollBack,
|
|
35
|
+
} from "../server/update-state.ts";
|
|
31
36
|
import {
|
|
32
37
|
accent,
|
|
33
38
|
bold,
|
|
@@ -319,9 +324,11 @@ function appUrl(): string {
|
|
|
319
324
|
|
|
320
325
|
/** The address a browser on this machine should open. */
|
|
321
326
|
function localUrl(): string {
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
327
|
+
// A specific address, loopback or not, only answers on itself: keep it. `localhost` too, since Node may listen
|
|
328
|
+
// for it on ::1 alone.
|
|
329
|
+
const host = wildcard(state.host) ? "127.0.0.1" : state.host;
|
|
330
|
+
|
|
331
|
+
return `http://${host.includes(":") ? `[${host}]` : host}:${options.port}`;
|
|
325
332
|
}
|
|
326
333
|
|
|
327
334
|
function modeLabel(): string {
|
|
@@ -451,6 +458,13 @@ function maybeShowPanel(): void {
|
|
|
451
458
|
// ─── The server ─────────────────────────────────────────────────────────
|
|
452
459
|
|
|
453
460
|
function startServer(first: boolean): void {
|
|
461
|
+
try {
|
|
462
|
+
restoreMissingNpmPackage(APP_ROOT);
|
|
463
|
+
} catch (error) {
|
|
464
|
+
// A child that cannot load still reaches the normal rollback and retry path below.
|
|
465
|
+
log(red(`Could not restore the live npm package: ${(error as Error).message}`));
|
|
466
|
+
}
|
|
467
|
+
|
|
454
468
|
const args = [
|
|
455
469
|
SERVER,
|
|
456
470
|
"--host",
|
|
@@ -477,6 +491,7 @@ function startServer(first: boolean): void {
|
|
|
477
491
|
PI_POCKET_SUPERVISED: "1",
|
|
478
492
|
PI_POCKET_LAUNCHER: "1",
|
|
479
493
|
PI_POCKET_ROLLBACK: "1",
|
|
494
|
+
PI_POCKET_NPM_ROLLBACK: "1",
|
|
480
495
|
},
|
|
481
496
|
});
|
|
482
497
|
/** This start said it was ready: a stop after that is not a new version that cannot start. */
|
|
@@ -890,10 +905,6 @@ async function main(): Promise<void> {
|
|
|
890
905
|
saveSettings(mode);
|
|
891
906
|
}
|
|
892
907
|
|
|
893
|
-
if (!existsSync(SERVER)) {
|
|
894
|
-
fail(`Missing ${SERVER}`);
|
|
895
|
-
}
|
|
896
|
-
|
|
897
908
|
log(dim(` Starting Pi Pocket (${modeLabel()})…`));
|
|
898
909
|
startServer(true);
|
|
899
910
|
|