pi-pocket 0.28.2-beta.1 → 0.29.0-beta.1

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 (45) hide show
  1. package/docs/architecture.md +5 -4
  2. package/docs/customizing.md +1 -1
  3. package/docs/extensions/linked-sessions.md +2 -0
  4. package/docs/extensions/policies/api-stability.md +1 -1
  5. package/docs/extensions/reference/api-versions.md +3 -0
  6. package/docs/extensions/reference/host.md +15 -1
  7. package/docs/extensions/reference/pocket.md +12 -1
  8. package/docs/extensions/reference/types.md +19 -1
  9. package/docs/extensions/tools.md +18 -0
  10. package/docs/features.md +5 -5
  11. package/docs/map.md +6 -4
  12. package/npm-shrinkwrap.json +2 -2
  13. package/package.json +1 -1
  14. package/src/server/app.ts +2 -7
  15. package/src/server/browser/cdp.ts +6 -0
  16. package/src/server/browser/identity.ts +55 -0
  17. package/src/server/browser/page.ts +12 -1
  18. package/src/server/browser.ts +1 -0
  19. package/src/server/commands.ts +26 -5
  20. package/src/server/config.ts +10 -0
  21. package/src/server/custom-providers.ts +298 -23
  22. package/src/server/docs.ts +10 -3
  23. package/src/server/extensions/agent-teams.ts +9 -1
  24. package/src/server/extensions/subagents.ts +51 -3
  25. package/src/server/host.ts +12 -3
  26. package/src/server/http/assets.ts +26 -3
  27. package/src/server/http/io.ts +11 -1
  28. package/src/server/http/link-routes.ts +4 -1
  29. package/src/server/http.ts +29 -3
  30. package/src/server/linked-sessions.ts +92 -9
  31. package/src/server/project-model.ts +17 -1
  32. package/types/pocket.d.ts +38 -4
  33. package/web/app.js +3 -2
  34. package/web/back.js +27 -6
  35. package/web/browser-panel.js +23 -12
  36. package/web/browser-paste.js +13 -0
  37. package/web/composer.js +7 -3
  38. package/web/extension-ui.js +17 -2
  39. package/web/index.html +2 -0
  40. package/web/running-board.js +38 -36
  41. package/web/sheets/custom-providers.js +420 -21
  42. package/web/sheets/memory.js +76 -40
  43. package/web/store.js +117 -22
  44. package/web/style.css +151 -11
  45. package/web/transcript.js +57 -11
@@ -97,13 +97,13 @@ A repository watch (`repo-watches.ts`) is an item of the app-wide `RepoWatchesDo
97
97
  Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the side. Everything that runs a model uses one a person chose:
98
98
 
99
99
  - **Sessions** run on the model someone picked, or on what a new session starts with (`Commands.#defaultModel`): the owner's default, even when it is not signed in now, else a trusted project's model/thinking default, else the last model picked, else Pi's global default, else none. `project-model.ts` reads only the final session folder's `.pi/settings.json` at creation, without a cache; a fresh creation-local global-only settings reader supplies defaults and trust policy without changing `app.settings`. It checks Pi's trust store and global trust policy, validates a complete provider/model pair, and keeps known unsigned models rather than silently substituting one. Invalid trusted settings stop creation with a contained error. Thinking-only settings cannot change another source's model/thinking pair. Owner defaults bypass project settings. Imported sessions, forks, subagents, manual choices, and PiP's own conversation retain their previous selection behavior. A model the person explicitly named to PiP bypasses project defaults before its manual configuration step. Trust gained after creation applies only to later new sessions; existing choices never track file or folder changes. Extra project skill/prompt paths and per-project run policy are not supported yet; the shared app settings and older host APIs are unchanged.
100
- - **Subagents** run at their session's thinking level unless the spawn names another, of any height (`extensions/subagents.ts`), on their session's model while the owner's list is empty, and only on a listed model once it is not: the session's model when listed and none is named, else the model named, which is required when the session's is not listed (the refusal lists the allowed models; the prompt section lists them too, each with the facts from `host.modelInfo` that help choose: thinking, context window, price; `model-facts.ts`). The owner may allow models (`subagentModels` in `config.json`: `PocketApp.setSubagentModels` replaces the list, and `allowSubagentModel`, behind `POST /api/subagent-models` that the Providers sheet sends, adds or takes off one model, reading and writing the list with no wait between, so changes that come together all count); with none allowed the tool has no model parameter, and the app rebuilds the module when the list changes. Each call checks the list as it is then: a model not on it (the session's own included) is refused, and so is work for a subagent already on one; a subagent has no `subagent` or `team` tool, so none starts a nested one; a person may raise a subagent's thinking by hand, and work sent to it leaves that level. Before an allowed model is used its sign-in is asked afresh, so a stale mark neither refuses it nor lets it through. A report of a subagent its model or provider failed (by the provider's words: a sign-in, a missing or refused model, a quota) carries the model and tells Pi to stop and tell its person.
100
+ - **Subagents** run at their session's thinking level unless the spawn names another, of any height (`extensions/subagents.ts`), on their session's model while the owner's list is empty, and only on a listed model once it is not: the session's model when listed and none is named, else the model named, which is required when the session's is not listed (the refusal lists the allowed models; the prompt section lists them too, each with the facts from `host.modelInfo` that help choose: thinking, context window, price; `model-facts.ts`). The owner may allow models (`subagentModels` in `config.json`: `PocketApp.setSubagentModels` replaces the list, and `allowSubagentModel`, behind `POST /api/subagent-models` that the Providers sheet sends, adds or takes off one model, reading and writing the list with no wait between, so changes that come together all count); with none allowed the tool has no model parameter, and the app rebuilds the module when the list changes. Each call checks the list as it is then: a model not on it (the session's own included) is refused, and so is work for a subagent already on one; a subagent has no `subagent` or `team` tool, so none starts a nested one; a person may raise a subagent's thinking by hand, and work sent to it leaves that level. Before an allowed model is used its sign-in is asked afresh, so a stale mark neither refuses it nor lets it through. An explicit tool list also gets tools marked `subagents: "always"` by its selected extensions, never one removed for subagents or absent from a fixed extension list; marked deferred tools are offered at once, and script-only tools bring codemode. A report of a subagent its model or provider failed (by the provider's words: a sign-in, a missing or refused model, a quota) carries the model and tells Pi to stop and tell its person.
101
101
  - **Linked sessions** (Agent Teams) start on a model the owner allows for subagents (their session's model when it is listed and none is named, else the model named, which is required when the session's is not listed; with no list, their session's model), and get messages from Pi only while they run on one, at their session's thinking level unless the start names another (`linked-sessions.ts`); a model that cannot be used now is refused before the session is made.
102
102
  - **Titles, compaction, and PiP's summaries** use the conversation's own model.
103
103
  - **PiP** passes a model, or names one in what it sends, only when its person named it in their own words (`pip.ts`, with `model-names.ts`): their own messages (`u:` request ids, from the authors document) since PiP's last new context (with those its last compaction kept), and the standing instructions of the watches and webhooks to PiP that they set up; never a watch PiP set up, what was posted, or what GitHub said.
104
104
  - **Sign-ins:** `Providers` asks subscriptions' sign-ins afresh (the owner's Providers sheet, a model a subagent on another model or PiP is about to use, a run that failed on one, a run answered by a marked one) and keeps, in memory, the ones their provider refused to renew. Only subagents on another model (`resolveModel`, `modelProblem`), PiP, and linked sessions as they start (`Providers.problem`) check before use, and refuse their models. Everything else tries the model: a session's own run and a subagent on its session's model fail where people see them, and a run that failed on an expired sign-in marks it; a title that fails is only logged. `modelList` and `agentInfo` mark them, and the owner is told. A check that began before a sign-in or sign-out here marks nothing.
105
105
 
106
- **OpenAI-compatible endpoints.** `app.customProviders` (`custom-providers.ts`) is the owner's only (`/api/custom-providers`, `requireOwner`). Changes run one after another. Each reads Pi's `models.json`, refuses to rewrite one that is not plain JSON or that Pi's own check (`ModelRuntime.create({ refreshOnCreate: false })`) refuses, writes the whole file at once (temporary file, rename, mode 600), then reloads only that provider (`models.refresh({ providers: [id], allowNetwork: false })`) and sends `models`. It manages only entries with `api: "openai-completions"`, a `baseUrl`, and an id that is not built in; it keeps fields it does not set. A key goes through `models.login(id, "api_key")` into `auth.json`, never into `models.json`; an endpoint without a key gets `apiKey: "none"`. Discovery reaches any address, a private one too, because only the owner can ask, and such servers are often local; its errors are fixed messages, never the fetch error, which can carry the key.
106
+ **OpenAI-compatible endpoints.** `app.customProviders` (`custom-providers.ts`) is the owner's only (`/api/custom-providers`, `requireOwner`). Changes run one after another. Each reads Pi's `models.json`, refuses to rewrite one that is not plain JSON or that Pi's own check (`ModelRuntime.create({ refreshOnCreate: false })`) refuses, writes the whole file at once (temporary file, rename, mode 600), then reloads only that provider (`models.refresh({ providers: [id], allowNetwork: false })`) and sends `models`. It manages only entries with `api: "openai-completions"`, a `baseUrl`, and an id that is not built in; it keeps fields it does not set. Of a model's fields it sets only `input` (`["text", "image"]` for **Images**); thinking: `reasoning: true` with a `thinkingLevelMap` that names every level, `null` for each level the model does not have, so Pi's model menu offers exactly the chosen ones, read back the way Pi does (`tiersOfEntry`); `contextWindow` and `maxTokens` (whole tokens, left out for Pi's defaults of 128000 and 16384); and `cost` in dollars per million tokens (input and output required, cache ones 0 when not given, the whole field left out for no price), which keeps a hand-made `cost.tiers`. The owner sets all of these by hand: discovery reads only the model ids and vLLM's `max_model_len` (as the context window), because model lists have no common format for what a model can do or costs. A key goes through `models.login(id, "api_key")` into `auth.json`, never into `models.json`; an endpoint without a key gets `apiKey: "none"`. Discovery reaches any address, a private one too, because only the owner can ask, and such servers are often local; its errors are fixed messages, never the fetch error, which can carry the key.
107
107
 
108
108
  **Manual model refresh.** `Providers.modelRefresh` (`model-refresh.ts`) shares one in-flight refresh across owner tabs. `POST /api/models/refresh` requires the owner and the normal `X-Pocket` header; `hello.server.refreshModels` gates the UI against an older server. It checks local configuration with Pi’s public runtime API before reloading it, then refreshes each configured provider in parallel with a separate eight-second limit and `force: true` (network stays off under `PI_OFFLINE`). Each completed provider sends the existing `models` event and refreshes room views, so a slow provider does not hold back a healthy one. Pi owns cache publication and cancellation generations; failed catalog fetches keep its cached/static models. Refresh never configures a conversation or changes the default or subagent allow-list. Counts compare available provider/id keys before and after; provider errors are safe fixed messages, not raw exceptions that could contain credentials.
109
109
 
@@ -192,9 +192,9 @@ A full view for a tab of protocol 4 has the order of every entry in the active c
192
192
 
193
193
  A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
194
194
 
195
- A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/text-hash.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
195
+ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 32 million characters of JSON, about 50 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/text-hash.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
196
196
 
197
- The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
197
+ The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. The signed-in app page carries that identity and build, never a token, so the same check can show a device copy before `/api/me` answers; its answer checks the copy again and drops it if the identity, rights, build, or cache policy changed. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
198
198
 
199
199
  Browser drafts, and the panel each session last showed (`pocket.person.<person>:layouts`; the tab's copy in `sessionStorage` names its person too), use `web/person-storage.js`: `pocket.person.<person>:…` keys, readable after `/api/me` or an event-stream hello identifies the person. An account signal invalidates answers already on their way, including at startup. Sign-out stops the device cache and attachments before the server request; after it finishes, it clears this storage, changes `pocket.person`, broadcasts the account change, and goes to `/`. Other tabs stop their cache on the early `pocket.signedOut` signal, but reload only on the completed account change. On Back, a cover checks `/api/me` before reconnecting; the same person keeps the document and drafts. Each check has a 10 s timeout; failures retry with backoff up to 30 s, or at once with Retry.
200
200
 
@@ -294,6 +294,7 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
294
294
  **History is the back stack (`back.js`).** Only `back.js` writes history. Each route (`/s/12`) and each layer over it (a sheet, the drawer, the launcher, the Files tile or Browser panel where they cover the screen, a file over the tile's tree) is an entry, and each entry says how many layers it stands for and how many steps back the session list's entry is. The app's state is the truth and history follows it a moment later: opening a layer pushes an entry, closing one with a tap goes back past it, and a new route first goes back past the layers above the current one. Back that the person makes closes the layers above the entry it lands on; back to another route reaches `store.js` through `onRoute`. Traversals `back.js` makes itself reach no one. So:
295
295
 
296
296
  - Navigate with `navigate()` (which calls `pushRoute`); do not call `history.pushState` or `history.back()` elsewhere. To drop a query from the address, use `replaceAddress`, which keeps the entry's marks.
297
+ - A way up (a subagent's **Back to main session**) uses `navigateUp()`, not `navigate()`: a forward entry would put the route left between two entries of the one above it, and back would open it again. Each route's entry keeps the route it was opened over (`from`, read with `routeUnder`); when that is the way up's target, `navigateUp` goes back to it (`popRoute`), else it takes this route's place (`replace`).
297
298
  - Something new that covers the screen, or that back should close, is a layer: `useBack(open, close)` in the component that shows it, where `close` makes `open` false. Sheets get theirs from `sheets.js`, one per sheet opened from another (the menu, then the model picker).
298
299
  - On phones the window clips sideways: the conversation sliding in from the right (a route, a swipe's lean) would make the page wider than the screen, and a phone's browser widen and pan its view to fit.
299
300
  - A finger's or a mouse's press and click within 280 ms of a layer opening or closing, or a route opening, at a tap (a pointer let go in the 400 ms before) is let go, focus and all: a quick second tap would land on whatever slid in under it (a tile of the sheet that rose, the scrim that closes it). What moves on its own (a reply opening a session, the server closing a sheet, Escape) holds nothing back, and keys and scripts never are.
@@ -65,7 +65,7 @@ Use a template for a message that people send often. Use a skill for steps that
65
65
 
66
66
  ## Models and providers
67
67
 
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).
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, each with **Images**, its thinking levels, its context window and maximum output, and its price. 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, price tiers), add it to `models.json` as Pi's `models.md` says; the form keeps those fields when it edits the endpoint. A provider that needs code comes as a Pi Pocket drop-in that calls `host.registerModelProvider` ([host.md](extensions/reference/host.md#registermodelprovider)), not as a Pi extension: see [Pi's extensions and packages](#pis-extensions-and-packages).
69
69
 
70
70
  **A Claude subscription.** Sign in to Anthropic with it in Providers. Then turn on **Claude subscription billing** in Menu → Extensions → Installed → **Built in**, so that requests count against the plan. It is off by default, and it asks before it turns on. Without it, Anthropic can bill the requests as extra usage, and refuse them when that is used up.
71
71
 
@@ -52,6 +52,8 @@ Since 0.28.0, when a linked session's run ends, Pi Pocket sends the session that
52
52
 
53
53
  So a tool that starts linked sessions need not ask them to report, and need not poll: the lead ends its turn, and the answers wake it. The report's fence shows as a linked session's card, like a message. Only the session that started one hears its end of run: a linked session that asks its lead, or a sibling, gets an answer only when that session sends one, and the message tells it to.
54
54
 
55
+ A lead can turn this off with `host.linkedSessions.reports(lead, { take: false }, key)`. Then no run end of a session it started reaches it: old ones, archived ones, from any start path. A message from it then asks the target to send the answer, and `send` returns `answers: false`. `take: true` turns the answers back on. An older Pi Pocket has no `reports`: check for it.
56
+
55
57
  ## Stop a run
56
58
 
57
59
  `stop(source, { to }, key)` stops the run of the linked session at the address `to`, and withdraws what waits in its queue. Stopping is the safe direction: it needs the same access as `send`, including the turn and room under the spend limit.
@@ -81,7 +81,7 @@ The host's members do not change while modules reload. A new member comes only a
81
81
  - `version`, `module`, `title`, and `pocketVersion` (connected-server package version, since 0.16.0; not the API level).
82
82
  - `h`, `html`, `Fragment`, and the hooks: `useState`, `useEffect`, `useLayoutEffect`, `useRef`, `useMemo`, `useCallback`, and `useReducer`.
83
83
  - The pieces `Icon`, `Loader`, `Spinner`, `Markdown`, and `Switch`, with the props that [pocket](../reference/pocket.md) gives.
84
- - `api`, `on`, `rail`, `menu`, `launcher`, `page`, `sheet`, `toolCall`, `openPage`, `closePage`, `openSheet`, `closeSheet`, `notify`, `me`, `conversationId`, `openConversation` (since 0.16.0), `style`, and `onDispose`.
84
+ - `api`, `on`, `rail`, `menu`, `launcher`, `page`, `sheet`, `toolCall`, `openPage`, `closePage`, `openSheet`, `closeSheet`, `notify`, `me`, `conversationId`, `openConversation` (since 0.16.0; its `options.artifact` and `options.version` are experimental, since 0.29.0), `style`, and `onDispose`.
85
85
  - What a page's or a sheet's component gets: `pocket`, `close`, and a sheet's `props`.
86
86
  - The icon names that [pocket](../reference/pocket.md) lists. Other icon names can go. An unknown name shows `grid`, so a module does not fail.
87
87
  - Safe mode: `?noext=1` and `?noext=0` on the app's address.
@@ -98,3 +98,6 @@ Each member in the reference has its own Since line. These parts came together:
98
98
  | Presented inputs: `web.presentEntry` and `pocket.entryPresentation` (experimental) | 0.28.0 |
99
99
  | Fenced blocks and inline math: `pocket.fence` and `pocket.mathInline` (experimental) | 0.28.0 |
100
100
  | `answers` from `linkedSessions.send` (experimental) | 0.28.0 |
101
+ | `linkedSessions.reports`: a lead turns off run-end answers (experimental) | 0.29.0 |
102
+ | `options.artifact` and `options.version` in `pocket.openConversation`: open an artifact of that session (experimental) | 0.29.0 |
103
+ | `subagents: "always"` on a tool: the tool comes with every subagent that has a tool list (experimental) | 0.29.0 |
@@ -464,7 +464,7 @@ start(
464
464
 
465
465
  Since 0.14.0 · Experimental
466
466
 
467
- Makes a session linked to `source` and sends it `message` as its first message. It returns the new session's id, and the address that `source` uses for it.
467
+ Makes a session linked to `source` and sends it `message` as its first message. It returns the new session's id, and the address that `source` uses for it. `answers` (since 0.29.0) says whether its final answer comes back to `source` by itself: it is `false` when `source` turned its answers off with [`linkedSessions.reports`](#linkedsessionsreports). An older Pi Pocket does not return it.
468
468
 
469
469
  - The new session works in `cwd` when supplied, otherwise the folder of `source`. `cwd` must name an existing folder and uses the normal folder-picker path rules. A blank `cwd` counts as no `cwd`. A relative `cwd` resolves against the folder of the server process, not the folder of the source. `cwd` is since 0.19.0: an older Pi Pocket ignores it and uses the folder of `source`, so a gallery entry that needs it sets `minPocket` to `0.19.0`. It gets a copy of the agent settings of `source`, but not its history.
470
470
  - Without `title`, the title is the first line of `message`.
@@ -516,6 +516,20 @@ Since 0.28.0 · Experimental
516
516
 
517
517
  Archives the linked session at the address `to`. With `archived: false`, it brings the session back. Without `archived`, it archives. `archived` in the result says whether the session is archived now. `repeating` is how many of its repeating schedules keep running: an archive does not stop them. It needs the same access as `send`. An older Pi Pocket has no `archive`.
518
518
 
519
+ #### `linkedSessions.reports`
520
+
521
+ ```ts
522
+ reports(
523
+ source: ConversationId,
524
+ request: { take: boolean },
525
+ key: string,
526
+ ): Promise<{ take: boolean }>;
527
+ ```
528
+
529
+ Since 0.29.0 · Experimental
530
+
531
+ Sets whether `source`, as a lead, takes the final answers of the sessions it started when their runs end. By default it takes them. With `take: false`, no run end of a session it started reaches it: old ones, new ones, archived ones, from any start path. `send` from `source` then returns `answers: false`, and its message asks the target to send the answer. With `take: true`, the answers come back. `take` in the result says the state now. The switch is stored on the session `source`. It needs the same access as `archive`, but on `source` itself: the turn, no plan mode, and room under the spend limit. A repeat with the same `key` changes nothing again and returns the first result, even with other arguments. A `take` that is not a boolean throws a `TypeError`, and nothing is stored. An older Pi Pocket has no `reports`: check for it.
532
+
519
533
  #### `linkedSessions.list`
520
534
 
521
535
  ```ts
@@ -251,13 +251,24 @@ The id of the session that this tab shows, a number as in its address (`/s/12`),
251
251
  ### `openConversation`
252
252
 
253
253
  ```ts
254
- openConversation(id: number | string): void;
254
+ openConversation(id: number | string, options?: { artifact?: string; version?: number }): void;
255
255
  ```
256
256
 
257
257
  Since 0.16.0 · Stable
258
258
 
259
259
  Open a positive integer conversation id through normal app navigation. This closes the extension page and keeps normal Back behavior. Sheets close when changing conversations; call `pocket.closeSheet()` first to close your own sheet even when that conversation is already open. The server still checks access; an id grants no access. Invalid ids throw. Use a bound start's `session` or a human list item's `conversationId`, not a private app URL.
260
260
 
261
+ `options.artifact` (since 0.29.0 · experimental) opens the app's artifact viewer on that artifact of the conversation, after the conversation opens. `options.version` is a positive integer; without it the viewer shows the latest version. It returns nothing. The server still checks access when the conversation loads, so a missing artifact or no access fails quietly, as in the Artifacts sheet. A `artifact` that is not a string, or a `version` that is not a positive integer, is ignored. Older apps ignore `options` and only open the conversation.
262
+
263
+ ```js
264
+ // A page lists artifacts that agents made in other sessions: a tap opens one in the viewer.
265
+ html`<button
266
+ onClick=${() => pocket.openConversation(ask.session, { artifact: "intake-502-check", version: 2 })}
267
+ >
268
+ Read the plan
269
+ </button>`;
270
+ ```
271
+
261
272
  ### `onConversation`
262
273
 
263
274
  ```ts
@@ -47,7 +47,7 @@ The types file imports types from Pi Durable, Pi AI, and Preact by package name.
47
47
  - [`Web`](web.md) and the types that it uses: `WebAccess`, `WebMethod`, `WebHandler`, and `WebRequest`.
48
48
  - [`Command`, `CommandContext`, and `CommandResult`](command-context.md).
49
49
  - [`Pocket`](pocket.md) and the types that it uses: `BrowserModule`, `Action`, the objects that you give (`RailSpec`, `MenuSpec`, `LauncherSpec`, `PageSpec`, `SheetSpec`, `ToolCallSpec`, `CallSummary`), `Added`, `PageProps`, `SheetProps`, and the props of the pieces.
50
- - `Module`, `Person`, `Role`, and `NoticeLevel`, on this page.
50
+ - `Module`, `ToolOptions`, `Person`, `Role`, and `NoticeLevel`, on this page.
51
51
  - Since 0.22.0, experimental: `PublicPageHandler`, `PublicPageRequest`, `PublicPageAnswer`, `PublicLinks`, `PublicLinkRequest`, and `PublicLinkInfo` ([Public pages](../public-pages.md)); `AskRequest`, `AskField`, `AskAnswer`, `HiddenValue`, `CommandRun`, `CommandEnvProvider`, `BrowserPageHandle`, `BrowserControl`, and `BrowserTarget` ([People's values](../people-values.md)); `AppEvents`, `AppEventName`, `SettingField`, and `SettingValue` ([Events, services, and settings](../services-settings.md)).
52
52
 
53
53
  The types file does not have the internal members of the host. It does not have Pi Durable's own API either: import `defineExtension`, `defineTool`, and the rest from `@earendil-works/pi-durable`.
@@ -89,6 +89,24 @@ Since 0.14.0 · Stable
89
89
 
90
90
  The version of the extension API that the module needs. A Pi Pocket with an older version does not set up the module. See [API versions](api-versions.md#pocketapi).
91
91
 
92
+ ## Tool options
93
+
94
+ ### `ToolOptions`
95
+
96
+ ```ts
97
+ interface ToolOptions {
98
+ readonly subagents?: "always";
99
+ }
100
+ ```
101
+
102
+ Since 0.29.0 · Experimental
103
+
104
+ Pi Pocket's options on a tool definition, beside Pi Durable's own. Add them with `Object.assign` after `defineTool` ([Tools](../tools.md#tools-for-every-subagent)).
105
+
106
+ - `subagents: "always"`: give the tool to every subagent whose extensions include it, when the session enables it, even when its `tools` list leaves it out. It is added once. A deferred tool is offered at once with a tool list; a tool that only scripts call brings codemode. Without a list, or on send, nothing changes. It does not add its extension. The tool's prompt and spawn result do not mention the marker or the tools it adds.
107
+
108
+ Older Pi Pocket ignores the field. The API version stays 2: this is an addition, not a break.
109
+
92
110
  ## Shared types
93
111
 
94
112
  ### `Person`
@@ -31,6 +31,24 @@ export default function createMyWords() {
31
31
  - `parameters` is a JSON Schema object. Build it with the builders of `@earendil-works/pi-schema`: `obj`, `str`, `num`, `int`, `bool`, `arr`, `union`, and `opt` for a property that can be left out. `obj` makes a closed object (`additionalProperties: false`); `obj(properties, { open: true })` lets other properties through. Pi Durable checks the arguments against the schema before `execute` runs. Since Pi 1.5 (Pi Pocket 0.28.0), pi-schema does the check, and the model gets its messages, such as `- path: missing`. A drop-in written before can keep TypeBox's `Type` from `@earendil-works/pi-ai` ([API versions](reference/api-versions.md)).
32
32
  - `execute(args, api, context)` does the work.
33
33
 
34
+ ## Tools for every subagent
35
+
36
+ Set `subagents: "always"` on a tool that every subagent needs. When Pi starts a subagent with a `tools` list, Pi Pocket adds the marked tools that the session enables, from the extensions that run there, once each. It never adds an extension: a tool from one removed for subagents, or left out of a session's fixed extension list, does not come along. Without a tool list, nothing changes. The tool's prompt and spawn result do not mention the marker or the tools it adds.
37
+
38
+ A marked tool with `deferred: true` is offered at once when the subagent has a tool list: a subagent has no tool search. A tool that only scripts call keeps that rule, and brings codemode with it. Sending more work to an existing subagent does not change its tools.
39
+
40
+ Pi Durable's `defineTool` does not type this Pi Pocket option. Add it after `defineTool`, as with `annotations`:
41
+
42
+ ```typescript
43
+ import type { ToolOptions } from "./_pocket.d.ts";
44
+
45
+ const lookup = Object.assign(defineTool({ … }), {
46
+ subagents: "always",
47
+ } satisfies ToolOptions);
48
+ ```
49
+
50
+ Since 0.29.0, experimental: it can change in a minor release. This is an addition, so the API version stays 2. Older Pi Pocket ignores the field; it does not add the tool. A gallery entry that needs this behavior sets `minPocket` ([API versions](reference/api-versions.md)).
51
+
34
52
  ## Return a result
35
53
 
36
54
  - Return `{ output: [{ type: "text", text }] }`. The model reads the text.
package/docs/features.md CHANGED
@@ -19,7 +19,7 @@ The full tour. For setup, see the [README](../README.md).
19
19
  - **Forks.** Tap Pi's reply → More → **Fork from here**: a new session with everything up to that reply, which then goes its own way. Tap one of your messages to **edit it and send it again**, or send any message again, to the same model or another one (a retry). Each makes a new session that forks just before the message; the original stays as it is. A fork gets its own chat (with the pins of what it inherited), a link back to where it came from, and optionally a git worktree of its own.
20
20
  - **A new context.** Menu → **New context** (or `/reset [note]`): Pi starts fresh and no longer sees the messages so far, while everyone still does. An optional handoff note carries over what matters.
21
21
  - **Instructions for Pi.** Menu → **Instructions for Pi** (or `/instructions …`): ground rules Pi gets with every message in this session, such as "use pnpm, not npm". Everyone in the session can see them.
22
- - **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for everywhere: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), and everywhere's reach every session and PiP. Menu → **Memory** (its hint says how many apply here and everywhere) lists them in those two groups, each with who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, for this project or everywhere, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons and everywhere 30; past that, forget one first. Changes show as lines in the chat. Turn it off in Extensions.
22
+ - **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for everywhere: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), and everywhere's reach every session and PiP. Menu → **Memory** (its hint says how many apply here and everywhere) opens as a wide sheet; a switch at its top, **This project** or **Everywhere**, each with how many it holds and how many of them wait for approval, picks which of the two it lists and where a lesson you type in goes. Each shows who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons and everywhere 30; past that, forget one first. Changes show as lines in the chat. Turn it off in Extensions.
23
23
  - **A lean prompt.** A new session gets only the tools most conversations use. `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools wait, and so do their prompt sections; the prompt lists them with a line each, and Pi loads one with `tool_search` when a task needs it. On a model whose provider takes tool changes in the messages (Claude 4.8 and 5, and later), the tool joins the list and stays for the conversation; on any other, Pi calls it from a `codemode` script, so the tool list and the prompt cache never change. Long guides, such as the design guide and the page-to-app messages of artifacts, are files that Pi reads when it needs them. Turn the **Tool search** module off in Menu → Extensions to offer every tool every time. A test keeps Pi Pocket's own part of a plain session's prompt under 14,000 characters (about 5,000 tokens: schemas and this prose run at about 2.75 characters a token), so it does not grow by accident.
24
24
  - **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
25
25
  - **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages**: Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. A repeat whose last message still waits in the session's queue (Pi is at work, or a run failed and holds it) sends no other at its next time: the time is skipped, a line in the chat counts the skips, and the Schedules sheet, the Running now board, and Pi's `schedule` tool list show how many there were (since 0.28.1). Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
@@ -53,7 +53,7 @@ The full tour. For setup, see the [README](../README.md).
53
53
  - **Continue a Pi session.** A session of Pi in the terminal can carry on here. The owner picks it from **Continue a Pi session** in the New session sheet (or the launcher): Pi's sessions on this computer by folder, newest first, with a search through their titles, folders, and words, and for one its folder, model, and last messages. **Continue in Pocket** makes a new session in its folder, with its model when that one is signed in here, and its whole conversation to read. Pi gets the context Pi itself builds from the file: what a compaction summarized, and Pi's context edits, stay as Pi had them. Pi's system prompt and extensions' state stay behind, and nothing Pi did runs again: a tool call that never finished gets a result saying so. The session's file is only read. The list marks sessions already continued here, and says when Pi went on in the terminal since.
54
54
  - **Diagrams and math.** Mermaid fences render as diagrams. Inline `$…$`, display `$$…$$`, and `math`, `latex`, or `tex` fences render as LaTeX. A closing `$` must have no space before it and no letter or digit after it, so prices and text such as `PATH=$HOME/bin:$PATH` stay plain. The owner can turn Diagrams off in Menu → **Extensions**; the original text remains in the conversation.
55
55
  - **Export.** Menu → **Export as Markdown** (or `/export`): the whole history as a Markdown file, with tool calls folded into `<details>` blocks.
56
- - **Any provider or model.** Uses Pi's own model runtime and sign-ins (`~/.pi/agent/auth.json`): pick a model and thinking level per session from the menu that opens up from the model chip in the message box (arrows and Enter pick, with a search box when there are many models), and sign in to providers (API key or subscription) from an inline card in the Providers sheet; expired sign-ins come first with a warning pill. API keys cannot be empty or only spaces. A failed sign-in shows a short message, technical details folded away, and **Start again**. A provider search with no matches offers **Clear search**. Pi’s `enabledModels` setting supplies the **Scoped** list, using Pi’s own pattern matching (including wildcards and thinking-level suffixes). When any scoped models are available, **[scoped | all]** beside the **Model** heading switches between that list and every model with a configured sign-in; the active choice uses the primary color. Tab in the search box (or in the picker, when it has no search box) switches it too, also when the search has no matches; from the picker's other controls, Tab moves the focus. On a touch screen, each choice takes a tap about 40px across. Each opening starts scoped; without a scope, when no pattern matches, or when `/model …` searches for models only outside the scope, it shows all instead. Switching the list keeps the search and changes no model or setting. The default-model picker has the same switch. New sessions start with the owner's default model and thinking level: **Make default** under the thinking levels makes the session's the default, and Menu → **Default model** (or the launcher) picks one without changing a session; without one, a new session starts with a trusted project's model/thinking default, then the last model anyone picked, then Pi's global default. To use project defaults, Menu → **Default model** → **Clear owner default: use project defaults, then last picked**. A project pin needs both `defaultProvider` and `defaultModel` in the final session folder's `.pi/settings.json`; `defaultThinkingLevel` is optional (`off` when omitted) and limited to that model's levels. Thinking-only project settings do not change another source's pair. Untrusted settings use normal fallback; a settings-only project appears in the owner's trust flow. Trust affects only later new sessions, never the open one, and no project setting can grant itself trust. Invalid consulted trusted settings stop creation with a contained error, without a model swap. Known unsigned project models stay selected. Imports, forks, subagents, manual choices, and PiP's own conversation keep their previous behavior. Extra per-project skill/prompt paths and per-project run policy are not supported yet ([project defaults](customizing.md#project-model-defaults-for-new-sessions)) A model is always one a person chose: a default that is not signed in now stays the default (the chip shows it, and the first message says why it fails) rather than give way to another model, and with no model chosen anywhere a new session starts with none until someone picks one. A subscription sign-in that its provider will no longer renew (OpenAI's refusing a refresh with `invalid_grant`, say) is found when the owner opens the Providers sheet, when a subagent on another model or PiP is about to use one of its models, or when a run fails on it: the sheet marks the provider **needs sign-in** with what the provider said, the model menu marks its models, the owner (alone) gets a notice, and subagents on other models and PiP use none of its models until someone signs in again. A session on one of its models, and a subagent on that session's model, are not checked first: they try it, and their runs fail where you see them. **Subagent models** gets a full-height pane on the right of the owner's Providers sheet on wide screens, and comes first on phones. It lists every signed-in model by provider, with a box to find one when there are many: each one checked is a model Pi may start subagents and linked sessions on; with none checked (the default) they run on their session's model, and with some checked they run only on those, never on the session's own model unless it is checked (see Background subagents; `subagentModels` in `~/.pi-pocket/config.json`). A tap changes that one model alone, so quick taps, and two tabs at once, keep every choice. An allowed model that is not signed in now stays listed, marked, so it can be taken off. Star a model in Providers to save it as a favorite, independently of its subagent checkbox. **All models / Favorites** filters this list and the session/default-model picker; favorite models come after the current model and before other models in the picker, within the active scope. Favorites belong to the signed-in person in this browser and survive reloads; they do not sync between devices.
56
+ - **Any provider or model.** Uses Pi's own model runtime and sign-ins (`~/.pi/agent/auth.json`): pick a model and thinking level per session from the menu that opens up from the model chip in the message box (arrows and Enter pick, with a search box when there are many models), and sign in to providers (API key or subscription) from an inline card in the Providers sheet; expired sign-ins come first with a warning pill. API keys cannot be empty or only spaces. A failed sign-in shows a short message, technical details folded away, and **Start again**. A provider search with no matches offers **Clear search**. Pi’s `enabledModels` setting supplies the **Scoped** list, using Pi’s own pattern matching (including wildcards and thinking-level suffixes). When any scoped models are available, **[scoped | all]** beside the **Model** heading switches between that list and every model with a configured sign-in; the active choice uses the primary color. Tab in the search box (or in the picker, when it has no search box) switches it too, also when the search has no matches; from the picker's other controls, Tab moves the focus. On a touch screen, each choice takes a tap about 40px across. Each opening starts scoped; without a scope, when no pattern matches, or when `/model …` searches for models only outside the scope, it shows all instead. Switching the list keeps the search and changes no model or setting. The default-model picker has the same switch. New sessions start with the owner's default model and thinking level: **Make default** under the thinking levels makes the session's the default, and Menu → **Default model** (or the launcher) picks one without changing a session; without one, a new session starts with a trusted project's model/thinking default, then the last model anyone picked, then Pi's global default. Since 0.29.0 a thinking level belongs to its model: a model picked with no level, or a new session on the last model picked, takes the level Pi's TUI keeps for it in Pi's `modelThinkingLevels`, limited to that model's levels. Pocket reads that map and never writes it. Subagents, linked sessions, and PiP's own conversation do not read it. To use project defaults, Menu → **Default model** → **Clear owner default: use project defaults, then last picked**. A project pin needs both `defaultProvider` and `defaultModel` in the final session folder's `.pi/settings.json`; `defaultThinkingLevel` is optional (`off` when omitted) and limited to that model's levels. Thinking-only project settings do not change another source's pair. Untrusted settings use normal fallback; a settings-only project appears in the owner's trust flow. Trust affects only later new sessions, never the open one, and no project setting can grant itself trust. Invalid consulted trusted settings stop creation with a contained error, without a model swap. Known unsigned project models stay selected. Imports, forks, subagents, manual choices, and PiP's own conversation keep their previous behavior. Extra per-project skill/prompt paths and per-project run policy are not supported yet ([project defaults](customizing.md#project-model-defaults-for-new-sessions)) A model is always one a person chose: a default that is not signed in now stays the default (the chip shows it, and the first message says why it fails) rather than give way to another model, and with no model chosen anywhere a new session starts with none until someone picks one. A subscription sign-in that its provider will no longer renew (OpenAI's refusing a refresh with `invalid_grant`, say) is found when the owner opens the Providers sheet, when a subagent on another model or PiP is about to use one of its models, or when a run fails on it: the sheet marks the provider **needs sign-in** with what the provider said, the model menu marks its models, the owner (alone) gets a notice, and subagents on other models and PiP use none of its models until someone signs in again. A session on one of its models, and a subagent on that session's model, are not checked first: they try it, and their runs fail where you see them. **Subagent models** gets a full-height pane on the right of the owner's Providers sheet on wide screens, and comes first on phones. It lists every signed-in model by provider, with a box to find one when there are many: each one checked is a model Pi may start subagents and linked sessions on; with none checked (the default) they run on their session's model, and with some checked they run only on those, never on the session's own model unless it is checked (see Background subagents; `subagentModels` in `~/.pi-pocket/config.json`). A tap changes that one model alone, so quick taps, and two tabs at once, keep every choice. An allowed model that is not signed in now stays listed, marked, so it can be taken off. Star a model in Providers to save it as a favorite, independently of its subagent checkbox. **All models / Favorites** filters this list and the session/default-model picker; favorite models come after the current model and before other models in the picker, within the active scope. Favorites belong to the signed-in person in this browser and survive reloads; they do not sync between devices.
57
57
  - **Multiplayer.** Any number of browsers can watch and steer the same session live. The status line under the message box shows how many are here, how full the context is (after a compaction, an estimate marked ~ until the next answer measures it), the cache hit rate, the cost, and a pill that says whether Lancet Guard is on (it opens Extensions). **Reply speed** in Appearance (or the launcher) adds how fast the last answer came: its tokens per second and how long its first token took (a response delivered in one buffered flush has no speed, only that wait). It is off until you turn it on, in each browser. On a touch screen, a tap on the line says in a notice what its items mean. On a narrow screen the line keeps to one row where it can. Where it does not fit, it gives up these in turn, only as far as it must: the speed's long words ("42 tok/s · 1.2s"), "1 here" while you are alone, the word "guard" (the shield stays), the word "context" (the meter stays), the cache, and the wait for the first token. "Sign in another device" makes a one-time invite link, a QR code, and a short code to type on the other device's sign-in screen. The owner can tick **Sign in as me (owner)** to sign their own other device in as the owner, with the owner's notifications, instead of as someone new. Messages show who sent them.
58
58
  - **Profile pictures.** Menu → **Your name** (or the round button at the bottom of the side rail) has **Add photo** and **Remove photo**. The picture is cropped to a square and shrunk in the browser, kept in the data folder, and replaces your initials in the people lists, the rail, and on your messages for everyone who can see you.
59
59
  - **Working together.** The top bar shows who else is in the session (an avatar with a mark that greys when their tab is in the background, and how many more), and "Alex is writing to Pi…" warns before two people steer at once. The **People** panel opens beside the conversation on wide screens, where it takes the Browser panel's place, and as a sheet on phones. Its header counts the people here; the roster shows their online or away state, typing, and role. A **Take turns** card starts or turns off shared driving with the same permissions as the menu. It has:
@@ -89,7 +89,7 @@ The full tour. For setup, see the [README](../README.md).
89
89
  - **Ask someone.** Off until the owner turns it on in Menu → **Extensions**. When Pi needs an answer that only someone outside the chat can give (a manager, a client, an expert), **Ask someone** under one of Pi's answers puts a request in the message box, and Pi writes the question with its `ask_someone` tool so that it stands alone: the background, the question, the options, and its recommendation. Nothing goes anywhere yet: the draft waits in **Questions for others** (the status line under the message box, the session menu, or the launcher), where you edit it, **Copy text**, or **Create link** for a day, a week, or a month. The link opens a page with no sign-in, the question, and a box for one answer and an optional name; then it closes. **Copy link**, **Copy message**, and **Share…** (on a phone) send it on; **End link** takes the page down. When the answer comes, a notice says so, and **Give to Pi** puts it in the message box, quoted and marked as someone else's view, for you to send. People who steer every session use it; viewers and people invited to one session do not. Since 0.22.0.
90
90
  - **Waiting out provider limits.** When a provider's limit stops a run (a 429 or an overload, a Claude or ChatGPT usage window, a model's cap), Pi Pocket waits for it to clear and goes on by itself, instead of failing. It waits until the reset time the provider gave (or, with none, tries again at growing intervals), then sends one request to find out; if that gets an answer, the sessions waiting on the same limit go on, one at a time. The live line says what Pi waits for, when it tries next, and when the limit resets, with **Retry now**; **Stop** or **Interrupt** end the wait at once, and a message you send meanwhile waits in the queue as always. The session's square is a hollow square with a dot, also on peek tiles, and a subagent's row says it waits. One push goes out when a wait of ten minutes or more begins (Menu → **Notifications** → **Waiting for a limit**). It survives a restart. The owner sets the longest wait (**Wait for a limit** in the Providers sheet: Off, 1, 6, 12, or 24 hours; default 6): what waits is any reset time within that longest wait, load with no time given (an ordinary 429 or an overload), which is tried again at growing intervals for up to 30 minutes, and, since 0.24.0, a plan's usage limit with no time given (OpenAI subscription sharing, Z.ai, MiniMax, OpenCode Go), which is tried again about every 15 minutes, up to the longest wait, counted from the first failure across restarts. What fails the run at once, with the reset in the message where there is one: a window of days (Claude's 7-day window, a Codex window of over 300 minutes), a reset after the longest wait, a usage limit that names a window of days (daily, weekly, monthly), with or without a reset time, and a sign-in that expired or billing. Retry now sends one try each 30 seconds. It never picks another model. Since 0.21.0.
91
91
  - **Prompt cache keeper.** On by default; `PI_POCKET_CACHE_KEEPER=off` turns it off. While a run waits on a tool call, Pi Pocket replays the last request that ended in a tool call, with `maxTokens` 1, at 90% of the cache's lifetime or 10 seconds early, whichever is sooner. It does so only when the expected savings are more than the cost. It keeps the 5-minute cache only: no idle warming, no 1h cache, no request with `cacheRetention` none, and no Anthropic thinking set by a token budget. It stops on a real cached request, when the run ends (PiP's too), on an error, at shutdown, or after 30 minutes. A warm request does not wait for a provider limit. Its usage counts in `pi.usage` and in the spend of the person and session that were paying when it started, and spend limits are checked before each warm. A restart drops the warm timers and does not replay warm requests.
92
- - **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.28.0 the tool waits for tool search, as `browser` does, so a session that starts none does not pay for its prompt. On a model without tool changes in the messages (all but Claude 4.8 and 5, and later), Pi then starts subagents from a codemode script: the conversation shows each start as a line of that script, without the subagent's card, and the subagents board still opens each one. Pi writes its tasks for subagents in the language of the person it works for, in ASD-STE100 (Simplified Technical English) when it is English (since 0.19.0; in other languages since 0.28.0), and asks for their reports in that language too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. Pi picks no model on its own: until the owner allows models for subagents (**Subagent models** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0).
92
+ - **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.28.0 the tool waits for tool search, as `browser` does, so a session that starts none does not pay for its prompt. On a model without tool changes in the messages (all but Claude 4.8 and 5, and later), Pi then starts subagents from a codemode script: the conversation shows each start as a line of that script, without the subagent's card, and the subagents board still opens each one. Pi writes its tasks for subagents in the language of the person it works for, in ASD-STE100 (Simplified Technical English) when it is English (since 0.19.0; in other languages since 0.28.0), and asks for their reports in that language too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. A tool marked `subagents: "always"` by an extension comes along even when that list leaves it out, only while the extension runs there ([Tools](extensions/tools.md#tools-for-every-subagent)). Pi picks no model on its own: until the owner allows models for subagents (**Subagent models** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0).
93
93
  - **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. Appearance → **PiP → Board** (Floating is the default, per browser) opens PiP's own conversation in the session's place instead, as a session: its top bar with the model, its menu, every step, and a × at the end of the bar, with PiP's own message box at the session's width (the panel's box, without a session box's slash commands, @ mentions, ↑ history, or Steer and Interrupt). The sidebar stays, the rail's orb shows it open, and every way in opens it there; back, its ×, or the orb again gives the place back to what was there (home after a notification's link), and Running now, the subagents board, an extension's page, or another session simply take its place. Changing the setting while PiP shows moves it to the new place. PiP has one message box, so a move changes nothing in it: the same words, files, passage to ask about (Ask PiP), and message on its way show in both places. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. It writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in its person's language: ASD-STE100 (Simplified Technical English), at about 80% adherence, when it is English (since 0.19.0), the same short, plain style in another (since 0.28.0), so a session it worked in reads in your language; it asks each session to answer it in the same language and style, and a session answers a message that came through PiP (scheduled ones too) in the language of that message. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Board** (above) shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back. PiP follows its owner's standing instructions in `pip.md` in the data folder (since 0.28.0, [customizing.md](customizing.md#pips-instructions)).
94
94
  - **Resize.** At widths of 768px and above, drag PiP's left edge, top edge, or top-left corner to resize it, with the bottom-right corner fixed. The same zones are finger-sized on touch screens. Its size is remembered for each account in this browser and fits back inside the viewport when it shrinks. Phones use a bottom sheet with rounded top corners and a grabber; the model, context meter, and all three header actions stay available.
95
95
  - **Choose PiP's model.** Tap the model chip in PiP's header to use the existing model and thinking picker for PiP alone, from Home or over a session. The chip and picker choices are disabled while PiP works. Saving also checks that PiP is idle. This header path does not change the last picked model for new sessions; as a board, the top bar's model keeps a session's behavior. With no model, the welcome offers **Choose a model to use these suggestions**, which opens the same picker. Suggestions that send at once wait for a model; those that put text in the box stay usable, and choosing a model keeps the suggestions visible.
@@ -105,7 +105,7 @@ The full tour. For setup, see the [README](../README.md).
105
105
  - a short name of three characters or more, without its family's name: "an OpenAPI v3.1 spec" names a signed-in "Acme V3.1".
106
106
  - everyday words that are a model's name without its first word: "deep research" names "X9 Deep Research", and "the 2.5 flash drive" names "Nova 2.5 Flash".
107
107
  - a longer name Pi has no model for: it names the model it starts with. "zeta-5-ultra" names zeta-5, while "zeta-5-nano", a model Pi knows, does not.
108
- - **Returning from a subagent.** A subagent's conversation has **Back to main session** above the message box, for viewers too, so the way back stays in sight however long the conversation is. The top bar says which session it is a subagent of, and carries a small tag with the model it uses, which a tap opens in the model sheet. The composer hides its model chip on a phone while the subagent works, so the tag keeps the model in sight; when room is short, the parent's title is cut first.
108
+ - **Returning from a subagent.** A subagent's conversation has **Back to main session** above the message box, for viewers too, so the way back stays in sight however long the conversation is. It goes up, not forward (since 0.29.0): opened from the main session, it goes back there as back does; reached another way, the main session takes its place. So back from the main session never opens the subagent again. The top bar says which session it is a subagent of, and carries a small tag with the model it uses, which a tap opens in the model sheet. The composer hides its model chip on a phone while the subagent works, so the tag keeps the model in sight; when room is short, the parent's title is cut first.
109
109
  - **Subagents bar.** Above the message box while a subagent works or has a report on its way: a dot per subagent, how many work and how many are done, and what the newest one does now. Tap it (or the count in the top bar while one works) for a row each: what it was asked, what it does this moment (the call it runs, or what it writes), for how long, the model and thinking level it runs on (with ↗ when that is not the session's model), whether its report is on its way, **Stop**, and a tap to open it; a call waiting for approval says so, and a failed one says why, and "dismissed" once someone dealt with it (see Subagents board). Done, stopped, and failed ones are counted apart, failed ones first. Once none works it stays until you put it away (×), and comes back, counting only the new ones, when one starts again. Viewers see it too, without Stop.
110
110
  - **Subagents board.** The rail's ⑂ shows every subagent in every session in the conversation's place: a soft state-colored square each, in a rounded row per session, those that need you first, and under each row a sub-tile for every subagent at work there, with its state and the model it runs on, so a glance says what each is doing without opening one (a tap picks it for the detail card, staying on the board; a double click, or double tap, opens it). A row shows six sub-tiles (three on a phone), and the selected one wherever it is; **Show N more** shows the rest. Working squares pulse; the selected square has a ring, and filtered-out squares fade. A proportional state bar and filter pills with counts say how many wait for an approval, failed, work, were stopped, or are done, and let you filter by one; a search finds a subagent by its name, what it was asked, what it does now, or why it failed. **Needs you** lists those waiting for an approval and those that failed with nobody dealing with it yet. The selected subagent's detail card shows its session, how long it has worked (or when it ended), what it was asked and does now, and its error, with **Open** (**Review the approval** while it waits), **Stop**, and, for a failure, **Dismiss** (off while it is asked; when the subagent failed again since, a notice says so and the newer failure stays). A failure is dealt with once someone who can steer dismisses it, or opens the subagent from the board, its row in the subagents bar, its report or the tool call that started it, or the session menu: it stays on the board as failed ("Failed · dismissed", without the "!"), and leaves Needs you, the rail's red mark, and the session's red ⑂, for everyone, after a reload or a restart too. A message someone sends it, like later work from Pi, settles it by what it comes to, after a restart too: answered, the subagent is done; failing again, it needs someone again. The session's activity says who dealt with a failure, whichever way. Hover a square to see what it does in the line under them; the arrows move the focus between squares and Enter opens the one focused; Esc, back, or × closes it, and on a phone a swipe right does too. Archived sessions show only while a subagent works there. A session keeps its 24 newest finished squares (done, stopped, or failed and dealt with); older ones are counted, as **+N** after its squares and in the bar's numbers. On a phone it is one column, Needs you first, with bigger squares and a bar at the bottom for the one selected.
111
111
  - **The queue and the bars above the message box.** Messages waiting for Pi show above the message box, with how many wait whenever not all of them show. With the bars there (the subagents bar, plan mode, a goal, a PR watch, a trust question, who drives), they take less than half of the room they share with the conversation when the bars fit in it, and the conversation keeps the rest, staying where you were reading. The bars always show whole; the queue and the subagents' list take what the bars leave, and scroll. Unfolding the subagents bar gives the list the room, one whole row at least: the queue shows fewer rows, or folds to how many wait. With several bars on a short screen, the plan, goal, watch, and trust bars keep one line each, their words cut short and their buttons whole. When even that does not fit (a phone on its side with every bar up), the stack scrolls, and the conversation keeps a quarter of the room, or a few lines, whichever is less.
@@ -124,7 +124,7 @@ The full tour. For setup, see the [README](../README.md).
124
124
  - **Extension settings.** A module can declare settings (on or off, text, a number, a choice, or a secret such as an API key); the owner changes them in Menu → Extensions under the module, with **Save settings**, and **Default** or **Clear** to put one back. A secret's value never leaves the server: the sheet shows only that it is set. Modules can also listen to what happens in the app (sessions made, renamed, and archived, messages, runs) and offer services to each other; Extensions says which ones offer a service. Since 0.22.0 ([docs/extensions/services-settings.md](extensions/services-settings.md)).
125
125
  - **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files it writes"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, and that the scan reads text so the code can reach more, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code, or gives one of them, or a `net`, `tls`, or `dgram` connection, an address it builds, also beside hosts it names), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none, or loads code the scan cannot read: `eval`, `new Function`, `getBuiltinModule`, `process.binding` or `dlopen`, `import()` or `require()` of a name it builds, or a `.node` file), and the files it writes (`files it writes`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
126
126
  - **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
127
- - **OpenAI-compatible endpoints.** The owner adds an endpoint from the **OpenAI Compatible** row of the Providers list (**Add**; searching "ollama", "local", or "custom" finds it): a name, a base URL (`http://localhost:1234/v1`), and an API key, or **No key** for a local server. **Find models** asks the endpoint's `GET /models` and lists what it has, each with a checkbox; a model ID can also be typed by hand, and either way it is added. **Save** writes the endpoint into Pi's `~/.pi/agent/models.json` (made, with `~/.pi/agent/`, when missing) and keeps the key in Pi's sign-ins (`auth.json`), so its models show in the model menu at once, with no restart. Each endpoint is a row of the list like any provider, with **Edit** (an empty key keeps the saved one; models can be found again with the saved key, at the same address only) and **Remove** (which removes its key too). Pi Pocket rewrites `models.json` only when it is plain JSON that Pi accepts, and keeps the fields that it does not set; a file with comments or trailing commas is left alone, with a message.
127
+ - **OpenAI-compatible endpoints.** The owner adds an endpoint from the **OpenAI Compatible** row of the Providers list (**Add**; searching "ollama", "local", or "custom" finds it): a name, a base URL (`http://localhost:1234/v1`), and an API key, or **No key** for a local server. **Find models** asks the endpoint's `GET /models` and lists what it has, each with a checkbox; a model ID can also be typed by hand, and either way it is added. Each chosen model has an **Images** checkbox (it sees images: Pi sends them instead of a placeholder) and a **Thinking** button that opens its thinking levels: on, it starts with Low, Medium, High, Extra high, and Max, each sending its own name as the reasoning effort; levels can be added (**Add level** adds the next one above the highest, below the last row; Off and Minimal too), removed, or sent under another name (a model whose top effort is `hard`). The rows stay in Pi's order, from Off to Max, as the model menu lists them; a row's menu changes which level it is. A **Context & price** button opens its context window and maximum output, in tokens (empty: Pi's defaults, 128k and 16k), and its price in dollars per million tokens: input, output, cache read, and cache write (empty: the model costs nothing; a cache price left empty is 0). The context meter and compaction go by the context window; each request asks for up to the maximum output, so it must be at or below what the endpoint allows; each message's cost, and spend limits, go by the price. All of these are set by hand and saved in `models.json`, and **Edit** shows them as saved; Pi Pocket does not guess them from the endpoint's list, which has no common format for them. The one exception is a vLLM server's `max_model_len`, which fills in the context window of a model chosen from its list. **Save** writes the endpoint into Pi's `~/.pi/agent/models.json` (made, with `~/.pi/agent/`, when missing) and keeps the key in Pi's sign-ins (`auth.json`), so its models show in the model menu at once, with no restart. Each endpoint is a row of the list like any provider, with **Edit** (an empty key keeps the saved one; models can be found again with the saved key, at the same address only) and **Remove** (which removes its key too). Pi Pocket rewrites `models.json` only when it is plain JSON that Pi accepts, and keeps the fields that it does not set; a file with comments or trailing commas is left alone, with a message.
128
128
  - **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (the refresh button beside the Subagent models heading), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
129
129
  - **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them. That includes HEIC and HEIF photos (from an iPhone, say), which the server converts to JPEG for the model in a worker, one photo at a time, with limits of 30 seconds and 64 million pixels (a photo that big needs about 1 GB of memory while it converts), so a broken or huge photo gets a notice and does not hold up the server; the original stays in the session's uploads. When the image the model gets differs from the file, its line in the message says so: the format when it changes (`[Image: shown to you as JPEG.]`, always for a HEIC photo), and, in the words of Pi's `read` tool, the original size, the shown size, and the multiplier when it is made smaller. An image that does not change gets no note. A sent HEIC photo shows in the chat and in PiP as the JPEG the model got; when the model did not get one (a model without images, or a failed conversion), or when Pi Pocket cannot be sure which image is the photo's (the message names an image with `@`, or another attached image failed), it shows as a file. An image starts to be made ready for the model as soon as it uploads, so a send seldom waits for it. In a session's message box (not PiP's), attached files stay across a reload, as the draft does, and leave with your sign-out; while a message is on its way, the box dims and holds what it sends, its words, files, and quote, which no key, dictation, or × changes until it went (in PiP's box too, which empties as it sends), also when it shows again meanwhile (you went to another place and came back), so it cannot go twice; text sent to the box meanwhile (Send to Pi) goes in once it went or failed, and so does a queued message taken back with Edit, kept meanwhile in the browser, also through a reload or a move; the same words and files sent again after a lost answer, also after a reload, find the message that went instead of making a second; once you change them, or after an answer that said it was refused or failed, they go again; if the send fails, it is all there to send again, with its quote.
130
130
  - **Code in your messages.** In a message you send, `` `code` `` and a fence of ` ``` ` lines show as code, the way Pi's replies show it, colored when the fence names a language (` ```js `). A span closes with as many backticks as opened it, a fence's lines stand on their own, and a stray or unclosed one stays text. Nothing else is formatted: `*`, `#`, lists, and spacing stay as typed, and @mentions outside code stay buttons. Only the display changes: Pi, exports, and ↑ get the message as written.
package/docs/map.md CHANGED
@@ -144,6 +144,7 @@ A module split into parts keeps its name for the part others import, with the re
144
144
  | `browser.ts` | `Browsers`: one headless Chromium for every conversation, started with the first page and stopped after the last; each conversation's page |
145
145
  | `browser/page.ts` | `BrowserPage`: one conversation's page: its events, screencast frames, console, navigation, and what Pi and people do to it |
146
146
  | `browser/cdp.ts` | The DevTools protocol over a pipe (`--remote-debugging-pipe`), and the Chromium process; `BrowserError` |
147
+ | `browser/identity.ts` | The browser's client hints: its brand (Chromium, Google Chrome, Brave, Edge), full version, and this machine's platform |
147
148
  | `browser/discovery.ts` | Finding a Chromium-based browser on this machine, and where its profile goes |
148
149
  | `browser/page-scripts.ts` | The scripts that run inside a page: the outline with refs for Pi, finding a target, selecting |
149
150
  | `browser/keys.ts` | Key names and combinations as key events |
@@ -185,7 +186,7 @@ The agent's side of Design mode. `extensions/design.ts` installs it (see Extensi
185
186
  | File | Owns |
186
187
  | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
187
188
  | `providers.ts`, `net.ts` | Provider sign-ins, and those that need signing in again (a subscription its provider will not renew); HTTP settings for provider streams |
188
- | `custom-providers.ts` | OpenAI-compatible endpoints the owner adds in Providers: their entries in Pi's `models.json` (made with its folder when missing; a file with comments, or one Pi refuses, is left alone), their keys as stored API-key sign-ins, and discovery of an endpoint's models (`GET <baseUrl>/models`); `web/sheets/custom-providers.js` is the form |
189
+ | `custom-providers.ts` | OpenAI-compatible endpoints the owner adds in Providers: their entries in Pi's `models.json` (made with its folder when missing; a file with comments, or one Pi refuses, is left alone), their keys as stored API-key sign-ins, and discovery of an endpoint's models (`GET <baseUrl>/models`), and each model's image input, thinking levels, context window, maximum output, and price; `web/sheets/custom-providers.js` is the form |
189
190
  | `guides/*.md` | Pages that the prompt points Pi to, to read only when a task needs them (`artifact-bridge.md`, `design.md`), so that the prompt stays short |
190
191
  | `public-fetch.ts` | `host.fetchPublic`: fetch that reaches only public addresses, checked where each connection is made and at each redirect |
191
192
  | `gallery.ts` | The extension gallery (`app.gallery`, `host.gallery`): its index read and kept in the data folder's `gallery/`, downloads checked against their pinned SHA-256, installs (off), updates with a diff, removal, the `<name>.gallery.json` provenance beside each, revoked versions, and Share's draft entries |
@@ -212,9 +213,9 @@ Plain ES modules, loaded as they are. `math.js` finds Markdown math delimiters;
212
213
 
213
214
  | File | Owns |
214
215
  | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
215
- | `store.js` | State, the event stream (SSE, or long polling when a tunnel holds it back), `api()`, `actions`, `workspaceOrder` (the numbers, by `session-tree.js`), `openId` (the session marked open: the one under a route opened `over` it, as PiP's board is) |
216
+ | `store.js` | State, the event stream (SSE, or long polling when a tunnel holds it back), `api()`, `actions`, `workspaceOrder` (the numbers, by `session-tree.js`), `openId` (the session marked open: the one under a route opened `over` it, as PiP's board is), `navigateUp` (a subagent's way to its parent: back, or in its place) |
216
217
  | `live.js` | The message Pi is writing, put together from view updates that carry what changed (`liveMessage`); it imports nothing, so the server's tests run it |
217
- | `back.js` | The back stack: routes and the layers over them (sheets, the drawer, panels that cover the screen, a file over the tree) as history entries, so back closes what opened last; `useBack`, `pushRoute` (with state kept on the entry, read with `routeState`), `popRoute` (back to the route a route was opened over, keeping the layers still open), `goHome`, the list put under a conversation opened straight away, taps let go that land on what just slid in |
218
+ | `back.js` | The back stack: routes and the layers over them (sheets, the drawer, panels that cover the screen, a file over the tree) as history entries, so back closes what opened last; `useBack`, `pushRoute` (with state kept on the entry, read with `routeState`, and the route it was opened over, `routeUnder`), `popRoute` (back to the route a route was opened over, keeping the layers still open), `goHome`, the list put under a conversation opened straight away, taps let go that land on what just slid in |
218
219
  | `gestures.js` | Touch gestures, each following its own finger by its identifier, passive where they can be: sheets dragged down and the drawer dragged left to close (`useDragToClose`); on phones, swipes on the conversation (right back, left Files), in Files (right back), and up from the message box (the places); a swipe in from the left edge goes back in an iPhone's home screen app |
219
220
  | `app.js` | Layout (tiled windows, and the subagents board in the conversation's place), top bar (with what changed, from `diff.js`), notices, keyboard shortcuts, routing |
220
221
  | `transcript.js` | The conversation as turns: messages, Pi's replies with message times arranged in the reply slot, its thinking and tool calls folded into groups that open into a timeline, extensions' command cards, approvals, the live line (and Pi's thinking above it), breadcrumbs (and `linked-sessions.js`, the links between linked sessions); a message from a linked session shows as its own card (`LinkedMessage`), without its routing words, named after its session from the view's `linkedPeers`. Unsent picks and typed answers on a Pi asks card (never a secret field's) are kept per person through `person-storage.js`, by session and by ask (its id and its call, or when it asked), until Send, Decline, the card leaving, or sign-out; one that ended unseen goes when a card in that session next shows with the server's view of it. |
@@ -267,6 +268,7 @@ Plain ES modules, loaded as they are. `math.js` finds Markdown math delimiters;
267
268
  | `panel-layout.js` | Which panel each session shows beside its conversation (an extension's, Browser, Files and its tab, People), kept for the tab and the device, so a session shows again what it showed when it was left; `store.js` keeps and reads it |
268
269
  | `browser.js` | Whether the Browser panel is open, and opening an address in it |
269
270
  | `browser-panel.js` | The Browser panel: frames by long polling, taps, drags, wheel, and keys as input events, the live address bar, sizes, the console, the start screen's local-server list |
271
+ | `browser-paste.js` | Which paste is the Browser panel's page's: only while the screen has the focus, and with text (Firefox does not give the screen the paste). No imports, so Node tests it |
270
272
  | `files-panel.js` | The Files tile: whether it is open and on which tab, the folder's tree (folders read as they open), Go to file, the open file beside the tree, and the Changes tab |
271
273
  | `diff.js` | The diff viewer: one file's diff (unified or split, line numbers, colors, changed words, hidden lines on request), `DiffBlock` for tool calls and replies, and `DiffReview`, every change file by file with viewed marks |
272
274
  | `diff-parse.js` | Diffs as data, without the DOM: unified diffs and Pi's edit format as files, hunks, and lines; rows that pair changed lines by likeness; the words that changed |
@@ -276,7 +278,7 @@ Plain ES modules, loaded as they are. `math.js` finds Markdown math delimiters;
276
278
 
277
279
  `web/model-favorites.js` keeps per-person model favorites in this browser's local storage. The Providers sheet supplies star controls; it and the session/default-model picker share the Favorites filter. Stars do not change subagent permissions.
278
280
 
279
- Manual refresh lives in `src/server/model-refresh.ts`, owned by `Providers.modelRefresh`; `web/model-refresh.js` shares the refresh and its feedback between the menu, Providers, and the launcher. `test/model-refresh.test.ts` checks local configuration, external sign-ins, provider isolation, cancellation, session use, and endpoint access. `test/custom-providers.test.ts` checks OpenAI-compatible endpoints: the new file and folder, the key in `auth.json`, edits that keep hand-made fields, and files left alone.
281
+ Manual refresh lives in `src/server/model-refresh.ts`, owned by `Providers.modelRefresh`; `web/model-refresh.js` shares the refresh and its feedback between the menu, Providers, and the launcher. `test/model-refresh.test.ts` checks local configuration, external sign-ins, provider isolation, cancellation, session use, and endpoint access. `test/custom-providers.test.ts` checks OpenAI-compatible endpoints: the new file and folder, the key in `auth.json`, edits that keep hand-made fields, files left alone, and models' images, thinking levels, context windows, and prices.
280
282
 
281
283
  The Extensions hub in `sheets/gallery.js` shares one listing between Discover, Installed, Updates, and the selected entry. `sheets.js` maps its sheet routes to one retained hub; `sheets/extensions.js` supplies the built-in and local drop-in management controls for Installed, and the standalone sheet when the gallery is unavailable.
282
284
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.28.2-beta.1",
3
+ "version": "0.29.0-beta.1",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-pocket",
9
- "version": "0.28.2-beta.1",
9
+ "version": "0.29.0-beta.1",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "@earendil-works/chord": "1.5.2",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.28.2-beta.1",
3
+ "version": "0.29.0-beta.1",
4
4
  "description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
5
5
  "keywords": [
6
6
  "pi",
package/src/server/app.ts CHANGED
@@ -54,7 +54,7 @@ import { Commands } from "./commands.ts";
54
54
  import { ExtensionSessions } from "./extension-sessions.ts";
55
55
  import { LinkedSessions } from "./linked-sessions.ts";
56
56
  import { removeAvatar, saveAvatar } from "./avatars.ts";
57
- import { APP_ROOT, ConfigStore, modulesWith, type User } from "./config.ts";
57
+ import { APP_ROOT, ConfigStore, helloUser, modulesWith, type User } from "./config.ts";
58
58
  import {
59
59
  ArtifactAssetDoc,
60
60
  ArtifactBodyDoc,
@@ -2593,12 +2593,7 @@ export class PocketApp {
2593
2593
 
2594
2594
  async hello(user: User) {
2595
2595
  return {
2596
- user: {
2597
- id: user.id,
2598
- name: user.name,
2599
- role: user.role,
2600
- ...(user.sessions === undefined ? {} : { sessions: user.sessions.map(Number) }),
2601
- },
2596
+ user: helloUser(user),
2602
2597
  users: this.people(user),
2603
2598
  models: await this.modelList(),
2604
2599
  guard: await this.guardStatus(),