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

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 (123) hide show
  1. package/README.md +1 -1
  2. package/SECURITY.md +1 -1
  3. package/docs/architecture.md +14 -0
  4. package/docs/customizing.md +7 -4
  5. package/docs/desktop.md +105 -0
  6. package/docs/extensions/linked-sessions.md +1 -1
  7. package/docs/extensions/policies/api-stability.md +8 -1
  8. package/docs/extensions/prompt-sections.md +4 -0
  9. package/docs/extensions/reference/api-versions.md +1 -0
  10. package/docs/extensions/reference/host.md +58 -1
  11. package/docs/extensions/reference/pocket.md +62 -1
  12. package/docs/extensions/reference/theme-surface.md +3 -0
  13. package/docs/extensions/reference/web.md +3 -1
  14. package/docs/extensions/routes.md +1 -1
  15. package/docs/extensions/sessions.md +37 -0
  16. package/docs/extensions/tools.md +1 -1
  17. package/docs/extensions/workspaces.md +25 -0
  18. package/docs/extensions.md +5 -0
  19. package/docs/features.md +14 -12
  20. package/docs/index.md +1 -0
  21. package/docs/map.md +25 -15
  22. package/npm-shrinkwrap.json +89 -2
  23. package/package.json +4 -1
  24. package/src/server/alerts.ts +44 -16
  25. package/src/server/app.ts +171 -6
  26. package/src/server/background.ts +5 -0
  27. package/src/server/browser/urls.ts +3 -0
  28. package/src/server/commands.ts +78 -25
  29. package/src/server/custom-providers.ts +661 -0
  30. package/src/server/design/files.ts +10 -0
  31. package/src/server/design/guide.ts +6 -0
  32. package/src/server/design/index.ts +16 -2
  33. package/src/server/design/scan-facts.ts +3 -0
  34. package/src/server/design/scan-fig-container.ts +390 -0
  35. package/src/server/design/scan-fig-kiwi.ts +466 -0
  36. package/src/server/design/scan-fig-nodes.ts +385 -0
  37. package/src/server/design/scan-fig.ts +404 -0
  38. package/src/server/design/scan-files.ts +54 -2
  39. package/src/server/design/scan-import-convert.ts +1 -1
  40. package/src/server/design/scan-import.ts +1 -1
  41. package/src/server/design/scan-infer.ts +2 -0
  42. package/src/server/design/scan-tree.ts +18 -0
  43. package/src/server/design/scan.ts +69 -10
  44. package/src/server/design/system.ts +5 -0
  45. package/src/server/extension-request.ts +15 -0
  46. package/src/server/extension-sessions.ts +238 -0
  47. package/src/server/extension-web.ts +38 -4
  48. package/src/server/extensions/agent-teams.ts +10 -2
  49. package/src/server/extensions/artifacts.ts +31 -26
  50. package/src/server/extensions/ask.ts +8 -13
  51. package/src/server/extensions/browser.ts +14 -3
  52. package/src/server/extensions/codemode.ts +100 -10
  53. package/src/server/extensions/design/system-routes.ts +9 -2
  54. package/src/server/extensions/diagrams/index.js +344 -0
  55. package/src/server/extensions/diagrams/math.css +1 -0
  56. package/src/server/extensions/diagrams/style.css +42 -0
  57. package/src/server/extensions/diagrams.ts +6 -0
  58. package/src/server/extensions/memory.ts +1 -1
  59. package/src/server/extensions/pip.ts +1 -1
  60. package/src/server/extensions/plan.ts +3 -1
  61. package/src/server/extensions/prompt.ts +16 -9
  62. package/src/server/extensions/schedules.ts +1 -1
  63. package/src/server/extensions/subagents.ts +27 -7
  64. package/src/server/extensions/tool-search.ts +70 -20
  65. package/src/server/heic-convert.d.ts +11 -0
  66. package/src/server/heic-worker.ts +12 -0
  67. package/src/server/heic.ts +129 -0
  68. package/src/server/hooks.ts +29 -0
  69. package/src/server/host.ts +47 -0
  70. package/src/server/http/api.ts +42 -4
  71. package/src/server/http/assets.ts +13 -0
  72. package/src/server/http/browser-routes.ts +5 -1
  73. package/src/server/http/conversation-routes.ts +20 -5
  74. package/src/server/http/events.ts +1 -0
  75. package/src/server/http/extension-routes.ts +2 -0
  76. package/src/server/http/push-routes.ts +5 -2
  77. package/src/server/http.ts +33 -1
  78. package/src/server/linked-sessions.ts +21 -9
  79. package/src/server/memory.ts +6 -0
  80. package/src/server/model-images.ts +46 -8
  81. package/src/server/model-refresh.ts +5 -5
  82. package/src/server/paths.ts +8 -0
  83. package/src/server/pip-compact.ts +1 -1
  84. package/src/server/pip.ts +5 -1
  85. package/src/server/providers.ts +25 -11
  86. package/src/server/push.ts +10 -0
  87. package/src/server/reload.ts +2 -0
  88. package/src/server/room.ts +21 -0
  89. package/src/server/shell.ts +10 -6
  90. package/src/server/watches.ts +8 -0
  91. package/src/server/workspace.ts +30 -0
  92. package/src/server/worktrees.ts +5 -0
  93. package/types/pocket.d.ts +117 -1
  94. package/web/app.js +2 -0
  95. package/web/composer.js +24 -4
  96. package/web/desktop.js +117 -0
  97. package/web/extension-ui.js +124 -5
  98. package/web/files-panel.js +17 -3
  99. package/web/home.js +11 -0
  100. package/web/host.js +78 -0
  101. package/web/markdown-ext.js +45 -0
  102. package/web/math.js +58 -0
  103. package/web/model-refresh.js +30 -20
  104. package/web/notify.js +15 -2
  105. package/web/peeks.js +3 -2
  106. package/web/pip.js +3 -2
  107. package/web/quote-reply.js +8 -7
  108. package/web/quote-text.js +26 -0
  109. package/web/seen.js +3 -2
  110. package/web/sheets/custom-providers.js +278 -0
  111. package/web/sheets/extensions.js +11 -18
  112. package/web/sheets/gallery.js +0 -2
  113. package/web/sheets/hooks.js +112 -5
  114. package/web/sheets/menu.js +11 -0
  115. package/web/sheets/model.js +1 -3
  116. package/web/sheets/providers.js +207 -21
  117. package/web/sheets.js +0 -1
  118. package/web/store.js +25 -5
  119. package/web/style.css +414 -36
  120. package/web/theme-surface.js +7 -0
  121. package/web/transcript.js +135 -16
  122. package/web/ui.js +96 -7
  123. 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).
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.
@@ -47,10 +47,18 @@ 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.
53
57
 
58
+ ## Ordinary sessions an extension starts
59
+
60
+ `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.
61
+
54
62
  ## Linked sessions
55
63
 
56
64
  `LinkedSessions` (`linked-sessions.ts`, `app.linkedSessions`, `host.linkedSessions` as `LinkedSessionsApi`) starts a session from another and carries messages between them; Agent Teams (`extensions/agent-teams.ts`, off by default) is its only user. A linked session is an ordinary ownerless session in the source's folder. Its session entry's `linkedFrom` names the session that started it, and nothing else follows from it: it is not in `SubagentsDoc`, `parentOf`, or `rootOf`, so it gives no access, and stopping or archiving one leaves the other as it was.
@@ -77,6 +85,8 @@ PiP's header model chip opens the existing picker with its own conversation ID a
77
85
 
78
86
  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
87
 
88
+ 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.
89
+
80
90
  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
91
 
82
92
  ## Who chooses models
@@ -90,6 +100,8 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
90
100
  - **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
101
  - **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
102
 
103
+ **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.
104
+
93
105
  **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
106
 
95
107
  `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.
@@ -252,6 +264,8 @@ In the browser, the composer keeps a command's request id while its send is unre
252
264
 
253
265
  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
266
 
267
+ **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.
268
+
255
269
  **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
270
 
257
271
  **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
 
@@ -62,7 +65,7 @@ Use a template for a message that people send often. Use a skill for steps that
62
65
 
63
66
  ## Models and providers
64
67
 
65
- 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, add it to `models.json` as Pi's `models.md` says. 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).
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).
66
69
 
67
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.
68
71
 
@@ -77,7 +80,7 @@ People sign in to providers in Menu → **Providers**, and pick a model for each
77
80
 
78
81
  Models are the person's choice, never Pi's:
79
82
 
80
- - 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).
81
84
  - PiP gives a model only when its person named it.
82
85
 
83
86
  Instructions, skills, and `AGENTS.md` cannot change this. Tell the person where the setting is instead.
@@ -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.
@@ -18,7 +18,7 @@ A linked session is an ordinary session. The session list shows it under the ses
18
18
 
19
19
  - `cwd` selects an existing working folder using the same path rules as the folder picker (including `~`). Prefer an absolute path. A blank `cwd` counts as no `cwd`. A relative `cwd` resolves against the folder of the server process, not the folder of the source. The child loads that folder's project context and tools; the source stays in its own folder. A missing path or a file is rejected before a session is created. Since 0.19.0: an older Pi Pocket ignores `cwd` and uses the source's folder, so a gallery entry that needs it sets `minPocket` to `0.19.0`.
20
20
  - Without `title`, the title is the first line of the message.
21
- - `model` is `provider/modelId`. While the owner's list (Menu → Providers → Models for subagents) is empty, it must be the source's model. Once the list has models, it must be one of them, and the source's own model counts only when it is listed. Without `model`, the session uses the source's model if the list is empty or has it. If the list does not have it, the call is refused with an error that names the allowed models: the caller must choose one (the error is a 400 for a human route).
21
+ - `model` is `provider/modelId`. While the owner's list (Menu → Providers → Subagent models) is empty, it must be the source's model. Once the list has models, it must be one of them, and the source's own model counts only when it is listed. Without `model`, the session uses the source's model if the list is empty or has it. If the list does not have it, the call is refused with an error that names the allowed models: the caller must choose one (the error is a 400 for a human route).
22
22
  - `send` refuses a session that runs on a model off the list (a person changed it, or the owner changed the list), when the list is not empty. A message from a linked session to the session that started it is a reply, not work: it goes whatever model that session runs on.
23
23
  - `thinking` can be any level, also one above the source's. Without it, the session uses the source's level. Pi Pocket lowers it to the highest level that the model has, or uses the lowest level of the model when it has none that low.
24
24
  - When a model cannot be used now, Pi Pocket refuses the call before it makes anything.
@@ -42,10 +42,13 @@ 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)`
48
50
  - `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental)); `stop`, `archive` (experimental, since 0.28.0)
51
+ - `sessions.start` (experimental, since 0.28.0: [Starting an ordinary session](../sessions.md))
49
52
  - `text`: `quoted`, `defang`
50
53
  - `thinkingLevels`
51
54
  - `fetchPublic(url, init)` (experimental, since 0.20.0)
@@ -62,7 +65,7 @@ The host's members do not change while modules reload. A new member comes only a
62
65
  - `provide`, `use`, `onService`, `settings`, `setting`, and `onSettings` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md)).
63
66
  - `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
67
  - `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.
68
+ - 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
69
  - 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
70
  - `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage` (experimental, since 0.28.0): read-only usage for a visible conversation and its visible descendants.
68
71
  - 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 +171,10 @@ Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` fi
168
171
 
169
172
  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
173
 
174
+ Since 0.28.0, `host.registerWorkspaceProvider`, `WorkspaceProvider`, `host.cwdOf`, and `WebRequest.createSession` are experimental: [Execution environments for workspaces](../workspaces.md).
175
+
176
+ Since 0.28.0, `pocket.fence` and `pocket.mathInline` are experimental, with `FenceSpec`, `MathInlineSpec`, and `FenceProps`.
177
+
171
178
  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
179
 
173
180
  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`.
@@ -28,6 +28,10 @@ Sections render before each request. Pi Pocket sends again only the sections tha
28
28
  - Put the date in a section, not the time.
29
29
  - Do not put counters in a section.
30
30
 
31
+ ## A section for one tool
32
+
33
+ A section about a tool shows while `input.agent.tools` has the tool. In codemode's Only mode, scripts alone call most tools, so also show it when `input.agent.callable` has the tool with `callers` that leave out `"model"`, as `browser.ts` does.
34
+
31
35
  ## A section for one session
32
36
 
33
37
  `input.conversationId` is the session. `input.read.snapshot(Doc, input.conversationId, context)` reads a document of that session. Use them to write a section that depends on the session.
@@ -91,3 +91,4 @@ Each member in the reference has its own Since line. These parts came together:
91
91
  | Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
92
92
  | Read-only conversation and descendant usage: `ConversationWebRequest.conversationUsage` (experimental) | 0.28.0 |
93
93
  | How a run stopped: `outcome` and `failure` on `run.ended`, and `failed` on a linked session (experimental) | 0.28.0 |
94
+ | `host.sessions.start` (experimental) | 0.28.0 |
@@ -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`
@@ -98,7 +108,7 @@ subagentModels(): readonly string[];
98
108
 
99
109
  Since 0.13.1 · Stable
100
110
 
101
- The models that the owner lets subagents use, as `provider/modelId`. While the list is empty (the default), a subagent runs on the model of its own session. Once it has models, subagents and linked sessions run only on those: the model of the session when it is listed and none is named; when it is not listed, the caller must name a listed model. The owner sets it in Menu → Providers → Models for subagents.
111
+ The models that the owner lets subagents use, as `provider/modelId`. While the list is empty (the default), a subagent runs on the model of its own session. Once it has models, subagents and linked sessions run only on those: the model of the session when it is listed and none is named; when it is not listed, the caller must name a listed model. The owner sets it in Menu → Providers → Subagent models.
102
112
 
103
113
  ### `modelProblem`
104
114
 
@@ -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
@@ -381,6 +403,41 @@ What `fetchPublic` takes besides the address.
381
403
  - `maxBytes`: the size of the body at most, after it is decoded.
382
404
  - `timeoutMs`: the time for the whole request at most, the body included.
383
405
 
406
+ ## Ordinary sessions
407
+
408
+ ### `sessions`
409
+
410
+ ```ts
411
+ readonly sessions: Sessions;
412
+ ```
413
+
414
+ Since 0.28.0 · Experimental
415
+
416
+ Lets an extension start an ordinary session, the same kind a person gets from New session. [Starting an ordinary session](../sessions.md) tells you who it acts for, what it checks, and what the new session is.
417
+
418
+ The call acts as the person that Pi works for in `source`, and that person's checks apply. Give it a `key` that stays the same when the call runs again. A second call with the same `key` returns the session the first call made, and sends its message once. It acts for the person of the first call, and it does not check the model, the folder, or the spend limit again. A `key` of `linkedSessions.start` never finds a session of this API.
419
+
420
+ #### `sessions.start`
421
+
422
+ ```ts
423
+ start(
424
+ source: ConversationId,
425
+ request: { title?: string; cwd?: string; model?: string; thinking?: string; message?: string },
426
+ key: string,
427
+ ): Promise<{ session: ConversationId }>;
428
+ ```
429
+
430
+ Since 0.28.0 · Experimental
431
+
432
+ Makes a top-level session and, when `message` is given, sends that text as its first message. It returns the new session's id.
433
+
434
+ - The new session works in `cwd` when supplied, otherwise the server's default folder. `cwd` must name an existing folder and uses the normal folder-picker path rules. A missing folder is refused before a session is made.
435
+ - `model` is `provider/modelId`. It must be a model known here whose provider can be used now. Without it, the session starts on the model a new session would get. The owner's list of models for subagents does not apply.
436
+ - `thinking` is any level. Pi Pocket lowers it to the highest level the model has, or uses the model's lowest when it has none that low. Without it, the session keeps the thinking level it started with.
437
+ - The new session has no `linkedFrom`. It is its own row in the session list, and it can start linked sessions of its own.
438
+ - A source past its spend limit, a person invited to one session, and a PiP source are refused, and nothing is made.
439
+ - A blank `message` is refused, and nothing is made. A `message` is also refused when the session gets no model: no `model` and no default model.
440
+
384
441
  ## Linked sessions
385
442
 
386
443
  ### `linkedSessions`
@@ -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
@@ -128,6 +128,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
128
128
  | `home` | The home screen on wide screens |
129
129
  | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
130
130
  | `home-actions` | Its buttons |
131
+ | `home-menu` | Its menu button, top right: the menu without a session's items |
131
132
  | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
132
133
  | `home-list` | The session list as a phone's home screen |
133
134
  | `pane` | The conversation's window (or the subagents board, or an extension's page) |
@@ -143,6 +144,8 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
143
144
  | `prompt` | A person's message |
144
145
  | `prompt-head`, `author-mark`, `prompt-author` | Its head: who sent it and when; their initials; their name |
145
146
  | `prompt-text` | What it says (its skill chip, words, and files) |
147
+ | `linked-head`, `linked-mark`, `linked-name` | A linked session's message (`data-from` `linked`): its head, square mark, session name (since 0.28.0) |
148
+ | `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
149
  | `presented-input`, `presented-head` | An extension's input (`web.presentEntry`), folded: its card and the line that opens it (since 0.28.0) |
147
150
  | `presented-chevron`, `presented-tag` | That line's chevron; the input's label in its head, when shown open (since 0.28.0) |
148
151
  | `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,37 @@
1
+ # Starting an ordinary session
2
+
3
+ An extension can start an ordinary session, the same kind a person gets from New session. Use `host.sessions.start`. Its shape is in [the host reference](reference/host.md).
4
+
5
+ **Experimental, since 0.28.0.** It can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)). A module for an older server checks that `host.sessions` is there, and a gallery entry that needs it sets `minPocket` to `0.28.0`.
6
+
7
+ ## What the call does
8
+
9
+ `start(source, { title?, cwd?, model?, thinking?, message? }, key)` makes a session and returns `{ session }`, its id.
10
+
11
+ - The session is top-level. It has no `linkedFrom`, and it shows as its own row in the session list. It can itself start linked sessions.
12
+ - It works in `cwd` when supplied, otherwise the server's default folder. `cwd` uses the same path rules as the folder picker, including `~`. A missing path or a file is rejected before a session is created.
13
+ - Without `title`, the title is the folder's name, as for New session.
14
+ - `model` is `provider/modelId`. It must be a model known here, and its provider must be usable now. Without `model`, the session starts on the model a new session would get. The owner's list of models for subagents does not apply: this is an ordinary session, not a subagent and not a linked session.
15
+ - `thinking` is any level. Pi Pocket lowers it to the highest level the model has, or uses the model's lowest when it has none that low, as it does for a linked session. This is the named model, or the default model when `model` is not given. Without `thinking`, the session keeps the thinking level it started with.
16
+ - With `message`, that text is the session's first message. It is an ordinary message from the person Pi works for in `source`, not a message sent for them.
17
+
18
+ ## Who it acts for
19
+
20
+ The call acts for the person Pi works for in `source`. That person must be able to see the source, steer, and start sessions.
21
+
22
+ Pi Pocket refuses the call, and makes nothing, when:
23
+
24
+ - nobody is the person Pi works for in the source, or that person cannot see the source;
25
+ - the source is a PiP conversation;
26
+ - that person was invited to one session;
27
+ - the source is past its spend limit;
28
+ - `model` is unknown, or its provider cannot be used now;
29
+ - `cwd` does not name an existing folder;
30
+ - `cwd` is a remote workspace, and that person is not the owner;
31
+ - `message` is blank, or the session gets no model to send it to (no `model` and no default model).
32
+
33
+ ## Once
34
+
35
+ Give the call a `key` that stays the same when it runs again, such as `${api.taskId}:${api.callId}`. A second call with the same `key` from the same source returns the session the first call made. It acts for the person the first call acted for, also when someone else wrote in the source since then. It does not check the model, the folder, or the spend limit again: a source that has reached its spend limit since then still gets its session back. When `message` is given, it is sent once: the repeat finds the message the first call sent.
36
+
37
+ The keys of this call are apart from those of `linkedSessions.start`. The same `key` given to both starts two sessions, one of each kind.
@@ -27,7 +27,7 @@ export default function createMyWords() {
27
27
 
28
28
  - `name` must be different from the name of each other tool ([Names](reference/names.md)). Use a prefix of your own.
29
29
  - `description` and `parameters` go to the model with each request. Keep them short and exact.
30
- - `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at 16,000 characters in a plain session.
30
+ - `deferred: true` keeps a tool out of the requests until Pi loads it with `tool_search`, which only the Tool search module offers: while it is off, Pi cannot load the tool. Use it for a tool that few conversations need, or for a large set of tools. `test/prompt-budget.test.ts` keeps Pi Pocket's own prompt and tools at 11,000 characters (about 4,000 tokens) in a plain session.
31
31
  - `parameters` is a TypeBox schema (`Type` from `@earendil-works/pi-ai`). Pi Durable checks the arguments against it before `execute` runs.
32
32
  - `execute(args, api, context)` does the work.
33
33