pi-pocket 0.28.0-beta.4 → 0.28.0-beta.5

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 (102) hide show
  1. package/README.md +1 -1
  2. package/docs/architecture.md +8 -0
  3. package/docs/customizing.md +5 -2
  4. package/docs/desktop.md +105 -0
  5. package/docs/extensions/policies/api-stability.md +7 -1
  6. package/docs/extensions/reference/host.md +22 -0
  7. package/docs/extensions/reference/pocket.md +62 -1
  8. package/docs/extensions/reference/theme-surface.md +2 -0
  9. package/docs/extensions/reference/web.md +3 -1
  10. package/docs/extensions/routes.md +1 -1
  11. package/docs/extensions/workspaces.md +25 -0
  12. package/docs/extensions.md +4 -0
  13. package/docs/features.md +9 -8
  14. package/docs/index.md +1 -0
  15. package/docs/map.md +22 -14
  16. package/npm-shrinkwrap.json +89 -2
  17. package/package.json +4 -1
  18. package/src/server/alerts.ts +44 -16
  19. package/src/server/app.ts +160 -6
  20. package/src/server/background.ts +5 -0
  21. package/src/server/browser/urls.ts +3 -0
  22. package/src/server/commands.ts +53 -20
  23. package/src/server/design/files.ts +10 -0
  24. package/src/server/design/guide.ts +6 -0
  25. package/src/server/design/index.ts +16 -2
  26. package/src/server/design/scan-facts.ts +3 -0
  27. package/src/server/design/scan-fig-container.ts +390 -0
  28. package/src/server/design/scan-fig-kiwi.ts +466 -0
  29. package/src/server/design/scan-fig-nodes.ts +385 -0
  30. package/src/server/design/scan-fig.ts +404 -0
  31. package/src/server/design/scan-files.ts +54 -2
  32. package/src/server/design/scan-import-convert.ts +1 -1
  33. package/src/server/design/scan-import.ts +1 -1
  34. package/src/server/design/scan-infer.ts +2 -0
  35. package/src/server/design/scan-tree.ts +18 -0
  36. package/src/server/design/scan.ts +69 -10
  37. package/src/server/design/system.ts +5 -0
  38. package/src/server/extension-request.ts +15 -0
  39. package/src/server/extension-web.ts +38 -4
  40. package/src/server/extensions/agent-teams.ts +1 -1
  41. package/src/server/extensions/artifacts.ts +15 -2
  42. package/src/server/extensions/browser.ts +6 -1
  43. package/src/server/extensions/design/system-routes.ts +9 -2
  44. package/src/server/extensions/diagrams/index.js +344 -0
  45. package/src/server/extensions/diagrams/math.css +1 -0
  46. package/src/server/extensions/diagrams/style.css +42 -0
  47. package/src/server/extensions/diagrams.ts +6 -0
  48. package/src/server/extensions/pip.ts +1 -1
  49. package/src/server/extensions/prompt.ts +10 -3
  50. package/src/server/extensions/subagents.ts +1 -1
  51. package/src/server/heic-convert.d.ts +11 -0
  52. package/src/server/heic-worker.ts +12 -0
  53. package/src/server/heic.ts +129 -0
  54. package/src/server/hooks.ts +29 -0
  55. package/src/server/host.ts +13 -0
  56. package/src/server/http/api.ts +12 -4
  57. package/src/server/http/assets.ts +13 -0
  58. package/src/server/http/browser-routes.ts +5 -1
  59. package/src/server/http/conversation-routes.ts +20 -5
  60. package/src/server/http/events.ts +1 -0
  61. package/src/server/http/extension-routes.ts +2 -0
  62. package/src/server/http/push-routes.ts +5 -2
  63. package/src/server/http.ts +33 -1
  64. package/src/server/linked-sessions.ts +19 -7
  65. package/src/server/memory.ts +6 -0
  66. package/src/server/model-images.ts +46 -8
  67. package/src/server/paths.ts +8 -0
  68. package/src/server/pip-compact.ts +1 -1
  69. package/src/server/pip.ts +5 -1
  70. package/src/server/push.ts +10 -0
  71. package/src/server/reload.ts +2 -0
  72. package/src/server/room.ts +21 -0
  73. package/src/server/shell.ts +10 -6
  74. package/src/server/watches.ts +8 -0
  75. package/src/server/workspace.ts +30 -0
  76. package/src/server/worktrees.ts +5 -0
  77. package/types/pocket.d.ts +84 -1
  78. package/web/app.js +2 -0
  79. package/web/composer.js +24 -4
  80. package/web/desktop.js +117 -0
  81. package/web/extension-ui.js +124 -5
  82. package/web/files-panel.js +17 -3
  83. package/web/host.js +78 -0
  84. package/web/markdown-ext.js +45 -0
  85. package/web/math.js +58 -0
  86. package/web/notify.js +15 -2
  87. package/web/peeks.js +3 -2
  88. package/web/pip.js +3 -2
  89. package/web/quote-reply.js +8 -7
  90. package/web/quote-text.js +26 -0
  91. package/web/seen.js +3 -2
  92. package/web/sheets/extensions.js +11 -18
  93. package/web/sheets/gallery.js +0 -2
  94. package/web/sheets/hooks.js +112 -5
  95. package/web/sheets/menu.js +11 -0
  96. package/web/sheets.js +0 -1
  97. package/web/store.js +25 -5
  98. package/web/style.css +246 -28
  99. package/web/theme-surface.js +6 -0
  100. package/web/transcript.js +135 -16
  101. package/web/ui.js +94 -7
  102. package/web/window-controls.js +327 -0
package/README.md CHANGED
@@ -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).
@@ -47,6 +47,10 @@ The native extension loader registers one scoped resolve hook for drop-in import
47
47
 
48
48
  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
49
 
50
+ ## Workspace execution providers
51
+
52
+ `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.
53
+
50
54
  ## Favorite folders
51
55
 
52
56
  `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.
@@ -77,6 +81,8 @@ PiP's header model chip opens the existing picker with its own conversation ID a
77
81
 
78
82
  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
83
 
84
+ 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.
85
+
80
86
  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
87
 
82
88
  ## Who chooses models
@@ -252,6 +258,8 @@ In the browser, the composer keeps a command's request id while its send is unre
252
258
 
253
259
  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
260
 
261
+ **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.
262
+
255
263
  **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
264
 
257
265
  **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.
@@ -25,11 +25,14 @@ Keep the files short and true. They go with each request, and a rule that Pi can
25
25
 
26
26
  ## PiP's instructions
27
27
 
28
- PiP has no project, so it does not read AGENTS.md files. Write the rules for PiP, such as the language of its answers, 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).
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
29
 
30
30
  - PiP gets the file with each message. When the file changes, the next message has the new text.
31
31
  - Only PiP reads it: sessions, subagents, and Pi's terminal app do not.
32
- - A session that PiP messages still answers PiP in Simplified Technical English. PiP answers you as the file says.
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`.
33
36
 
34
37
  ## Skills: procedures that Pi follows on request
35
38
 
@@ -0,0 +1,105 @@
1
+ # Desktop apps
2
+
3
+ A desktop app can show Pi Pocket in a window of its own: an Electron or Tauri wrapper, for example, with a tray icon, native notifications, and 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 desktop app 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 **host bridge** joins the two: the app puts `window.pocketHost` in the page, and Pi Pocket uses what it offers. In a browser there is no 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 host bridge that this server's web app speaks. The answer never has Pi Pocket's version. A server older than the bridge answers 401 there; its web app manifest (`/manifest.webmanifest`) still has `"name": "Pi Pocket"`.
16
+
17
+ ## The bridge
18
+
19
+ The app's preload script puts one object in the top page of the server's origin, and nowhere else: never in a frame (artifacts run in frames), never on another origin.
20
+
21
+ ```js
22
+ window.pocketHost = {
23
+ kind: "pi-pocket-gui", // which app; for logs only
24
+ apiVersion: 1,
25
+ capabilities: ["menu", "badge", "notify", "visibility", "pinned", "open"],
26
+
27
+ menuItems(), // [{ id, label, hint? }]: items for the menu's Desktop group, at its end
28
+ invoke(id), // one of them was chosen; false when it could not be done
29
+ setBadge(count), // sessions that need you, as the home-screen icon counts them
30
+ notify(message), // a notification for the app to show (below)
31
+ visible(), // whether the app's window shows: false while hidden in a tray or minimized
32
+ setPinned(list), // [{ id, title, state, label, url }]: the pinned sessions, in order
33
+ subscribe(listener), // the app's events (below)
34
+ };
35
+ ```
36
+
37
+ `web/host.js` reads it: `host`, `hostCan(capability)`, and `callHost(name, …)`, which catches what the app throws. `web/desktop.js` does the rest. Pi Pocket uses only the capabilities the app names, and ignores ones it does not know. A newer bridge keeps version 1's calls.
38
+
39
+ ### Capabilities
40
+
41
+ | Capability | What Pi Pocket does |
42
+ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43
+ | `menu` | Shows `menuItems()` in a **Desktop** group at the end of the menu, below its App part. Choosing one calls `invoke(id)`. Pi Pocket GUI offers **Server settings…**. |
44
+ | `badge` | Calls `setBadge(count)` instead of the Badging API whenever the count changes. |
45
+ | `notify` | Opens its event stream with `host=notify`. The server then sends this connection every notification it would push to the person (`desktop-notify`), and the page passes each to `notify(message)`. |
46
+ | `visibility` | Reads `visible()` with the page's own visibility: the page counts as hidden while either says so. It tells the server (`POST /api/visibility`), so the server knows the person is away and lets notifications through, and seen marks and peek tiles wait as they do in a hidden tab. |
47
+ | `pinned` | Calls `setPinned(list)` when a pinned session's title or state changes, for a tray menu. `state` is the square's shape from `sessionMark`: `waiting`, `limited`, `working`, `failed`, `fresh` (finished, not read), or `seen`. The session list's theme states `done` and `idle` do not change these bridge names. `label` says it in words. |
48
+ | `open` | Opens what the app asks for (an `open` event), also without `notify`. |
49
+
50
+ A page in an Electron window keeps running at full speed while the window hides in the tray, so `document.visibilityState` stays `visible` there. That is why `visible()` exists: without it, the server would think the person is looking, and hold every notification back.
51
+
52
+ ### Notifications
53
+
54
+ The server decides as for Web Push (`alerts.ts`): who can see the session, the kinds each person turned on in Menu → Notifications, and whether they are looking at it. Then it sends the message through Web Push to their subscribed devices, and to each of their desktop apps' connections (`PocketApp.notifyDesktops`). An app that is not running gets nothing: nothing waits for it.
55
+
56
+ ```js
57
+ {
58
+ title: "Pi needs approval · Deploy",
59
+ body: "bash: npm run deploy", // cut at 400 characters, as for Web Push
60
+ url: "/s/12", // what a click opens: a session, PiP ("/?pip=1"), or "/"
61
+ tag: "approval-…", // one notification per tag: a newer one replaces it
62
+ urgency: "high", // "normal", or "high" for approvals and questions
63
+ approval: { // approvals only
64
+ id: "…",
65
+ allow: true, // Web Push's rule: the person may allow it, and the whole call fits on one short line
66
+ may: true, // the person may allow it at all
67
+ call: "bash: npm run deploy", // the whole call, never cut
68
+ },
69
+ }
70
+ ```
71
+
72
+ The app chooses how much of an approval to show and whether to offer **Allow**, from `may`, `allow`, and `call`. It always offers **Deny**. The server checks again, when the answer comes, that the person may give it.
73
+
74
+ ### The app's events
75
+
76
+ `subscribe(listener)` takes one function. The app calls it with:
77
+
78
+ - `{ type: "visibility" }`: its window was shown or hidden. The page reads `visible()` again.
79
+ - `{ 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.
80
+ - `{ type: "approve", id, allow }`: the person answered an approval in a notification. The page answers it with its own sign-in.
81
+
82
+ ## The window's buttons
83
+
84
+ An app 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 bridge is not needed for it.
85
+
86
+ `web/window-controls.js` makes room only under the buttons, and only as much as they take; the rest of the layout keeps its whole height:
87
+
88
+ - 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.
89
+ - 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.
90
+ - 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.
91
+ - 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.
92
+
93
+ The page reads the layout, not the screen: a window, a bar, or a panel that opens (the subagents board, Design, Files, Browser, People) has its room and its cut before the frame that first shows it, and a window that pops in is measured where it lands. Nothing shows under the buttons first and moves after.
94
+
95
+ On `<html>`, `data-window-controls` is `left` (macOS), `right` (Windows, Linux), or `none`, and `--controls-h` is how far down the buttons reach. What makes room has `data-under-controls`, `bar` or `push`, and `--controls-room`. The window cut around the buttons has `data-controls-notch`, and `--notch-w` and `--notch-h`. The page sets `data-window-controls` before its first paint, so an app can tell that it makes its own room. For a page without it (an older Pi Pocket, a sign-in page), Pi Pocket GUI instead sets a top safe-area inset as tall as the buttons, which Pi Pocket's bars have long kept clear of on phones.
96
+
97
+ ## Security
98
+
99
+ The bridge is only as safe as the app that offers it. An app must:
100
+
101
+ - put it only in the top frame of the server's origin, and take it away when that frame goes elsewhere;
102
+ - check, in its main process, the frame and origin of every call that comes from the page: the sender frame's own origin (`senderFrame.origin`), not its `url`, because the server's origin also serves sandboxed artifact pages, whose origin is opaque;
103
+ - give the page no Node.js, and keep its sandbox and context isolation on.
104
+
105
+ Pi Pocket gives the bridge nothing that the page could not do over the API itself: the notifications are the person's own, and an approval's answer goes through the same route and checks as a tap in the app.
@@ -42,6 +42,8 @@ These members are public:
42
42
  - `notice(level, message, id?)`
43
43
  - `resolveModel(spec)`, `subagentModels()`, `modelProblem(ref, fresh?)`, `modelInfo(spec)` (exact local metadata, since 0.16.0)
44
44
  - `requesterOf(conversationId)`
45
+ - `cwdOf(conversationId)` (experimental, since 0.28.0)
46
+ - `registerWorkspaceProvider(scheme, provider)` and `WorkspaceProvider` (experimental, since 0.28.0: [Execution environments for workspaces](../workspaces.md))
45
47
  - `roleOf(personId)` (experimental, since 0.27.0)
46
48
  - `skillPaths()`, `skills(cwd)`
47
49
  - `heldBack(conversationId)`, `onLimitsChanged(listener)`
@@ -62,7 +64,7 @@ The host's members do not change while modules reload. A new member comes only a
62
64
  - `provide`, `use`, `onService`, `settings`, `setting`, and `onSettings` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md)).
63
65
  - `publicPage` and `links` (experimental, since 0.22.0): pages at `/l/<token>` for anyone with a module's link, what a page handler gets (`PublicPageRequest`), and what its answer does ([Public pages](../public-pages.md)).
64
66
  - `presentEntry` (experimental, since 0.28.0), with `PresentEntry`: how an input this module sends shows in the transcript. The model still reads that message in full ([Adding to the app](../app.md)).
65
- - What a route handler gets (`WebRequest`: `method`, `params`, `query`, `body`, `user`, `signal`; since 0.16.0 also request-lifetime `snapshot`, `context`, `commit`), and what its answer does.
67
+ - What a route handler gets (`WebRequest`: `method`, `params`, `query`, `body`, `user`, `signal`; since 0.16.0 also request-lifetime `snapshot`, `context`, `commit`), and what its answer does. `createSession` is experimental since 0.28.0.
66
68
  - A conversation-bound request's `conversation` metadata and human `linkedSessions.start` / `list`, with their authenticated-actor, receipt, and admission checks (since 0.16.0).
67
69
  - `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage` (experimental, since 0.28.0): read-only usage for a visible conversation and its visible descendants.
68
70
  - The route paths, the methods, the `access` values (`owner`, `steer`, `view`), and the `X-Pocket` header that every call to a route must have.
@@ -168,6 +170,10 @@ Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` fi
168
170
 
169
171
  Since 0.28.0, `web.presentEntry` and `pocket.entryPresentation` are experimental, with `PresentEntry`; so is `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage`. A module names how an input it sends shows. The model still reads that message in full. Since then too, `pocket.messages` leaves out an input stored as a module's own kind: before, such an input was not a message in the transcript at all.
170
172
 
173
+ Since 0.28.0, `host.registerWorkspaceProvider`, `WorkspaceProvider`, `host.cwdOf`, and `WebRequest.createSession` are experimental: [Execution environments for workspaces](../workspaces.md).
174
+
175
+ Since 0.28.0, `pocket.fence` and `pocket.mathInline` are experimental, with `FenceSpec`, `MathInlineSpec`, and `FenceProps`.
176
+
171
177
  Since 0.28.0, `run.ended` carries `outcome` (`done`, `failed`, or `aborted`) and, when the run gave up, `failure`: the same short line the session list shows. `LinkedSession.failed` carries that line for a linked session's last run, with the same audience rule as its title, and only while the failure stands. Both are experimental.
172
178
 
173
179
  Since 0.20.0, the session list's extension points are experimental: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, and `sessionSearch`, `WebRequest.sessions`, and their types. So is `pocket.composerKey`, with `ComposerKeySpec` and `ComposerBox`, and so are `pocket.onConversation`, `messages`, and `reveal`, with `MessagesOptions`, `MessagePage`, and `MessageInfo`. So are `host.registerModelProvider`, and `host.fetchPublic` with `PublicFetchInit`.
@@ -40,6 +40,16 @@ Since 0.1.0 · Stable
40
40
 
41
41
  Pi's own folder, usually `~/.pi/agent`. Pi keeps its sign-ins, models, settings, skills, and prompt templates there.
42
42
 
43
+ ### `cwdOf`
44
+
45
+ ```ts
46
+ cwdOf(conversationId: ConversationId): string;
47
+ ```
48
+
49
+ Since 0.28.0 · Experimental
50
+
51
+ The conversation's current working folder, or its canonical workspace URI for a remote session. It reads the current agent state, so a module must not cache it across folder changes.
52
+
43
53
  ## Skills
44
54
 
45
55
  ### `skillPaths`
@@ -162,6 +172,18 @@ The thinking levels, lowest first. They have the names that models and sessions
162
172
 
163
173
  ## People and limits
164
174
 
175
+ ### `registerWorkspaceProvider`
176
+
177
+ ```ts
178
+ registerWorkspaceProvider(scheme: string, provider: WorkspaceProvider): () => void;
179
+ ```
180
+
181
+ Since 0.28.0 · Experimental
182
+
183
+ Registers the execution environment for a URI scheme such as `ssh`. `resolveCwd` returns the canonical address. It must keep the same scheme. Pi Pocket stores that address and refuses to use the local machine when no provider is active. The returned disposer removes only its own registration. See [Execution environments for workspaces](../workspaces.md).
184
+
185
+ `WorkspaceProvider` has `env(cwd: string): ExecutionEnv` and `resolveCwd(cwd: string, signal?: AbortSignal): Promise<string>`. `env` returns promptly. It receives the canonical workspace address. `resolveCwd` can check and canonicalize the address. `signal` is optional: in 0.28, session creation and settings do not pass one yet.
186
+
165
187
  ### `requesterOf`
166
188
 
167
189
  ```ts
@@ -569,6 +569,26 @@ pocket.composerKey({
569
569
  });
570
570
  ```
571
571
 
572
+ ### `fence`
573
+
574
+ ```ts
575
+ fence(spec: FenceSpec): Added<FenceSpec>;
576
+ ```
577
+
578
+ Since 0.28.0 · Experimental
579
+
580
+ Registers a component for one or more fenced-code languages. The app renders it with exactly `{ source, lang, streaming }`: the code text, the language label from the fence, and whether the Markdown is still streaming. The component uses the app's Preact and can use the Preact functions in `pocket`. Language matching ignores case. When registrations match the same language, the first one in server module order, then registration order, wins. See [`FenceSpec`](#fencespec), [`FenceProps`](#fenceprops), and [`Added`](#added).
581
+
582
+ ### `mathInline`
583
+
584
+ ```ts
585
+ mathInline(spec: MathInlineSpec): Added<MathInlineSpec>;
586
+ ```
587
+
588
+ Since 0.28.0 · Experimental
589
+
590
+ Registers the renderer for inline `$…$` and display `$$…$$` math. The app calls `mount(element, source, display)` for each math element: `element` is the code element, `source` is the formula without delimiters, and `display` is true for display math. Math parsing is on only while a registration is active. When multiple registrations exist, the first one in server module order, then registration order, wins. See [`MathInlineSpec`](#mathinlinespec) and [`Added`](#added).
591
+
572
592
  ### `insertText`
573
593
 
574
594
  ```ts
@@ -1259,6 +1279,33 @@ Since 0.14.0 · Stable
1259
1279
 
1260
1280
  What a sheet's component gets: the fields of the `props` that `openSheet` gave, and `pocket` and `close`.
1261
1281
 
1282
+ ### `FenceSpec`
1283
+
1284
+ ```ts
1285
+ interface FenceSpec {
1286
+ id: string;
1287
+ langs: string[];
1288
+ component: ComponentType<FenceProps>;
1289
+ }
1290
+ ```
1291
+
1292
+ Since 0.28.0 · Experimental
1293
+
1294
+ The registration's id, the code fence languages it handles, and the Preact component the app renders. Language matching ignores case. See [`FenceProps`](#fenceprops).
1295
+
1296
+ ### `MathInlineSpec`
1297
+
1298
+ ```ts
1299
+ interface MathInlineSpec {
1300
+ id: string;
1301
+ mount(element: HTMLElement, source: string, display: boolean): void;
1302
+ }
1303
+ ```
1304
+
1305
+ Since 0.28.0 · Experimental
1306
+
1307
+ The registration's id and its math mounter. The app calls the mounter with the rendered code element, formula text without delimiters, and whether the formula uses display math.
1308
+
1262
1309
  ### `ToolCallSpec`
1263
1310
 
1264
1311
  ```ts
@@ -1309,7 +1356,7 @@ interface Added<S> {
1309
1356
 
1310
1357
  Since 0.14.0 · Stable
1311
1358
 
1312
- What `rail`, `menu`, `launcher`, `page`, and `sheet` return.
1359
+ What `rail`, `menu`, `launcher`, `page`, `sheet`, `fence`, and `mathInline` return.
1313
1360
 
1314
1361
  - `update`: changes the fields in `patch`. An update that changes nothing draws nothing again. Values count as the same only when they are the very same value: a new array or function is a change.
1315
1362
  - `remove`: removes what was added.
@@ -1356,6 +1403,20 @@ Since 0.14.0 · Stable
1356
1403
 
1357
1404
  `text` is the Markdown to show.
1358
1405
 
1406
+ ### `FenceProps`
1407
+
1408
+ ```ts
1409
+ interface FenceProps {
1410
+ source: string;
1411
+ lang: string;
1412
+ streaming: boolean;
1413
+ }
1414
+ ```
1415
+
1416
+ Since 0.28.0 · Experimental
1417
+
1418
+ The exact props the app passes to a `pocket.fence` component. `source` is the code text, `lang` is the language label from the fence, and `streaming` says whether the Markdown is still streaming.
1419
+
1359
1420
  ### `SwitchProps`
1360
1421
 
1361
1422
  ```ts
@@ -143,6 +143,8 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
143
143
  | `prompt` | A person's message |
144
144
  | `prompt-head`, `author-mark`, `prompt-author` | Its head: who sent it and when; their initials; their name |
145
145
  | `prompt-text` | What it says (its skill chip, words, and files) |
146
+ | `linked-head`, `linked-mark`, `linked-name` | A linked session's message (`data-from` `linked`): its head, square mark, session name (since 0.28.0) |
147
+ | `linked-open`, `linked-body`, `linked-more` | Its Open button, its text as Markdown, and Show all on a long one (since 0.28.0) |
146
148
  | `presented-input`, `presented-head` | An extension's input (`web.presentEntry`), folded: its card and the line that opens it (since 0.28.0) |
147
149
  | `presented-chevron`, `presented-tag` | That line's chevron; the input's label in its head, when shown open (since 0.28.0) |
148
150
  | `presented-more` | The button beside that line that opens its message sheet (since 0.28.0) |
@@ -251,6 +251,7 @@ Answers the requests of a route. The value that it returns goes back as JSON, an
251
251
 
252
252
  ```ts
253
253
  interface WebRequest {
254
+ createSession(request: { cwd: string; title?: string }): Promise<{ id: number }>;
254
255
  readonly method: WebMethod;
255
256
  readonly params: Readonly<Record<string, string>>;
256
257
  readonly query: URLSearchParams;
@@ -278,6 +279,7 @@ What a handler gets.
278
279
  - Document operations recheck the current person. Retaining a request, its context, or a callback does not extend its lifetime: commits after disconnect or handler return are refused, and an unfinished callback rolls back. Await all writes before returning. These APIs are for module documents, not core's internal documents or a way to start model work.
279
280
  - An unbound catalog save has no source plan, turn, or spend checks. A bound commit also requires the source's current steering and turn rights.
280
281
  - Since 0.20.0 (experimental), `sessions()` gives the sessions that the person who asked can see now, as their session list shows them, archived ones too. See [`WebSession`](#websession). Use it to check the ids that a browser sends, and to keep data about sessions from people who cannot see them. Each call reads the list again.
282
+ - Since 0.28.0 (experimental), `createSession` starts an ordinary session on owner-only routes. It refuses anyone but the owner. See [Execution environments for workspaces](../workspaces.md).
281
283
 
282
284
  ### `WebSession`
283
285
 
@@ -643,7 +645,7 @@ Who can use a route, or whose tabs load a browser module.
643
645
  - `"steer"`: the owner, and guests who can steer all sessions.
644
646
  - `"view"`: the owner, guests, and viewers who can see all sessions.
645
647
 
646
- A person invited to one session never can, because these parts belong to the whole app. Each route has its own `access`, so a browser module for everyone can call a route for the owner alone.
648
+ A person invited to one session never can, because these parts belong to the whole app. The one exception is the built-in Diagrams browser module, which draws Mermaid and math in their replies. They get its browser module and no routes. Each route has its own `access`, so a browser module for everyone can call a route for the owner alone.
647
649
 
648
650
  `access` is the same for all methods. A POST route with `"view"` lets viewers change something through it, though they cannot steer a session. Give `"owner"` or `"steer"` to a route that changes things.
649
651
 
@@ -98,7 +98,7 @@ Routes and the browser module are for the owner alone, unless their `access` say
98
98
  | `"steer"` | The owner, and guests who can steer every session |
99
99
  | `"view"` | The owner, guests, and viewers who see every session |
100
100
 
101
- - A person invited to one session never may use them: these parts belong to the whole app.
101
+ - A person invited to one session never may use them: these parts belong to the whole app. The one exception is the built-in Diagrams browser module, which draws Mermaid and math in their replies. They get its browser module and no routes.
102
102
  - Each route checks its own `access`. So a browser module for everyone can have a route for the owner alone.
103
103
  - `access` is the same for each method. A `POST` route open to `"view"` lets viewers change something through it, though they cannot steer a session. Give a route that changes things `"owner"` or `"steer"`.
104
104
  - A browser module runs with the rights of the person whose tab loads it. So it can do nothing in a guest's tab that the guest cannot do.
@@ -0,0 +1,25 @@
1
+ # Execution environments for workspaces
2
+
3
+ A workspace provider lets a module run a session in an address such as `ssh://host/path`. A workspace address has a scheme of 2 characters or more, then `://`: `C:\work` and `D:` stay local paths. Pi Pocket stores the provider's canonical address in the session. It passes that address to the provider's `env` method for execution. It does not use the local machine when a provider is missing.
4
+
5
+ The interface is experimental since 0.28.0. It can change in a minor release. A module must check that `host.registerWorkspaceProvider` exists when it supports older servers.
6
+
7
+ ```ts
8
+ const remove = host.registerWorkspaceProvider("ssh", {
9
+ env(cwd) {
10
+ return makeExecutionEnv(cwd);
11
+ },
12
+ async resolveCwd(cwd, signal) {
13
+ signal?.throwIfAborted();
14
+ return canonicalRemoteAddress(cwd, signal);
15
+ },
16
+ });
17
+
18
+ web.onDispose(remove);
19
+ ```
20
+
21
+ The provider must keep the `ssh` scheme in the canonical address. The resolver can receive an abort signal. It should stop work when that signal aborts. In 0.28, session creation and settings do not pass one yet. The `env` method must return promptly. It can defer network work until execution.
22
+
23
+ Use `request.createSession({ cwd })` from an owner-only route to start a session. Only the owner can start a session on a workspace address, or move one there: Pi Pocket refuses a guest in session creation, in a session's settings, in a linked session's folder (given or taken from its source), and in a fork or a message sent again from a remote session. A guest can still steer a remote session that the owner shares. The provider remains responsible for validating the remote host and path. Pi Pocket blocks its local file and Git actions for non-local workspace addresses: Files, Changes, branches, uploads, background tasks, artifact files, the design system and design exports, file paths in the browser, and pull request watches. Worktrees are not supported for remote workspaces. The system prompt leaves out this machine's AGENTS.md files and skills: the provider's module adds the remote project's context.
24
+
25
+ When a provider is missing or unloaded, Pi Pocket refuses execution. A module that registers the same scheme replaces the active provider. Its disposer removes only that registration, so an earlier provider can resume.
@@ -105,6 +105,10 @@ These examples work. `npm test` runs them (`test/docs-examples.test.ts`):
105
105
  - [examples/server-status.ts](examples/server-status.ts) with [examples/server-status.js](examples/server-status.js): a page on the rail, with a route that reads the machine's load and memory, and events that keep it live.
106
106
  - [examples/quiet-note.ts](examples/quiet-note.ts) with [examples/quiet-note.js](examples/quiet-note.js): an input the transcript can fold. The model still reads the whole message.
107
107
 
108
+ ## Execution environments for workspaces
109
+
110
+ Modules can register an execution provider for a workspace URI scheme such as `ssh`. See [Execution environments for workspaces](extensions/workspaces.md) and the experimental [`host.registerWorkspaceProvider`](extensions/reference/host.md#registerworkspaceprovider) API.
111
+
108
112
  ## Rules that are easy to break
109
113
 
110
114
  - **Nothing two times.** A restart can run a hook or a safe tool again. Some work must occur one time only: a message that you send, money that you spend, a line that you add to a file. Put it behind `api.memo`, or behind a key that lets a second run find the first.