pi-pocket 0.28.0-beta.1 → 0.28.0-beta.10

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.
Files changed (201) hide show
  1. package/README.md +4 -4
  2. package/SECURITY.md +1 -1
  3. package/contrib/systemd/pi-pocket@.service +1 -1
  4. package/docs/architecture.md +38 -9
  5. package/docs/customizing.md +29 -3
  6. package/docs/design/design-mode.md +1 -1
  7. package/docs/docker.md +2 -0
  8. package/docs/embedders.md +110 -0
  9. package/docs/examples/clock.ts +3 -5
  10. package/docs/examples/my-words.ts +2 -2
  11. package/docs/examples/quiet-note.ts +4 -4
  12. package/docs/examples/read-page.ts +4 -6
  13. package/docs/extensions/commands.md +1 -1
  14. package/docs/extensions/first-extension.md +2 -2
  15. package/docs/extensions/hooks.md +4 -0
  16. package/docs/extensions/linked-sessions.md +32 -8
  17. package/docs/extensions/policies/api-stability.md +13 -3
  18. package/docs/extensions/policies/core-or-extension.md +1 -1
  19. package/docs/extensions/prompt-sections.md +4 -0
  20. package/docs/extensions/reference/api-versions.md +6 -0
  21. package/docs/extensions/reference/host.md +103 -11
  22. package/docs/extensions/reference/limits.md +2 -1
  23. package/docs/extensions/reference/names.md +1 -1
  24. package/docs/extensions/reference/pocket.md +62 -1
  25. package/docs/extensions/reference/theme-surface.md +10 -2
  26. package/docs/extensions/reference/web.md +80 -1
  27. package/docs/extensions/routes.md +1 -1
  28. package/docs/extensions/services-settings.md +8 -8
  29. package/docs/extensions/sessions.md +37 -0
  30. package/docs/extensions/themes.md +1 -0
  31. package/docs/extensions/tools.md +3 -3
  32. package/docs/extensions/workspaces.md +25 -0
  33. package/docs/extensions.md +7 -2
  34. package/docs/features.md +30 -26
  35. package/docs/index.md +1 -0
  36. package/docs/map.md +103 -86
  37. package/docs/systemd.md +2 -2
  38. package/npm-shrinkwrap.json +190 -58
  39. package/package.json +12 -7
  40. package/src/launcher/access.ts +17 -1
  41. package/src/launcher/main.ts +190 -48
  42. package/src/launcher/options.ts +8 -6
  43. package/src/launcher/serve.ts +151 -60
  44. package/src/server/alerts.ts +44 -16
  45. package/src/server/app-events.ts +11 -1
  46. package/src/server/app.ts +500 -52
  47. package/src/server/background.ts +77 -31
  48. package/src/server/browser/urls.ts +3 -0
  49. package/src/server/build.ts +1 -1
  50. package/src/server/commands.ts +147 -56
  51. package/src/server/conversation-usage.ts +235 -0
  52. package/src/server/custom-providers.ts +721 -0
  53. package/src/server/design/files.ts +10 -0
  54. package/src/server/design/guide.ts +6 -0
  55. package/src/server/design/index.ts +84 -63
  56. package/src/server/design/scan-facts.ts +4 -0
  57. package/src/server/design/scan-fig-container.ts +390 -0
  58. package/src/server/design/scan-fig-kiwi.ts +466 -0
  59. package/src/server/design/scan-fig-nodes.ts +394 -0
  60. package/src/server/design/scan-fig.ts +518 -0
  61. package/src/server/design/scan-files.ts +54 -2
  62. package/src/server/design/scan-import-convert.ts +1 -1
  63. package/src/server/design/scan-import-eval.ts +15 -8
  64. package/src/server/design/scan-import.ts +16 -4
  65. package/src/server/design/scan-infer.ts +10 -1
  66. package/src/server/design/scan-tree.ts +30 -1
  67. package/src/server/design/scan.ts +87 -25
  68. package/src/server/design/system-types.ts +6 -0
  69. package/src/server/design/system.ts +184 -78
  70. package/src/server/design/tokens-resync.ts +542 -0
  71. package/src/server/design/tokens.ts +34 -3
  72. package/src/server/docs.ts +32 -2
  73. package/src/server/entry-format.ts +5 -0
  74. package/src/server/entry-presentation.ts +20 -0
  75. package/src/server/extension-commands.ts +11 -5
  76. package/src/server/extension-document-imports.ts +9 -1
  77. package/src/server/extension-pi-ai-compat.ts +22 -0
  78. package/src/server/extension-request.ts +15 -0
  79. package/src/server/extension-sessions.ts +238 -0
  80. package/src/server/extension-web.ts +38 -4
  81. package/src/server/extensions/agent-teams.ts +56 -36
  82. package/src/server/extensions/anthropic-subscription.ts +6 -4
  83. package/src/server/extensions/artifacts.ts +167 -96
  84. package/src/server/extensions/ask-someone.ts +13 -10
  85. package/src/server/extensions/ask.ts +34 -32
  86. package/src/server/extensions/background.ts +20 -18
  87. package/src/server/extensions/browser.ts +106 -93
  88. package/src/server/extensions/codemode.ts +107 -13
  89. package/src/server/extensions/design/system-routes.ts +9 -2
  90. package/src/server/extensions/diagrams/index.js +344 -0
  91. package/src/server/extensions/diagrams/math.css +1 -0
  92. package/src/server/extensions/diagrams/style.css +42 -0
  93. package/src/server/extensions/diagrams.ts +6 -0
  94. package/src/server/extensions/memory.ts +19 -15
  95. package/src/server/extensions/pip.ts +213 -163
  96. package/src/server/extensions/plan.ts +4 -3
  97. package/src/server/extensions/prompt.ts +17 -9
  98. package/src/server/extensions/schedules.ts +21 -19
  99. package/src/server/extensions/subagents.ts +59 -31
  100. package/src/server/extensions/tool-search.ts +82 -29
  101. package/src/server/extensions/triggers.ts +14 -14
  102. package/src/server/guides/artifact-bridge.md +1 -1
  103. package/src/server/guides/design.md +1 -0
  104. package/src/server/heic-convert.d.ts +11 -0
  105. package/src/server/heic-worker.ts +12 -0
  106. package/src/server/heic.ts +129 -0
  107. package/src/server/hooks.ts +29 -0
  108. package/src/server/host.ts +92 -2
  109. package/src/server/http/api.ts +65 -6
  110. package/src/server/http/assets.ts +13 -0
  111. package/src/server/http/browser-routes.ts +5 -1
  112. package/src/server/http/conversation-routes.ts +24 -5
  113. package/src/server/http/events.ts +5 -0
  114. package/src/server/http/extension-routes.ts +5 -0
  115. package/src/server/http/push-routes.ts +5 -2
  116. package/src/server/http.ts +33 -1
  117. package/src/server/linked-sessions.ts +389 -65
  118. package/src/server/main.ts +15 -0
  119. package/src/server/memory.ts +6 -0
  120. package/src/server/model-images.ts +162 -0
  121. package/src/server/model-refresh.ts +5 -5
  122. package/src/server/paths.ts +8 -0
  123. package/src/server/pi-sessions.ts +261 -51
  124. package/src/server/pip-compact.ts +13 -1
  125. package/src/server/pip.ts +13 -5
  126. package/src/server/projection.ts +11 -2
  127. package/src/server/providers.ts +62 -11
  128. package/src/server/push.ts +10 -0
  129. package/src/server/reload.ts +72 -5
  130. package/src/server/resend.ts +4 -1
  131. package/src/server/room.ts +121 -17
  132. package/src/server/running.ts +309 -4
  133. package/src/server/schedules.ts +5 -0
  134. package/src/server/shell.ts +10 -6
  135. package/src/server/tool-schema.ts +20 -0
  136. package/src/server/watches.ts +8 -0
  137. package/src/server/when.ts +25 -11
  138. package/src/server/workspace.ts +30 -0
  139. package/src/server/worktrees.ts +5 -0
  140. package/types/pocket.d.ts +208 -5
  141. package/web/agent-tile.js +4 -1
  142. package/web/app-icon.js +1 -0
  143. package/web/app.js +47 -12
  144. package/web/back.js +29 -6
  145. package/web/browser-panel.js +13 -25
  146. package/web/browser.js +3 -10
  147. package/web/chat.js +41 -30
  148. package/web/composer.js +379 -121
  149. package/web/diff.js +4 -3
  150. package/web/embedder.js +130 -0
  151. package/web/extension-ui.js +139 -12
  152. package/web/files-panel.js +33 -44
  153. package/web/history.js +10 -12
  154. package/web/home.js +11 -0
  155. package/web/host.js +78 -0
  156. package/web/index.html +50 -0
  157. package/web/launcher.js +11 -4
  158. package/web/markdown-ext.js +45 -0
  159. package/web/math.js +58 -0
  160. package/web/model-refresh.js +30 -20
  161. package/web/notes-drafts.js +129 -0
  162. package/web/notify.js +15 -2
  163. package/web/panel-layout.js +140 -0
  164. package/web/peeks.js +16 -17
  165. package/web/person-storage.js +123 -0
  166. package/web/pip-attachments.js +5 -2
  167. package/web/pip.js +408 -129
  168. package/web/quote-reply.js +113 -27
  169. package/web/quote-text.js +26 -0
  170. package/web/rich.js +1 -1
  171. package/web/running-board.js +1272 -0
  172. package/web/seen.js +3 -2
  173. package/web/session-tabs.js +4 -3
  174. package/web/sessions.js +590 -237
  175. package/web/sheets/all-artifacts.js +104 -0
  176. package/web/sheets/appearance.js +37 -0
  177. package/web/sheets/custom-providers.js +278 -0
  178. package/web/sheets/extensions.js +34 -22
  179. package/web/sheets/find.js +8 -2
  180. package/web/sheets/gallery.js +0 -2
  181. package/web/sheets/hooks.js +112 -5
  182. package/web/sheets/memory.js +41 -2
  183. package/web/sheets/menu.js +13 -1
  184. package/web/sheets/model.js +1 -3
  185. package/web/sheets/providers.js +207 -21
  186. package/web/sheets.js +4 -5
  187. package/web/store.js +674 -83
  188. package/web/style.css +1865 -145
  189. package/web/subagents-board.js +18 -3
  190. package/web/subagents.js +25 -1
  191. package/web/text-hash.d.ts +2 -0
  192. package/web/{fingerprint.js → text-hash.js} +2 -1
  193. package/web/theme-surface.js +7 -0
  194. package/web/theme.js +7 -0
  195. package/web/transcript.js +320 -39
  196. package/web/turns.js +7 -3
  197. package/web/ui.js +245 -30
  198. package/web/voice.js +4 -2
  199. package/web/window-controls.js +330 -0
  200. package/web/fingerprint.d.ts +0 -2
  201. package/web/sheets/running.js +0 -130
package/README.md CHANGED
@@ -52,7 +52,7 @@ The launcher asks how your devices should connect, then prints a sign-in link an
52
52
 
53
53
  While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
54
54
 
55
- **Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 upgrades the database one way, so going back needs the backup.
55
+ **Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 and 0.28.0 upgrade the data one way, so going back needs the backup.
56
56
 
57
57
  ### Other ways to run it
58
58
 
@@ -82,9 +82,9 @@ Choose a mode in the launcher, or pass `--access`:
82
82
  | `tailscale` | Your tailnet | Plain http on the tailnet address |
83
83
  | `tailscale-serve` | Your tailnet | https at the tailnet name; needs `tailscale` 1.52 or newer |
84
84
 
85
- `tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet. It serves port 443 at the machine's tailnet name and takes its mount down when the launcher quits; a server restart keeps the address. Without the command the launcher stops with an install hint instead of falling back to this device only. For another tunnel (ngrok), choose `local` and point it at port 8787.
85
+ `tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet, and, when the launcher does not run as root, that user as tailscaled's operator (`sudo tailscale set --operator=$USER`). It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. `--host` cannot be combined with it: serve always listens on `127.0.0.1` and lets tailscaled reach it. For another tunnel (ngrok), choose `local` and point it at port 8787.
86
86
 
87
- Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_SESSION_CACHE=off` keeps browsers from saving the sessions they open on the device (IndexedDB), so that they keep them in each tab's memory only; it is on by default. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)).
87
+ Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `--host` overrides the address a named mode would listen on, and one launcher runs per data folder (a second one says which pid holds it). `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_SESSION_CACHE=off` keeps browsers from saving the sessions they open on the device (IndexedDB), so that they keep them in each tab's memory only; it is on by default. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)). `PI_POCKET_KEEPALIVE_SECONDS` (default `5`, from `1` to `3600`) is how long the server keeps an idle connection open for its next request. Behind a reverse proxy of your own (Caddy, nginx, a load balancer), set it above the proxy's idle timeout, or set the proxy's below it: otherwise the proxy can send a request on a connection as the server closes it, and answers with a 502. Caddy keeps idle connections for 2 minutes by default, so `PI_POCKET_KEEPALIVE_SECONDS=125`, or `keepalive 4s` in Caddy's `transport http` block.
88
88
 
89
89
  > [!WARNING]
90
90
  > Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. [SECURITY.md](SECURITY.md) says what is protected and what is not.
@@ -118,6 +118,6 @@ The [full list](docs/features.md#limitations) has the details.
118
118
 
119
119
  ## Credits and license
120
120
 
121
- Inspired by [Mario Zechner's demo](https://x.com/badlogicgames/status/2106452296087302173) of his own Pi app. Pi Pocket is an independent project, not affiliated with Earendil. The bundled fonts keep their own licenses, which are beside them in [web/fonts/](web/fonts/).
121
+ Inspired by [Mario Zechner's demo](https://x.com/badlogicgames/status/2106452296087302173) of his own Pi app. Pi Pocket is an independent project, not affiliated with Earendil. The bundled fonts keep their own licenses, which are beside them in [web/fonts/](web/fonts/). Dependencies keep their own licenses too; one is not MIT: HEIC photos are decoded with [libheif-js](https://github.com/catdad-experiments/libheif-js) (LGPL-3.0), installed as an ordinary npm package that you can replace.
122
122
 
123
123
  [MIT](LICENSE). To report a security problem, see [SECURITY.md](SECURITY.md).
package/SECURITY.md CHANGED
@@ -13,7 +13,7 @@ Pi Pocket runs a coding agent that executes commands on the machine it runs on,
13
13
  - **Anyone who can steer can do what you can.** Through Pi, they reach your files, Pi Pocket's settings and tokens, and its code. An invite to one session limits what someone sees in the app, not what Pi can reach. Neither do git worktrees or spend limits: a worktree keeps a session's files apart, and a run is stopped only after the request that crosses its limit.
14
14
  - **Approvals.** Lancet Guard approvals can come from anyone who can steer, including the person who asked, unless the owner turns on "Approvals need someone else" (Menu → Extensions); then, when nobody is known to have asked, only the owner can allow. A notification offers Allow only for a call that fits on one short line; anything longer opens the app first. Since 0.22.0, an extension can ask a question on the same kind of card (a sign-in, a code): only the person Pi works for fills it in, what they type goes to that extension and never to Pi or the transcript, and its notification has no Allow. Values an extension hides show as `[label]` in command output, tool results, and messages to Pi; that keeps them out by accident, not from a command or a model that leaks them on purpose. A "Done when" check command runs after every answer without asking, so with Lancet Guard on it must be one the guard allows outright.
15
15
  - **The built-in browser** reaches what this machine reaches: `localhost`, your network, and the internet. Anyone who can steer can use it from the Browser panel, and Pi from its `browser` tool; Lancet Guard does not check either, and pages can hold whatever they show. The addresses people open show in the session's chat. Its pages run in Chromium on the server, not in your browser, so they cannot reach the app or its cookies. Only the owner opens files from the address bar or sees which servers run on the machine. If steering guests should not reach your network, turn Browser off in Menu → Extensions.
16
- - **Models** are a person's to choose. Pi starts subagents only on their session's model, or on models the owner allowed (Providers → Models for subagents); PiP passes a model only when its person named it; titles and summaries use the session's own model. Subagents on another model, and PiP, ask a model's sign-in afresh first and use none whose sign-in expired; a session's own run, a subagent on its model, titles, and summaries just try the model, and a run that fails on an expired sign-in marks it. This guards spending against Pi's choices, not against a person: anyone who can steer can pick a session's model, and Pi, which runs commands, can reach Pi's sign-ins and Pi Pocket's files like anything else on the machine.
16
+ - **Models** are a person's to choose. Pi starts subagents only on their session's model, or on models the owner allowed (Providers → Subagent models); PiP passes a model only when its person named it; titles and summaries use the session's own model. Subagents on another model, and PiP, ask a model's sign-in afresh first and use none whose sign-in expired; a session's own run, a subagent on its model, titles, and summaries just try the model, and a run that fails on an expired sign-in marks it. This guards spending against Pi's choices, not against a person: anyone who can steer can pick a session's model, and Pi, which runs commands, can reach Pi's sign-ins and Pi Pocket's files like anything else on the machine.
17
17
  - **Linked sessions** (Agent Teams, off until the owner turns it on) widen what prompt injection can reach. A session that read something hostile (a page, a file, an issue) can pass it on to the other sessions of its team in a message, and a message makes Pi work in the target for the person Pi worked for in the sender, with that person's access, in a session where other people may have written. Pi is told to take a linked session's message as a request, not as an order from a person, and to do nothing destructive or with credentials only because one asks; that is guidance to the model, not a boundary. A message is fenced, and a team stops at the starting session's spend limit. Since 0.19.0, no count of messages or sessions stops a team, so set a session budget for a session that starts one; a link gives no access to a session someone cannot already see.
18
18
  - **Plan mode** keeps Pi to planning; it is not a boundary. Programs that people configured to run on their own, such as a git diff driver, run as they would for anyone.
19
19
  - **Drop-in extensions** in `~/.pi-pocket/extensions/` run inside the server with the owner's rights. They stay off until the owner turns them on. One with a browser module also runs code in the app's own page, with the rights of whoever's tab loads it: the owner's alone unless the module opens it to others (never to someone invited to one session). The page's content security policy keeps that code from loading scripts and styles from another site or fetching from one, but code in the page could still send data out in other ways (navigating the page elsewhere, for one): turn on only browser modules you trust, as with the server part. What a module's route throws with `web.error` reaches everyone who may use that route as it is; anything else it throws, only the owner reads. Every file of a web type (`.js`, `.mjs`, `.css`, `.json`, images, and `.woff2` fonts) in a browser module's folder can be read by everyone the module is for. A module's conversation command is offered to everyone who can steer that session, people invited to only that session included, and its handler runs with the owner's rights: treat its arguments as untrusted, and check who runs it. A global command is the owner's alone.
@@ -3,7 +3,7 @@
3
3
  [Unit]
4
4
  Description=Pi Pocket (%i access)
5
5
  Documentation=https://github.com/TannerMidd/pi-pocket/blob/main/docs/systemd.md
6
- Wants=network-online.target
6
+ Wants=network-online.target tailscaled.service
7
7
  After=network-online.target tailscaled.service
8
8
 
9
9
  [Service]
@@ -7,10 +7,12 @@ How Pi Pocket's parts depend on each other, and the orderings the code relies on
7
7
  Pi Durable owns the lasting state of conversations: conversations, entries, tasks, and Pi Pocket's documents (`docs.ts`), in `pocket.sqlite`. People and settings, push subscriptions, uploads, and worktrees are files beside it ([map.md](map.md#data-pi-pocket-or-pi_pocket_dir)). What `PocketApp` keeps in memory about conversations is read back from storage:
8
8
 
9
9
  - At startup, `#recover` reads each conversation's run, agent, chat, subagents, and who Pi works for in it.
10
- - After that, every commit goes through `#committed`, which keeps the memory up to date.
10
+ - After that, every stored commit goes through `#committed`, which keeps the memory up to date.
11
11
 
12
12
  Pi Durable 1.4.0 migrates SQLite storage to schema version 2 when it opens. Older Durable versions cannot open that database. Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.21.0.
13
13
 
14
+ Pi Durable 1.5.0 keeps schema version 2, but it stores `pi.live` at version 3, and its tool and generation tasks at newer versions, as soon as a conversation runs. An older Pi Pocket then does not start on that data folder: it stops with "Document … (pi.live) has newer version 3 than 1". Back up the complete data folder with the server stopped before upgrading to Pi Pocket 0.28.0, and do not go back to an older version with the same folder.
15
+
14
16
  Scheduled messages, PR watches, repository watches, and PiP reports held while PiP is off use durable `sleepUntil()` checkpoints. A sleeping task holds no invocation and resumes at its saved phase when the harness clock reaches its deadline. The task graph includes these tasks with status `sleeping`.
15
17
 
16
18
  Some state lives in this process alone, and a restart forgets it. For example:
@@ -18,7 +20,7 @@ Some state lives in this process alone, and a restart forgets it. For example:
18
20
  - who is connected, typing, or away;
19
21
  - which tool calls wait for approval;
20
22
  - the browser's pages;
21
- - when each run ended, which peek tiles and session-list squares use, and whether its last run failed;
23
+ - when each run ended, which peek tiles and session-list squares use (why a session's last run failed is kept: `pocket.run-failure`);
22
24
  - provider sign-ins in progress;
23
25
  - the edit and write calls Changes found in each session's history, so a look reads only the entries added since.
24
26
 
@@ -47,17 +49,26 @@ The native extension loader registers one scoped resolve hook for drop-in import
47
49
 
48
50
  Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose functions call into the app lazily, and `web`, through which they add routes and a browser module to the app. `ExtensionWebs` (`extension-web.ts`) keeps what each module's version added, which the loader commits once the module installed and removes with it, running its cleanups. The HTTP layer parses a request, checks it, calls a part, and writes the answer; it holds no state of its own beyond invites and the event streams' pollers.
49
51
 
52
+ ## Workspace execution providers
53
+
54
+ `PocketApp` selects the execution environment by the session's working folder. Local folders keep the existing Node environment; URI workspaces use the last registered provider for their scheme. Removal restores the previous registration, and a missing provider fails closed. Resolution checks the provider identity and cancellation after awaited work. Only the owner can use a workspace URI. The provider's module, a drop-in outside the core package, owns host-key trust, connections, remote project context, and cleanup. Files/Git actions and managed worktrees remain local-only.
55
+
50
56
  ## Favorite folders
51
57
 
52
58
  `FolderFavoritesDoc` (`pocket.folder-favorites`) stores each person's ordered favorite working folders in SQLite. `folder-favorites.ts` reads and changes only the signed-in person's list; explicit star/unstar operations run inside one harness transaction, so concurrent devices do not overwrite unrelated changes. The commit coordinator sends each connected client only its person's list as a `folder-favorites` event. `hello.folderFavorites` supplies the initial list and refreshes it on reconnect. The folder picker shows only what the server committed, so a failed save leaves its list as it was.
53
59
 
60
+ ## Ordinary sessions an extension starts
61
+
62
+ `ExtensionSessions` (`extension-sessions.ts`, `app.extensionSessions`, `host.sessions` as `SessionsApi`) starts a top-level session for the person Pi works for in the source, the same kind New session makes. It writes nothing to `linkedFrom`. The owner's list of models for subagents does not apply: a named model must be known and usable now, and a start that names none keeps the default a new session would get. The call's record is an item of `LinkedSessionCallsDoc` under its own token (`session:<source>:<key>`, hashed, apart from the tokens of linked sessions), kept and pruned by `recordOf`, and written in the commit that makes the session. A repeat reads the record first: it returns that session for the record's person, without the checks again. Its first message, when given, goes through `Commands.submit` as that person's own words (a `u:` request id), and a repeat finds that submission. A source past its spend limit, an invited person, a PiP source, and a blank message are refused before anything is made. A message to a session with no model is refused in the creation commit, which then makes nothing. Since 0.28.0, experimental.
63
+
54
64
  ## Linked sessions
55
65
 
56
- `LinkedSessions` (`linked-sessions.ts`, `app.linkedSessions`, `host.linkedSessions` as `LinkedSessionsApi`) starts a session from another and carries messages between them; Agent Teams (`extensions/agent-teams.ts`, off by default) is its only user. A linked session is an ordinary ownerless session in the source's folder. Its session entry's `linkedFrom` names the session that started it, and nothing else follows from it: it is not in `SubagentsDoc`, `parentOf`, or `rootOf`, so it gives no access, and stopping or archiving one leaves the other as it was.
66
+ `LinkedSessions` (`linked-sessions.ts`, `app.linkedSessions`, `host.linkedSessions` as `LinkedSessionsApi`) starts a session from another and carries messages between them; Agent Teams (`extensions/agent-teams.ts`, off by default) is its only user. Pi Pocket's harness settings (`#harnessSettings` in `app.ts`) default Pi's `steeringMode` and `followUpMode` to `all`, unless Pi's settings set them, so every message that waits goes in at one boundary: a team's messages and reports cost the lead one turn, not one each. A linked session is an ordinary ownerless session in the source's folder. Its session entry's `linkedFrom` names the session that started it, and nothing else follows from it: it is not in `SubagentsDoc`, `parentOf`, or `rootOf`, so it gives no access, and stopping or archiving one leaves the other as it was.
57
67
 
58
- - **Whom it acts for.** Each call acts as the person Pi works for in the source (`requesterOf`), with their checks: seeing the source, steering, the turn, spend, and, to start one, access to every session. The source in plan mode starts and sends nothing. A message goes through `Commands.submit` as sent for that person (a `p:` request id), with `[via linked session …]` and the message fenced (`defang`), so its text is never a slash command and Pi reads it as a request; the target's checks apply there too. The transcript knows such a message by that label and fence, not by the words before the fence.
68
+ - **Whom it acts for.** Each call acts as the person Pi works for in the source (`requesterOf`), with their checks: seeing the source, steering, the turn, spend, and, to start one, access to every session. The source in plan mode starts and sends nothing. A message goes through `Commands.submit` as sent for that person (a `p:` request id), with `[via linked session …]` and the message fenced (`defang`), so its text is never a slash command and Pi reads it as a request; the target's checks apply there too. It steers (lands at the target's next tool round) unless `send` is told `steer: false`. The transcript knows such a message by that label and fence, not by the words before the fence.
69
+ - **Its end of run reports itself.** `LinkedSessions.watch` listens to `run.ended` (`app-events.ts`): a linked session's own run (not a subagent's) sends its lead, unless archived, one message through the same path, keyed `run-end:<outcome>:<last entry id>` so a run reports once and a replay finds it: its newest assistant entry's text (`MAX_REPORT` characters at most), its failure line, or that it was stopped. The words before the fence say which. A report the lead cannot take becomes a notice there. Only that route reports itself: a message's preface promises it only when the source started the target (`#leads`), and otherwise asks for a reply; `send` returns that as `answers`, and the `team` tool tells Pi. The listener runs after the commit that ended the run, in this process: a crash between the two loses that report.
59
70
  - **Once.** Each call's key is hashed with the source into an item of `LinkedSessionCallsDoc` (`pocket.linked-session-calls`), which records the session it made or messaged, whom it acted for, and when. A start writes it in the same commit as the session, then sends the first message; a message's request id is made from the same hash, so a replay finds the session and the message it made. Records are kept 30 days, and the newest 1000.
60
- - **Bounds.** A linked session starts none. Since 0.19.0 no count limits how many a session starts (before, at most 10, counted in the commit that made one). `LinkedSessionRelayDoc` (`pocket.linked-session-relay`) on the team's top session counts messages between its sessions, and a person's own message in any of them (`Commands.submit` without a `via`) sets it back to 0. It is counted in a commit before each message goes, so it survives a restart. Since 0.19.0 no send is refused on that count (before, past 20 were). `Spend` counts a team against its top session's budget: the top session, every session linked under it, and their subagents.
71
+ - **Bounds.** A linked session starts none. Since 0.19.0 no count limits how many a session starts (before, at most 10, counted in the commit that made one). Before 0.19.0 `LinkedSessionRelayDoc` (`pocket.linked-session-relay`) counted messages between a team's sessions and refused past 20; since 0.28.0 nothing writes it (its definition stays, for the stored copies). `Spend` counts a team against its top session's budget: the top session, every session linked under it, and their subagents.
61
72
  - **What it shows.** Sessions know each other by addresses of their own (`LinkedSessionPeersDoc`, `pocket.linked-session-peers`), so no session id goes into a shared transcript; a fork starts with none. `list` reaches only the sessions the person sees, and names them only when everyone who sees the source sees them too. The session list (`PocketApp.sessions`) gives someone who cannot see the origin `linkedOrigin: true` in place of `linkedFrom`; a scoped person's tabs get their own list in every broadcast, not a filter of everyone's.
62
73
  - **Models.** A start copies the source's agent settings (model, thinking, instructions, tools), not its history. It takes only a model on the owner's list for subagents (with no list, only the source's model); a start that names none gets the source's model when it is listed, and is refused when it is not (`ChooseModelError`: Pi must choose from the list, which the error gives). At the thinking level of the source unless the start names another (any level; the model's nearest lower one when it lacks it), and only after `Providers.problem` asks its provider afresh: nothing is made with a model that is not allowed or cannot be used now.
63
74
 
@@ -71,12 +82,14 @@ Subagents leave Agent Teams out of every subagent (`extensions/subagents.ts`), e
71
82
 
72
83
  PiP (`pip.ts`) is a conversation with a `pip` mark in its session entry, which `sessions()` leaves out of every list. The harness settings select every installed extension but PiP's (`pocket-pip`) by default; PiP's conversation stores its own selection (`PIP_EXTENSIONS`, without bash, write, or edit), which `ensure` sets again each time it opens, so PiP's tools reach no other conversation. Its tools act through `Commands` and `Schedules` as PiP's person, with that person's checks, so `canSee` keeps every PiP from everyone but its person: anyone who could write to it would act as them. Its messages to sessions are once per tool call (a request id hashed from the call's key), and each follow leaves a mark in its list (`FollowsDoc`) when it reports or is stopped, so a replayed call neither sends nor follows twice. A tab's PiP panel is a second client in PiP's room (`setPip`), whose `view` events reach the tab as `pipview`; `watching` counts it, so PiP's answers push nothing while it shows.
73
84
 
74
- PiP's header model chip opens the existing picker with its own conversation ID and live view, not the session behind it. Its `pipPanel` configure request uses `Commands.configure`, checks private PiP ownership, and checks `LiveDoc.run` and compactions in the same commit as the model/thinking write. It leaves `lastModel` alone. Ordinary configure requests, including **Open as a conversation**, retain their behavior.
85
+ PiP's header model chip opens the existing picker with its own conversation ID and live view, not the session behind it. Its `pipPanel` configure request uses `Commands.configure`, checks private PiP ownership, and checks `LiveDoc.run` and compactions in the same commit as the model/thinking write. It leaves `lastModel` alone. Ordinary configure requests, including PiP opened as a board, retain their behavior.
75
86
 
76
87
  ## Work from outside the app
77
88
 
78
89
  A PR watch (`watches.ts`) is a `WatchDoc` in its session and a durable task there, which sleeps until its next look, looks with `gh` (`watches.gh`, which tests replace), and puts what to tell Pi in its checkpoint before sending it: the send's request id is the watch's task and count, so a restart sends it once. Comment ids told, and the commits whose failures and conflicts were told, stay in the watch. Webhooks (`hooks.ts`) are app-wide (`HooksDoc`); `/hook/…` is outside `/api` and its sign-in, and lets a post in only by its hook's secret. Both send through `Commands.submit` as their person, with a `via` that marks the message (`[via PR watch]`, `[via webhook NAME]`), so that person's checks and spend limit apply, and what came from outside is fenced (`fence.ts`, as PiP's session text is): no closing tag survives inside, in any case or spacing. A hook's address and secret are checked before its body is read. A signed hook (`signed`, for GitHub) lets a post in only by GitHub's signature: its secret is never in its address, so the address GitHub shows a repository's admins cannot post. Pi's `watch_pr` names a PR by number, which `gh` finds in the session's own repository, or one elsewhere by address only where `gh`'s account can push (`requirePush` in `github.ts`); what follows `--` is never an option.
79
90
 
91
+ Webhook edits require steering rights. `Hooks.update` checks creator-or-owner access in the same transaction that changes the instructions, leaving the hook's other fields unchanged. Deliveries already in progress keep their original instructions.
92
+
80
93
  A repository watch (`repo-watches.ts`) is an item of the app-wide `RepoWatchesDoc` and a durable task in the conversation it messages (PiP's, or a session's), with the same wait, look, and send phases as a PR watch: a look puts the message in the task's checkpoint, and the send's request id is the task's and its count's, so it goes once. It reads the repository's issues, pulls, workflow runs, releases, and comments through `gh api`, and keeps the ids it told. PiP's tools (`repo_watch`, `session_watch_pr`, `session_start` with `repo`) act through `Pip` as its person; a repository is worked on or watched only where `gh`'s account can push, and `Pip.checkout` finds a session's checkout whose `origin` is the repository, or clones it once into `repos/`.
81
94
 
82
95
  ## Who chooses models
@@ -90,6 +103,8 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
90
103
  - **PiP** passes a model, or names one in what it sends, only when its person named it in their own words (`pip.ts`, with `model-names.ts`): their own messages (`u:` request ids, from the authors document) since PiP's last new context (with those its last compaction kept), and the standing instructions of the watches and webhooks to PiP that they set up; never a watch PiP set up, what was posted, or what GitHub said.
91
104
  - **Sign-ins:** `Providers` asks subscriptions' sign-ins afresh (the owner's Providers sheet, a model a subagent on another model or PiP is about to use, a run that failed on one, a run answered by a marked one) and keeps, in memory, the ones their provider refused to renew. Only subagents on another model (`resolveModel`, `modelProblem`), PiP, and linked sessions as they start (`Providers.problem`) check before use, and refuse their models. Everything else tries the model: a session's own run and a subagent on its session's model fail where people see them, and a run that failed on an expired sign-in marks it; a title that fails is only logged. `modelList` and `agentInfo` mark them, and the owner is told. A check that began before a sign-in or sign-out here marks nothing.
92
105
 
106
+ **OpenAI-compatible endpoints.** `app.customProviders` (`custom-providers.ts`) is the owner's only (`/api/custom-providers`, `requireOwner`). Changes run one after another. Each reads Pi's `models.json`, refuses to rewrite one that is not plain JSON or that Pi's own check (`ModelRuntime.create({ refreshOnCreate: false })`) refuses, writes the whole file at once (temporary file, rename, mode 600), then reloads only that provider (`models.refresh({ providers: [id], allowNetwork: false })`) and sends `models`. It manages only entries with `api: "openai-completions"`, a `baseUrl`, and an id that is not built in; it keeps fields it does not set. A key goes through `models.login(id, "api_key")` into `auth.json`, never into `models.json`; an endpoint without a key gets `apiKey: "none"`. Discovery reaches any address, a private one too, because only the owner can ask, and such servers are often local; its errors are fixed messages, never the fetch error, which can carry the key.
107
+
93
108
  **Manual model refresh.** `Providers.modelRefresh` (`model-refresh.ts`) shares one in-flight refresh across owner tabs. `POST /api/models/refresh` requires the owner and the normal `X-Pocket` header; `hello.server.refreshModels` gates the UI against an older server. It checks local configuration with Pi’s public runtime API before reloading it, then refreshes each configured provider in parallel with a separate eight-second limit and `force: true` (network stays off under `PI_OFFLINE`). Each completed provider sends the existing `models` event and refreshes room views, so a slow provider does not hold back a healthy one. Pi owns cache publication and cancellation generations; failed catalog fetches keep its cached/static models. Refresh never configures a conversation or changes the default or subagent allow-list. Counts compare available provider/id keys before and after; provider errors are safe fixed messages, not raw exceptions that could contain credentials.
94
109
 
95
110
  `PocketApp.modelList` resolves Pi’s `enabledModels` through the SDK’s `resolveModelScopeWithDiagnostics` against available models, then `modelList` marks scope membership alongside sign-in state. Both `hello` and providers’ `models` updates use that list. Manual refresh rereads Pi settings before recomputing the scope; malformed scope values are ignored so the picker still opens. The model picker’s Scoped / All state lasts only while it is open and filters the list without changing Pi’s settings, the session’s model, or its default. Empty scopes mean all available models, not a ban on picking models.
@@ -153,6 +168,8 @@ Pi Durable publishes each commit's changes in no set order. `#committed` handles
153
168
  - Document changes go to `#documentCommitted`. It tracks busy and ended runs, agents, the session list, and the documents the rooms show (`ROOM_DOCS`).
154
169
  - Submissions go to `attribution.submissionCommitted`.
155
170
 
171
+ It gets each commit once it is stored (`Harness.observeCommits`). Since Pi Durable 1.5, a partial answer and running tool output are stored later than they are shown: with the next commit that reads `pi.live` (the end of the answer, a tool that settles, the end of a run), and at the latest after `settings.progress.persistWithinMs` (1 second). A room's watch of its conversation's view (`Conversation.watch`) shows each at once. A crash loses up to about a second of a streamed answer. Pi Durable detaches an observer that throws, so `#committed` catches what one commit throws, and the app keeps hearing of the next ones.
172
+
156
173
  Everything here is synchronous. A commit listener may not call the harness's session APIs, so a write it causes (noting a message's author, or moving a session up the list when Pi starts work there) runs in `setImmediate`. Keep this one coordinator: separate listeners would make their registration order a billing rule nobody can see.
157
174
 
158
175
  Updates to tabs are coalesced:
@@ -169,14 +186,18 @@ The message Pi is writing goes as what changed since the tab's last update (`liv
169
186
 
170
187
  A tab's connection names what its code understands (`p`, `PROTOCOL` in `web/store.js`). 2 keeps the queue when an update leaves it out; 3 takes the message as what changed; 4 takes a full view with only the newest entries; 5 takes them light at first; 6 names what it kept of the session and takes the order as what comes after it. A tab below 3 gets the whole message with each update, and one that names none (older code, as a tab asleep through an update keeps) also gets the queue with each update, because its code drops a queue that an update leaves out.
171
188
 
189
+ A room keeps the active context's entries itself. Since Pi Durable 1.5, a conversation's view holds only a window of the newest 50 to 100 entries of the whole history. The room reads the active context from `Conversation.context()` as it opens, after each new head marker (a compaction, a reset), and when the window no longer reaches the newest entry the room has. Between these reads, it adds the entries the window adds.
190
+
172
191
  A full view for a tab of protocol 4 has the order of every entry in the active context, but only the entries of the newest 80 rows (`firstEntries` in `projection.ts`), with the turn the oldest of them is in, so the tab knows which groups are open there. The tab draws 60 of the rows, and the panel for PiP draws 80. Earlier entries come from `GET /api/c/<id>/context?before=<entry>`, with `rows=<n>` or `from=<entry>` (`Room.entriesBefore`, `loadEarlier` in `web/store.js`), when the person shows earlier messages, opens Find, or jumps to a message that is not loaded yet. The server marks the entries it left out as sent, so an update does not send them. A full view of the same session, as after a reconnect, keeps the entries the tab loaded. A session of 6,000 entries was one event of 8 to 10 MB: on a phone, the tab stopped for most of a second each time to read it, and only its last rows are drawn.
173
192
 
174
193
  A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
175
194
 
176
- A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/fingerprint.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
195
+ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/text-hash.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
177
196
 
178
197
  The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
179
198
 
199
+ Browser drafts, and the panel each session last showed (`pocket.person.<person>:layouts`; the tab's copy in `sessionStorage` names its person too), use `web/person-storage.js`: `pocket.person.<person>:…` keys, readable after `/api/me` or an event-stream hello identifies the person. An account signal invalidates answers already on their way, including at startup. Sign-out stops the device cache and attachments before the server request; after it finishes, it clears this storage, changes `pocket.person`, broadcasts the account change, and goes to `/`. Other tabs stop their cache on the early `pocket.signedOut` signal, but reload only on the completed account change. On Back, a cover checks `/api/me` before reconnecting; the same person keeps the document and drafts. Each check has a 10 s timeout; failures retry with backoff up to 30 s, or at once with Retry.
200
+
180
201
  A tab whose server says it can (`hello.server.switches`) goes to another session on the connection it has: `POST /api/switch` with the connection id its `hello` carried, the session (`c`, none for the list), what it kept of it (`have`, as above), and a number (`seq`) that grows with each switch, so the server drops one that arrives after a newer one (`PocketApp.switchTo`). The server takes the tab out of the old session's room, answers `switched` with that number, and sends the new session as a new connection gets it (`#enter`): its view, chat, notes, and browser. A connection opened anew sent its person's profile, the session list, and PiP's state again, and its person left the app and came back in every other tab's list of who is here, and the session showed "connecting" until all of it came. Until `switched` comes, the tab drops events about a session (its view, chat, notes, people, browser, and missing): the server sent those of the session it left before it heard of the switch. A view or `missing` of another session than the one shown is dropped too. A switch the server cannot take (the connection closed, or the server started again) opens a new connection, which names the session, as before; a server without `switches` gets that too.
181
202
 
182
203
  The session list goes to a tab only when it differs from the one that tab last got (`Client.sessionsSent`): it is large, and it is worked out again for many changes that leave it as it was.
@@ -252,9 +273,11 @@ In the browser, the composer keeps a command's request id while its send is unre
252
273
 
253
274
  Plain ES modules, served as they are, with no build. Editing a file under `web/` reloads every open tab, and a syntax error blanks the screen for everyone.
254
275
 
276
+ **Markdown's extension points (`markdown-ext.js`, `math.js`).** `pocket.fence` and `pocket.mathInline` let a browser module draw code fences and set math. `extension-ui.js` fills in the two lookups and `ui.js` asks them, so neither imports the other; a revision that goes up on every change draws Markdown again. Math is parsed only while a `mathInline` registration is live, and each formula reaches the mounter through a random marker that exists for one parse, so reply HTML cannot impersonate math. The built-in `extensions/diagrams/` module registers a Mermaid fence, a math fence, and the math mounter; Pele and KaTeX load from `/vendor/` on first use.
277
+
255
278
  **Loading order matters.** `store.js` is the root, and a few modules do work when they load (listed in [map.md](map.md#web-web-preact-and-htm-no-build)). `theme.js` must load before anything that reads `prefs()` as it loads. `store.set` calls subscribers in the order they subscribed. When moving code between modules, keep both orders. `back.js` sits under `store.js` and imports nothing of the app's, so anything may use it.
256
279
 
257
- **Drawing while an answer streams (`app.js`, `ui.js`).** Every `store.set` draws the app again from the top, once per microtask; components read `store.state` as they draw. A streaming answer changes `view` (or PiP's `pipView`) several times a second, and the chat, people, and the connection change too, so what is big and reads little of the store is wrapped in `drawnFor(keys, component)`, which draws it again only when one of `keys` changes: the session list and the rail (`LIST_KEYS`, `RAIL_KEYS` in `sessions.js`). Its keys must name every key it reads as it draws, and every key that the functions it calls read (`prefs()` reads `appearance`, `canSteer()` reads `me`, `isPinned` reads `pinned`); a key left out shows stale data until another change draws it. `store.set({})` still draws it. Inside the list, each row is memoized (`memo`, compared by its props): the list works out what a row shows and passes it, the row reads nothing of the store, and a minute tick (`useMinute`) and `extensionsRev` draw rows again as their times and extensions' chips change. The server sends `hello`, the session list, and the people again on each connect: their handlers keep what is the same (`kept` in `store.js`), and set nothing when nothing changed, so a reconnect draws only what changed. The server's clock in `hello` (`server.now`) is no change: it goes to `serverClockOffset()`. On narrow screens the sidebar and the home screen's splash are not drawn, and on touch screens rows draw no hover buttons (`WIDE`, `NO_HOVER` in `ui.js`, the same queries as `style.css`; a change draws the app again). Markdown still growing (`cache={false}`) is drawn block by block (`liveBlocks`): each top-level block keeps its HTML from the update before unless its text changed, so an update parses, sanitizes, and colors only the last block. The blocks are found again in the whole text each time, so a later line that changes an earlier block shows; a reference link defined in another block shows as written until the text is whole, and an HTML block with a blank line inside it shows split until then.
280
+ **Drawing while an answer streams (`app.js`, `ui.js`).** Every `store.set` draws the app again from the top, once per microtask; components read `store.state` as they draw. A streaming answer changes `view` (or PiP's `pipView`) several times a second, and the chat, people, and the connection change too, so what is big and reads little of the store is wrapped in `drawnFor(keys, component)`, which draws it again only when one of `keys` changes: the session list and the rail (`LIST_KEYS`, `RAIL_KEYS` in `sessions.js`). Its keys must name every key it reads as it draws, and every key that the functions it calls read (`prefs()` reads `appearance`, `canSteer()` reads `me`, `isPinned` reads `pinned`); a key left out shows stale data until another change draws it. `store.set({})` still draws it. Inside the list, each row is memoized (`memo`, compared by its props): the list works out what a row shows and passes it, the row reads nothing of the store, and its time ago (`ago`), a minute tick (`useMinute`, only for a row that shows a call's age or a limit's time), and `extensionsRev` draw rows again as their times and extensions' chips change. A press on a row is the row's own state, so it draws that row alone. Hundreds of rows make every restyle and layout costly: a row out of sight is neither (`content-visibility: auto`), a drag of a window's edge sets that window's width only (`dragWidth`), and nothing sets a variable on the page's root, or a class there that `*` matches, at each move or press, as every element would be styled again. They make drawing them costly too: as the list's rows change wholly (it opens, another tab, a search starts or ends), it draws a screenful at once and the rest a few dozen at each frame (`firstRows`, `ROWS_PER_FRAME`), opening (or another tab) scrolled down to where it was; a search's matches past the screenful wait until the typing pauses. The list keeps each row's element from its last draw (`drawnRows`) and gives it again while the row's session and place and what all rows read are as they were, so Preact passes over it. A search keeps the list's own groups as they were, out of sight (`Kept`, `.kept`, `content-visibility: hidden`), and draws its matches beside them, so its end shows them again at once; the browser marks what matched (`::highlight(session-search)`, `searchMarks`), and a key draws again only the rows that come and go. The server sends `hello`, the session list, and the people again on each connect: their handlers keep what is the same (`kept` in `store.js`), and set nothing when nothing changed, so a reconnect draws only what changed. The server's clock in `hello` (`server.now`) is no change: it goes to `serverClockOffset()`. On narrow screens the sidebar and the home screen's splash are not drawn, and on touch screens rows draw no hover buttons (`WIDE`, `NO_HOVER` in `ui.js`, the same queries as `style.css`; a change draws the app again). Markdown still growing (`cache={false}`) is drawn block by block (`liveBlocks`): each top-level block keeps its HTML from the update before unless its text changed, so an update parses, sanitizes, and colors only the last block. The blocks are found again in the whole text each time, so a later line that changes an earlier block shows; a reference link defined in another block shows as written until the text is whole, and an HTML block with a blank line inside it shows split until then.
258
281
 
259
282
  **Themes (`themes.ts`, `theme.js`).** The page has three cascade layers, declared in `index.html`: `pocket` (`style.css`, imported into it, and extensions' stylesheets, which `pocket.style()` imports into it after), `palette` (the colors' variables, a `<style>` that `theme.js` writes), and `theme` (a theme folder's stylesheets). A later layer wins whatever the specificity, and an earlier layer's `!important` wins over a later one's, so a theme overrides the app's rules but not its reduced motion. Inline values beat every layer: only what a person sets (the text size, dragged widths, the desktop's wallpaper) is inline, never a palette. A stylesheet added outside the layers (a `<link>`) would beat the app and the theme alike.
260
283
 
@@ -278,7 +301,13 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
278
301
 
279
302
  **PiP chat (`pip.js`, `pip-attachments.js`).** The panel's uploads, submits, image thumbnails, and Markdown image paths use its own conversation ID, never the session behind it. The browser-only attachment draft outlives panel mounts, scopes itself to account and PiP ID, and holds upload identities and submit tokens so late callbacks cannot restore removed files or clear newer drafts. Unknown authentication or conversation IDs during reconnect are not a scope change. Files survive closing and reopening the panel, not a page reload; text keeps its existing local-storage draft. The normal upload and submit endpoints retain their size, file-access, and image-capability checks; PiP does not choose another model for an attachment. Opening the pending-memory sheet uses the private PiP ID even on Home. Panel cleanup restores focus only if it is still in the outgoing panel or on the body, not when a destination sheet already took it.
280
303
 
281
- **PiP resize (`pip-window.js`).** Resize uses pointer capture on the same edge/corner zones for mouse and touch, at widths of 768px and above. The preferred size is local to the account/browser; CSS clamps it to the viewport without overwriting it.
304
+ **A session's send on its way (`composer.js`).** The box keeps no send of its own: `onTheWay` holds each conversation's message, `!` command, or command on its way (`beginSend`, `endSend`), so a box shown again meanwhile holds it read only and cannot send it twice. Its words and files stay in the draft until it went, and meanwhile its words are all the draft holds: what comes for the box waits until it ended: an insert in the store, and a queued message taken back (Edit) in the person's storage (`keepBack`), which a box of its conversation takes once no send is on its way there, also after a reload or a move. One taken back during a send waits until that send ended (`endSend`), or, in another tab or after a reload, until its request id is gone: before, the box's words may go again with that id. Once it went, the draft empties (unless another tab wrote it since), and a file added meanwhile stays. A failure leaves them, and gives the quote back (`giveBackQuote`). Every send of the box that the server runs (a message or template, a `!` command, an extension's command) has one request id for its conversation and exact message (`requestFor`: its kind, words, and files, and its quote when it has one, since a reload loses the quote), kept with the draft in the person's storage until it went. Sent again before, from a box shown again or after a reload (no answer came, or one that does not say: a 5xx, or one that `answered` in `store.js` cannot read), it reuses that id, and the server gives back the first submission, task, or run (`Commands.submit`, `ShellRequestsDoc`, `CommandRequestsDoc`). A 4xx refusal keeps the id: the server stored nothing for it, and a first send that went may be behind it. A 2xx (also an extension's command that ran and failed) ends the id, and so does a change of the words in the box (`edit`): the same words then are a new request, and run again. Sign-out clears it with the draft.
305
+
306
+ **Shared notes drafts (`notes-drafts.js`, `chat.js`).** `personStorage` keeps `{ text, base }` per person and conversation; sign-out clears it and an account change clears the helper's memory. The original revision survives reload, so newer shared saves still require **Use theirs** or **Keep mine**. Blocked or full storage keeps edits in memory with a reload warning. Save, Cancel, and **Use theirs** remove the saved edit or its last stored value after a failed write, never a newer draft from another tab. Failed cleanup shows a warning. A pending save locks its original draft across panel mounts; the textarea stays focused and read-only.
307
+
308
+ **PiP's place (`pip.js`, Appearance → PiP).** Floating, `openPip` sets `pipOpen` (and `OPEN_KEY`, and tells the server, which sends `pipview` only while it is on), as before. With `pip: "board"`, PiP is its own conversation opened as a session is: `openPip` gets PiP's id (asking the server once, with no `pipview`, when the tab does not know it) and calls `navigate`, clearing the drawer, page, and launcher, and the sheet unless the setting's own sheet moved it. `pipBoard()` is true while the route is PiP's conversation (`showsPip`, as its view says, or PiP's id once known) with no board or page over it; `pipShown()` (either place) drives the rail button, the unread mark, and `togglePip`. The session's top bar gets a fixed `core:pip-close` × while `pipBoard()`. The route it was opened over is kept on PiP's history entry (`navigate(id, { over })` → `pushRoute`, read back into `store.state.over` on each route), so it holds through back and forward and a reload; `closePip` goes back there with `navigate(id, { back: true })` (`popRoute`, `back.js`), which steps history back past PiP's entry, so none is left for back to open again, and keeps a sheet still open (Appearance) over that route; or home when the entry has none (the address typed). While a route is `over` a session, `openId()` (not `conversationId`) is the session the list, the folded rail, the tabs, peek tiles, the launcher, and Alt+arrows treat as open, so the one under PiP stays marked, as under Running now. PiP has one message box: on its board the session's place draws PiP's own `Composer` (`PipBoardBox`, with the messages that wait over it and the status line under it) instead of the session composer, on the same `composerDraft` (words, files, the send on its way), so a move changes nothing in it. Text for PiP (`openPip(text)`) goes into it as `pipDraft`, in either place; on the board it also takes what `insertIntoComposer` puts in that place's box (`takeInsert`, which gives each insert to one box). PiP's quote (Ask PiP, or Reply on its board) is one, `pipQuote`, over that box, while the session's own Reply quote (`replyQuote`), the only one the session composer shows, waits under the board as long as `openId()` stays that session. A send takes its quote out of its box as it starts (`dropQuote`, by identity) and gives it back if it fails and nothing took its place (`giveBackQuote`), so no box offers a quote on its way. A board open waits for the tab to know its person and connection, and opens nothing if the person went elsewhere or chose Floating meanwhile. Another board, page, or session simply takes the route. A store subscriber moves PiP when the setting changes, after the change reaches every listener and only if the setting is still the same: to the board it closes the floating panel and navigates; to the corner it navigates away first, then opens the panel; `PipHost` draws nothing while `pipBoard()`, so never both places. A floating `pipOpen` kept across a reload is dropped when the setting says Board. PiP turned off in Extensions closes the board, as it closes the panel; PiP's conversation keeps no panel layout (`followLayout`, `store.js`), so it opens again as PiP, not under a panel left open. The panel no longer has an **Open as a conversation** button: Board is that view. Its **Pending memories** strip (`PendingMemories`, `sheets/memory.js`) shows in both places, only while something waits (or a restart is needed to list them): PiP's box draws it, in both places.
309
+
310
+ **PiP resize (`pip-window.js`).** Resize uses pointer capture on the same edge/corner zones for mouse and touch, at widths of 768px and above, for the floating window only. The preferred size is local to the account/browser; CSS clamps it to the viewport without overwriting it.
282
311
 
283
312
  **Extensions hub (`sheets/gallery.js`).** For owners with the gallery on, Extensions and the gallery share Discover, Installed, and Updates. The hub keeps one listing for its cards and embedded detail; `ExtensionsContent` supplies built-in and local module controls. Its list and entry sheet routes retain the same component so phone Back preserves search. Trail keys do not depend on whether the gallery is enabled: turning it off falls back to standalone management without adding another Back step. Source and update reviews stay separate sheets; updates still bind approval to the displayed pin and enabled state.
284
313
 
@@ -1,6 +1,6 @@
1
1
  # Changing how Pi works, without code
2
2
 
3
- Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi. So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
3
+ Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi, except Pi's extensions ([below](#pis-extensions-and-packages)). So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
4
4
 
5
5
  ## Instructions for one session
6
6
 
@@ -23,6 +23,17 @@ Pi's `configuration.md` gives the full list of names, with `AGENTS.override.md`.
23
23
 
24
24
  Keep the files short and true. They go with each request, and a rule that Pi cannot obey is worse than no rule.
25
25
 
26
+ ## PiP's instructions
27
+
28
+ PiP has no project, so it does not read AGENTS.md files. Write the rules for PiP in `pip.md` in Pi Pocket's data folder: `~/.pi-pocket/pip.md`, unless `--data` or `PI_POCKET_DIR` names another folder (since 0.28.0).
29
+
30
+ - PiP gets the file with each message. When the file changes, the next message has the new text.
31
+ - Only PiP reads it: sessions, subagents, and Pi's terminal app do not.
32
+
33
+ ## The language agents write in
34
+
35
+ Since 0.28.0, agents write to each other in the language of the person they work for: PiP to the sessions it starts or messages, a session to its linked sessions and its subagents, and each answer back. A session you open later, that PiP or another session worked in, reads in your language, with no setting. PiP takes the language from your messages to it, and for a watch, a webhook, or a schedule from the instructions you gave it. In English they write Simplified Technical English (ASD-STE100); in another language, the same short, plain style. Their answers to you follow your own messages, as before. To choose another language for PiP's messages to sessions, say so in `pip.md`.
36
+
26
37
  ## Skills: procedures that Pi follows on request
27
38
 
28
39
  A skill is a folder with a `SKILL.md`: a name and a description at the top, and the steps below. Its name and description go into the system prompt. Pi reads the rest when a task matches it, or when a person sends `/skill:name what to do`.
@@ -54,11 +65,22 @@ Use a template for a message that people send often. Use a skill for steps that
54
65
 
55
66
  ## Models and providers
56
67
 
57
- People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add a model or a provider that Pi does not know, follow Pi's `models.md` and `custom-provider.md`.
68
+ People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add an OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, a proxy), the owner taps **Add** on the **OpenAI Compatible** row in Providers: a name, a base URL, an API key (or **No key**), and models picked from the endpoint's list (**Find models**) or typed by hand. Pi Pocket writes the endpoint into Pi's `models.json`, which it makes, with its folder, when missing, and keeps the key in `auth.json`. **Edit** and **Remove** change it later. A `models.json` with comments, or one Pi refuses, is left alone. To add another model or provider that Pi does not know, or the fields the form does not set (headers, compat, costs), add it to `models.json` as Pi's `models.md` says; the form keeps those fields when it edits the endpoint. A provider that needs code comes as a Pi Pocket drop-in that calls `host.registerModelProvider` ([host.md](extensions/reference/host.md#registermodelprovider)), not as a Pi extension: see [Pi's extensions and packages](#pis-extensions-and-packages).
69
+
70
+ **A Claude subscription.** Sign in to Anthropic with it in Providers. Then turn on **Claude subscription billing** in Menu → Extensions → Installed → **Built in**, so that requests count against the plan. It is off by default, and it asks before it turns on. Without it, Anthropic can bill the requests as extra usage, and refuse them when that is used up.
71
+
72
+ > [!WARNING]
73
+ > **Using a Claude subscription in Pi Pocket is at your own risk.** Anthropic's terms and its help pages disagree on it:
74
+ >
75
+ > - Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) forbid accessing its services "through automated or non-human means, whether through a bot, script, or otherwise", except with an Anthropic API key or where Anthropic explicitly permits it.
76
+ > - Its help pages say that third-party apps can use your subscription limits. Yet its servers often bill such requests as extra usage.
77
+ > - Claude subscription billing makes Pi Pocket's requests look like Claude Code's.
78
+ >
79
+ > Anthropic can change how it counts these requests, refuse them, or act on an account it finds using them. An Anthropic API key, or a model from another provider, has none of these risks.
58
80
 
59
81
  Models are the person's choice, never Pi's:
60
82
 
61
- - A subagent runs on its session's model, unless the owner allows models under **Models for subagents**, at the top of the Providers sheet. By default, there are none. Once some are allowed, subagents and linked sessions run only on those: on the session's model when it is one of them and Pi names none, else on a model Pi chooses from them (Pi must name one when the session's is not among them).
83
+ - A subagent runs on its session's model, unless the owner allows models under **Subagent models** in the Providers sheet (a pane on the right on wide screens, at the top on phones). By default, there are none. Once some are allowed, subagents and linked sessions run only on those: on the session's model when it is one of them and Pi names none, else on a model Pi chooses from them (Pi must name one when the session's is not among them).
62
84
  - PiP gives a model only when its person named it.
63
85
 
64
86
  Instructions, skills, and `AGENTS.md` cannot change this. Tell the person where the setting is instead.
@@ -129,6 +151,10 @@ These are in the app, not in files. Tell the person where they are. Do not chang
129
151
 
130
152
  See [features.md](features.md) for each of them.
131
153
 
154
+ ## Pi's extensions and packages
155
+
156
+ Pi Pocket reads Pi's sign-ins, models, settings, skills, prompt templates, and AGENTS.md files, but not Pi's extensions. It does not load `~/.pi/agent/extensions/`, the `extensions` setting, or the packages of the `packages` setting in Pi's `settings.json`. Pi Pocket runs on Pi Durable, and its extensions are of another kind ([extensions.md](extensions.md)). For something that a Pi package gives, look in Menu → Extensions: under **Built in**, and in **Discover**.
157
+
132
158
  ## When this is not enough
133
159
 
134
160
  To give Pi a new tool, add a rule to its prompt that depends on the session's state, or check its tool calls, write an extension: [extensions.md](extensions.md). An extension can also add a page, a rail button, or a route to the app ([Adding to the app](extensions/app.md)).
@@ -29,7 +29,7 @@ Rules for every stream:
29
29
 
30
30
  A design needs images, fonts, data files, and more than one page. Today an artifact is one UTF-8 file.
31
31
 
32
- - The `artifact` and `artifact_inline` tools get `assets`: up to 200 entries of `{ name, path }` (copy a file from the session's machine, binary allowed) or `{ name, content }` (UTF-8 text). `name` is a relative path: segments of `[A-Za-z0-9._-]`, joined by `/`, no `.` or `..` segment, no leading `/`, up to 200 characters.
32
+ - The `artifact` tool (and `artifact_inline`, until 0.28.0, when `inline: true` replaced it) gets `assets`: up to 200 entries of `{ name, path }` (copy a file from the session's machine, binary allowed) or `{ name, content }` (UTF-8 text). `name` is a relative path: segments of `[A-Za-z0-9._-]`, joined by `/`, no `.` or `..` segment, no leading `/`, up to 200 characters.
33
33
  - A new version keeps the assets of the version before. `removeAssets: string[]` drops some. An entry with an existing name replaces it.
34
34
  - Limits: 5 MB for one asset, 20 MB for all the assets of one version, as constants beside `MAX_BYTES`.
35
35
  - Storage: assets are stored once for each content hash (sha256) in a new document kind, `pocket.artifact-asset`, keyed by the hash, with the bytes in base64. `ArtifactVersion` gets an optional `assets?: Record<string, { hash: string; size: number; type: string }>`. A replayed call must find what it wrote, as the body does.
package/docs/docker.md CHANGED
@@ -61,6 +61,8 @@ Do not use `PI_POCKET_ACCESS=local` with the published port: `local` listens on
61
61
 
62
62
  `cloudflare` works in the container: the image already contains `cloudflared`, so the launcher does not need a terminal to download it. The tunnel runs inside the container, and the published port is not used. `tailscale` looks for a Tailscale address in the container, which it usually does not have. Run Tailscale on the host instead: publish the port on `127.0.0.1` as above and point `tailscale serve` at it, or run the container with `network_mode: host`.
63
63
 
64
+ `tailscale-serve` does not work from the container as shipped: the image has no `tailscale` command, and it would need the host's `tailscaled` socket as well. Keep Tailscale on the host and mount the port by hand, as above; the launcher's own mode is for a native install.
65
+
64
66
  ## Permissions
65
67
 
66
68
  Compose runs the container as root. With rootless Podman, root inside the container is your own host user, so the bind-mounted folders are writable without extra work. This is why the default is root, despite the Browser panel being a Chromium process.
@@ -0,0 +1,110 @@
1
+ # Embedders
2
+
3
+ An **embedder** is an app that shows Pi Pocket's web app inside itself: an Electron or Tauri wrapper on a computer, for example, or a phone app with a web view, with notifications, a badge, or a menu of its own. [Pi Pocket GUI](https://github.com/vitalNohj/pi-pocket-gui) is one. Pi Pocket stays a web app on its server; the embedder loads the server's address, and the person signs in there as in a browser.
4
+
5
+ A browser tab cannot do some things that such an app can, and Web Push does not reach a page in Electron. The **app bridge** joins the two: the embedder puts `window.pocketHost` in the page, and Pi Pocket uses what it offers. Pi Pocket knows nothing else about the embedder: not its name, not what kind of app it is, not what it runs on. In a browser there is no app bridge, and nothing changes.
6
+
7
+ ## Finding Pi Pocket
8
+
9
+ `GET /api/pocket/info` answers without a sign-in:
10
+
11
+ ```json
12
+ { "name": "pi-pocket", "bridge": 1 }
13
+ ```
14
+
15
+ `bridge` is the version of the app bridge that this server's web app speaks. The answer never has Pi Pocket's version. A server older than the app bridge answers 401 there; its web app manifest (`/manifest.webmanifest`) still has `"name": "Pi Pocket"`.
16
+
17
+ ## The app bridge
18
+
19
+ The app bridge is experimental (since 0.28.0): it can change in a minor release ([API stability](extensions/policies/api-stability.md)). Before 0.28.0-beta.7 these docs were `docs/desktop.md`.
20
+
21
+ The embedder (in Electron, its preload script) puts one object in the top page of the server's origin, and nowhere else: never in a frame (artifacts run in frames), never on another origin.
22
+
23
+ ```js
24
+ window.pocketHost = {
25
+ kind: "my-app", // which embedder; for logs only
26
+ apiVersion: 1,
27
+ capabilities: ["menu", "badge", "notify", "visibility", "pinned", "open"],
28
+
29
+ menuTitle(), // the heading of the embedder's group in the menu, such as its name; optional
30
+ menuItems(), // [{ id, label, hint? }]: the items of that group, at the menu's end
31
+ invoke(id), // one of them was chosen; false when it could not be done
32
+ setBadge(count), // sessions that need you, as the home-screen icon counts them
33
+ notify(message), // a notification for the embedder to show (below)
34
+ visible(), // whether the embedder's window shows: false while hidden in a tray or minimized
35
+ setPinned(list), // [{ id, title, state, label, url }]: the pinned sessions, in order
36
+ subscribe(listener), // the embedder's events (below)
37
+ };
38
+ ```
39
+
40
+ `web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the embedder throws. `web/embedder.js` does the rest. Pi Pocket uses only the capabilities the embedder names, and ignores ones it does not know. A newer app bridge keeps version 1's calls.
41
+
42
+ ### Capabilities
43
+
44
+ | Capability | What Pi Pocket does |
45
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
46
+ | `menu` | Shows `menuItems()` in a group of their own at the end of the menu, below its App part, under `menuTitle()` (up to 40 characters); without a title, the group has no heading. Choosing one calls `invoke(id)`. Pi Pocket GUI offers **GUI Settings…** under its name. |
47
+ | `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes. |
48
+ | `notify` | Opens its event stream with `embedder=notify`. The server then sends this connection every notification it would push to the person (`embedder-notify`), and the page passes each to `notify(message)`. |
49
+ | `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab. |
50
+ | `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these app bridge names. `label` says it in words. |
51
+ | `open` | Opens what the embedder asks for (an `open` event), also without `notify`. |
52
+
53
+ A page from before 0.28.0-beta.7, still open after the server updates, asks with `host=notify` and listens for `desktop-notify`: the server still sends it those, until the page reloads.
54
+
55
+ A page in an Electron window keeps running at full speed while the window hides in the tray, so `document.visibilityState` stays `visible` there. That is why `visible()` exists: without it, the server would think the person is looking, and hold every notification back.
56
+
57
+ ### Notifications
58
+
59
+ The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their embedders' connections (`PocketApp.notifyEmbedders`). An embedder that is not running gets nothing: nothing waits for it.
60
+
61
+ ```js
62
+ {
63
+ title: "Pi needs approval · Deploy",
64
+ body: "bash: npm run deploy", // cut at 400 characters, as for Web Push
65
+ url: "/s/12", // what a click opens: a session, PiP ("/?pip=1"), or "/"
66
+ tag: "approval-…", // one notification per tag: a newer one replaces it
67
+ urgency: "high", // "normal", or "high" for approvals and questions
68
+ approval: { // approvals only
69
+ id: "…",
70
+ allow: true, // Web Push's rule: the person may allow it, and the whole call fits on one short line
71
+ may: true, // the person may allow it at all
72
+ call: "bash: npm run deploy", // the whole call, never cut
73
+ },
74
+ }
75
+ ```
76
+
77
+ The embedder chooses how much of an approval to show and whether to offer **Allow**, from `may`, `allow`, and `call`. It always offers **Deny**. The server checks again, when the answer comes, that the person may give it.
78
+
79
+ ### The embedder's events
80
+
81
+ `subscribe(listener)` takes one function. The embedder calls it with:
82
+
83
+ - `{ type: "visibility" }`: its window was shown or hidden. The page reads `visible()` again.
84
+ - `{ type: "open", url }`: open this, such as a notification or a tray item that was clicked. Only addresses of the server's own origin open.
85
+ - `{ type: "approve", id, allow }`: the person answered an approval in a notification. The page answers it with its own sign-in.
86
+
87
+ ## The window's buttons
88
+
89
+ An embedder that hides its title bar, and shows Pi Pocket up to its window's top edge with the window's own buttons over it (close, minimize, zoom), tells the page where they are through the web's standard for it, the Window Controls Overlay (`navigator.windowControlsOverlay`). An installed web app with `"display_override": ["window-controls-overlay"]` does the same. The app bridge is not needed for it.
90
+
91
+ `web/window-controls.js` makes room only under the buttons, and only as much as they take; the rest of the layout keeps its whole height:
92
+
93
+ - A bar under them (the session tabs, the conversation's top bar, a panel's, a viewer's) keeps what it holds beside them, and the window can be dragged by it.
94
+ - A window without one (the sidebar on wide screens, an extension's page) starts below them. Tiled, its margin moves it, so the tiles' gap stays above it.
95
+ - A strip beside the buttons, as wide as the windows that moved down, moves the window too. What floats over the app (sheets, the launcher, viewers, PiP) takes clicks there.
96
+ - Tiled, the window whose bar is under the buttons has its corner cut around them (`corner-shape`), so its border and focus ring go down, around them, and back up, instead of under them. A browser without `corner-shape` keeps the rounded corner.
97
+
98
+ The page reads the layout, not the screen: a window, a bar, or a panel that opens (the subagents board, Design, Files, Browser, People) has its room and its cut before the frame that first shows it, and a window that pops in is measured where it lands. Nothing shows under the buttons first and moves after.
99
+
100
+ On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an embedder can tell that it makes its own room. For a page without it (an older Pi Pocket, a sign-in page), Pi Pocket GUI instead sets a top safe-area inset as tall as the buttons, which Pi Pocket's bars have long kept clear of on phones.
101
+
102
+ ## Security
103
+
104
+ The app bridge is only as safe as the embedder that offers it. An embedder must:
105
+
106
+ - put it only in the top frame of the server's origin, and take it away when that frame goes elsewhere;
107
+ - check, in its main process, the frame and origin of every call that comes from the page: the sender frame's own origin (`senderFrame.origin`), not its `url`, because the server's origin also serves sandboxed artifact pages, whose origin is opaque;
108
+ - give the page no Node.js, and keep its sandbox and context isolation on.
109
+
110
+ Pi Pocket gives the app bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the page.
@@ -2,7 +2,7 @@
2
2
  * A clock tool, and a /clock-zone command that sets the time zone it uses in a session. An example drop-in extension:
3
3
  * copy it into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
4
4
  */
5
- import { Type } from "@earendil-works/pi-ai";
5
+ import { obj, opt, str } from "@earendil-works/pi-schema";
6
6
  import { defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
7
7
  // A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
8
8
  import type { Web } from "../../types/pocket.d.ts";
@@ -22,10 +22,8 @@ const clock = defineTool({
22
22
  name: "clock",
23
23
  description:
24
24
  "The date and time now, in a time zone such as Europe/Berlin (by default, the session's or the server's).",
25
- parameters: Type.Object({
26
- zone: Type.Optional(
27
- Type.String({ description: "An IANA time zone, such as America/Chicago" }),
28
- ),
25
+ parameters: obj({
26
+ zone: opt(str({ description: "An IANA time zone, such as America/Chicago" })),
29
27
  }),
30
28
  // It only reads the clock: running it again after a restart cut it off is harmless.
31
29
  replay: "safe",
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Counts the words in a text: a tool for Pi, and a /my-words command for people.
3
3
  */
4
- import { Type } from "@earendil-works/pi-ai";
4
+ import { obj, str } from "@earendil-works/pi-schema";
5
5
  import { defineExtension, defineTool } from "@earendil-works/pi-durable";
6
6
  import type { Web } from "../../types/pocket.d.ts";
7
7
 
@@ -13,7 +13,7 @@ function countWords(text: string): number {
13
13
  const wordCount = defineTool({
14
14
  name: "my_word_count",
15
15
  description: "Count the words in a text.",
16
- parameters: Type.Object({ text: Type.String({ description: "The text to count" }) }),
16
+ parameters: obj({ text: str({ description: "The text to count" }) }),
17
17
  replay: "safe",
18
18
  execute: async (args) => ({
19
19
  output: [{ type: "text" as const, text: `${countWords(args.text)} words` }],
@@ -2,7 +2,7 @@
2
2
  * A note the transcript can fold: one line in the app, and the whole message for the model.
3
3
  * An example drop-in: copy it and `quiet-note.js` into `~/.pi-pocket/extensions/`, then turn it on in Menu → Extensions.
4
4
  */
5
- import { Type } from "@earendil-works/pi-ai";
5
+ import { obj, str } from "@earendil-works/pi-schema";
6
6
  import { defineExtension, defineTool } from "@earendil-works/pi-durable";
7
7
  // A type import is gone when the module runs. In the drop-in folder, import the types from "./_pocket.d.ts".
8
8
  import type { Web } from "../../types/pocket.d.ts";
@@ -14,9 +14,9 @@ const leaveNote = defineTool({
14
14
  name: "quiet_note",
15
15
  description:
16
16
  "Leave a note in this session. The app may show one line; you still read the whole note.",
17
- parameters: Type.Object({
18
- text: Type.String({ description: "The whole note" }),
19
- summary: Type.String({ description: "A few words for the one line" }),
17
+ parameters: obj({
18
+ text: str({ description: "The whole note" }),
19
+ summary: str({ description: "A few words for the one line" }),
20
20
  }),
21
21
  // The request id is this call's, so a replay finds the note instead of leaving another.
22
22
  replay: "safe",
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Reads a public web page for Pi: a read_page tool that fetches only public addresses and fences the page's text.
3
3
  */
4
- import { Type } from "@earendil-works/pi-ai";
4
+ import { num, obj, opt, str } from "@earendil-works/pi-schema";
5
5
  import { defineExtension, defineTool } from "@earendil-works/pi-durable";
6
6
  import type { Host } from "../../types/pocket.d.ts";
7
7
 
@@ -30,11 +30,9 @@ export default function createReadPage(host: Host) {
30
30
  const readPage = defineTool({
31
31
  name: "read_page",
32
32
  description: "Read the text of a public web page (http or https).",
33
- parameters: Type.Object({
34
- url: Type.String({ description: "The page's address" }),
35
- maxChars: Type.Optional(
36
- Type.Number({ description: "The text to give at most (default 20000)" }),
37
- ),
33
+ parameters: obj({
34
+ url: str({ description: "The page's address" }),
35
+ maxChars: opt(num({ description: "The text to give at most (default 20000)" })),
38
36
  }),
39
37
  replay: "safe",
40
38
  execute: async (args) => {
@@ -63,7 +63,7 @@ The handler runs with the owner's rights, as all of the module does. A conversat
63
63
 
64
64
  Each run is a durable task, kept by the person who ran it, the session, and the request's id.
65
65
 
66
- - When a reply gets lost, the same text sent again from the same tab finds the first run, and gets its result. The handler runs one time. Pi Pocket keeps the ids of a person's recent runs only ([limits](reference/limits.md#commands)).
66
+ - When a reply gets lost, the same text sent again from the same browser, also after a reload, finds the first run, and gets its result. The handler runs one time. Pi Pocket keeps the ids of a person's recent runs only ([limits](reference/limits.md#commands)).
67
67
  - A restart of the server never runs a handler again. The person hears that it was stopped, because it can have done a part of its work.
68
68
  - Menu → **Running now** shows a command while it runs, and can stop it. People who steer stop conversation commands; the owner stops global commands.
69
69
  - To stop a run aborts `ctx.signal`. It does not undo what the handler did. A stop just after the handler wrote its card leaves the card, and the run says that it was stopped.