pi-pocket 0.27.0-beta.2 → 0.27.0-beta.4

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.
@@ -142,7 +142,7 @@ These came in 0.20.0, and are experimental. Check that they are there (`typeof p
142
142
  - **`sessionChips({ id, chips(session) })`** puts chips under the titles of rows: `chips` gives `[{ label, title, run }]` for a session. A chip with `run` is a button. A row with chips is taller, and the space beside them opens the session.
143
143
  - **`sessionSearch({ id, words(session) })`** gives words that the session list's search and the launcher match, after the title and the folder. A row that only a word matches shows the word.
144
144
  - **`sessionFilter({ id, title, icon or iconPath, badge, match, … })`** adds a button in the search field, which does one thing, as a rail button does. The first 3 show. While `match` is a function, the button is lit, and the list shows only the sessions that every filter that is on keeps. `update({ match: null })` turns it off. Its `started(id)` runs when a person starts a session with New in the list's head while it is on.
145
- - **`sessionAction({ id, label, run(ids) or sheet, access })`** adds an action on sessions: in the sheet that a finger held on a row opens, and in the bar while sessions are selected. `run` gets the session ids; a sheet gets them as the prop `sessions`. Only people who can steer see it, unless `access` is `"view"`. The first action with an `icon` or an `iconPath` is also a button on rows, where a mouse hovers.
145
+ - **`sessionAction({ id, label, run(ids) or sheet, access })`** adds an action on sessions: in the sheet that a finger held on a row opens, in the menu that a right-click on a row opens, and in the bar while sessions are selected. `run` gets the session ids; a sheet gets them as the prop `sessions`. Only people who can steer see it, unless `access` is `"view"`. The first action with an `icon` or an `iconPath` is also a button on rows, where a mouse hovers.
146
146
 
147
147
  `chips`, `words`, and `match` get a [`SessionInfo`](reference/pocket.md#sessioninfo), `{ id, title, cwd, archived, updatedAt }`. They must answer at once, not with a promise: one that returns a promise stops its module in that browser, as a throw does, and a filter that failed hides no session. The list can reuse their results: unchanged rows can skip `chips`, and unchanged session data and list settings can skip `words` and `match`. Keep them fast, read the module's own state in them, and do not call `pocket` in them. When that state changes, give `update` a new function: the same function draws nothing again ([Redraws](#redraws)). One that throws stops its module in that browser.
148
148
 
@@ -128,6 +128,7 @@ await page.press("Enter");
128
128
  ```
129
129
 
130
130
  - `snapshot()` gives the page as Pi reads it, and its controls as data: each one's ref, role, name, kind, and value. A password field's value is `••••` when it holds one, never its value.
131
+ - `snapshot()` also gives `scroll: { y, viewport, height }` in CSS pixels (since 0.27.0, experimental): the top of the viewport, its height, and the page's height. There is more below when `y + viewport < height`, and more above when `y > 0`.
131
132
  - `fill` puts a person's value into a field, and returns only what the field is. It fills only a field named by a ref, a selector, or a label, never a point, and fills nothing when something covers the field or the focus does not reach it, so a value never lands in another field. `type` types as Pi types.
132
133
  - A value filled into a field that is not a password field shows in that field: in screenshots, in the Browser panel that the people in the session watch, and in the snapshot's `value`. Fill secrets only into password fields.
133
134
  - `inspect` says what a target is, and whether it is a password field. A `beforeTool` hook can use it to refuse Pi's own `type` into a password field ([Hooks](hooks.md)), as below.
@@ -42,6 +42,7 @@ These members are public:
42
42
  - `notice(level, message, id?)`
43
43
  - `resolveModel(spec)`, `subagentModels()`, `modelProblem(ref, fresh?)`, `modelInfo(spec)` (exact local metadata, since 0.16.0)
44
44
  - `requesterOf(conversationId)`
45
+ - `roleOf(personId)` (experimental, since 0.27.0)
45
46
  - `skillPaths()`, `skills(cwd)`
46
47
  - `heldBack(conversationId)`, `onLimitsChanged(listener)`
47
48
  - `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental))
@@ -161,6 +162,8 @@ Since 0.22.0, these are experimental too: `web.publicPage` and `web.links`; `hos
161
162
 
162
163
  Since 0.26.0, `pocket.pip` (`ask`) is experimental, with `PipApi` and `PipAskResult`.
163
164
 
165
+ Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` field of `host.browser`'s `snapshot()`.
166
+
164
167
  Since 0.20.0, the session list's extension points are experimental: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, and `sessionSearch`, `WebRequest.sessions`, and their types. So is `pocket.composerKey`, with `ComposerKeySpec` and `ComposerBox`, and so are `pocket.onConversation`, `messages`, and `reveal`, with `MessagesOptions`, `MessagePage`, and `MessageInfo`. So are `host.registerModelProvider`, and `host.fetchPublic` with `PublicFetchInit`.
165
168
 
166
169
  ### Deprecated
@@ -85,3 +85,5 @@ Each member in the reference has its own Since line. These parts came together:
85
85
  | People's values and the browser: `host.ask`, `hide`, `commandEnv`, `browser` (experimental) | 0.22.0 |
86
86
  | Events, services, and settings: `host.on`, `web.provide`, `use`, `onService`, `settings`, `setting`, `onSettings`, `pocket.settings`, `onSettings` (experimental) | 0.22.0 |
87
87
  | Give PiP a message: `pocket.pip.ask` (experimental) | 0.26.0 |
88
+ | A person's role: `host.roleOf` (experimental) | 0.27.0 |
89
+ | The page's scroll position: `scroll` in the `host.browser` snapshot (experimental) | 0.27.0 |
@@ -30,7 +30,7 @@ When people take turns in a session, the person who has the turn is the only per
30
30
 
31
31
  ### the person Pi works for
32
32
 
33
- The person whose message started Pi's current work in a session. Pi acts for this person, with this person's rights. Code: `host.requesterOf`.
33
+ The person whose message started Pi's current work in a session. Pi acts for this person, with this person's rights. Code: `host.requesterOf`. To know this person's role, use `host.roleOf` with the id (since 0.27.0, experimental).
34
34
 
35
35
  ## Sessions
36
36
 
@@ -172,6 +172,16 @@ Since 0.3.0 · Stable
172
172
 
173
173
  The id of the person that Pi works for in a session now. This is the person whose message started Pi's current work.
174
174
 
175
+ ### `roleOf`
176
+
177
+ ```ts
178
+ roleOf(personId: string): Role | undefined;
179
+ ```
180
+
181
+ Since 0.27.0 · Experimental
182
+
183
+ The role of a person by id: `"owner"`, `"guest"`, or `"viewer"`. It is `undefined` for an id that is not a person here. It reads the role that core uses, so a module does not keep its own copy. Use it with `requesterOf` to know if Pi works for the owner. It can change in a minor release. Check that it is there first: `host.roleOf?.(id)`.
184
+
175
185
  ### `heldBack`
176
186
 
177
187
  ```ts
@@ -647,7 +657,12 @@ One control of a snapshot, as data, up to 500 of them.
647
657
  interface BrowserPageHandle {
648
658
  readonly url: string;
649
659
  readonly title: string;
650
- snapshot(): Promise<{ text: string; controls: BrowserControl[]; truncated: boolean }>;
660
+ snapshot(): Promise<{
661
+ text: string;
662
+ controls: BrowserControl[];
663
+ truncated: boolean;
664
+ scroll: { y: number; viewport: number; height: number };
665
+ }>;
651
666
  inspect(
652
667
  target: BrowserTarget,
653
668
  ): Promise<{ label: string; kind: string; editable: boolean; password: boolean }>;
@@ -499,7 +499,7 @@ sessionAction(spec: SessionActionSpec): Added<SessionActionSpec>;
499
499
 
500
500
  Since 0.20.0 · Experimental
501
501
 
502
- Adds an action on sessions. It shows in the sheet that a finger held on a row opens, and in the bar under the list while sessions are selected (Ctrl/⌘+click, or Select). Its `run` gets the ids of the sessions, or its sheet gets them as the prop `sessions`. See [`SessionActionSpec`](#sessionactionspec).
502
+ Adds an action on sessions. It shows in the sheet that a finger held on a row opens, in the menu that a right-click on a row opens, and in the bar under the list while sessions are selected (Ctrl/⌘+click, or Select). Its `run` gets the ids of the sessions, or its sheet gets them as the prop `sessions`. See [`SessionActionSpec`](#sessionactionspec).
503
503
 
504
504
  ### `sessionFilter`
505
505
 
package/docs/features.md CHANGED
@@ -7,14 +7,15 @@ The full tour. For setup, see the [README](../README.md).
7
7
  - **Omarchy colors.** All of Omarchy's themes, from Tokyo Night and Gruvbox to Rosé Pine and the light ones, drawn from each theme's own `colors.toml`, in soft tiles: rounded windows and controls on 1px hairlines, soft shadows only on what floats, Geist for words and JetBrains Mono for code, paths, and numbers, with JetBrains Mono's own italic and the Nerd Fonts icons that prompts and tools print (bundled in `web/fonts/`, with Inter, Fira Code, IBM Plex Mono, and Iosevka for themes to name; `web/fonts/SOURCES.md` says where each came from); light themes too. Menu → **Appearance** (or the **Theme** tile, the launcher, or `/theme gruvbox`) picks one under **Colors**, as well as a theme folder's `colors.toml` (any Omarchy theme folder dropped into `themes/` shows there); the mini-desktop cards in Appearance preview a theme on hover or keyboard focus, and leaving without choosing restores the saved theme. The new look grows as a circle from where you tapped. **Desktop** follows the Omarchy theme of the machine Pi Pocket runs on: change your desktop's theme and the app follows within seconds, optionally with your wallpaper in the gaps.
8
8
  - **Sheets and controls.** Sheets have a 56px title bar on wide screens, a back chevron when opened from another sheet, grouped inset lists, round toggles, and segmented settings. On phones they keep their bottom-sheet grip and drag-to-close gesture. Text sheets have Cancel and the main action together at the bottom; all existing keyboard and back flows stay available. Buttons, fields, and search share the same rounded controls across the app.
9
9
  - **Tiled windows and motion.** On wide screens the sidebar and the session are Hyprland windows, softened: 8px gaps, rounded corners on a hairline, and a soft accent ring on the one under the mouse. Motion uses Omarchy's Hyprland curves: windows pop in at 87%, sheets and popovers rise a little as they fade in, and leave quickly, new messages slide in, and notices count down until they go. While Pi works, the conversation shows what it does; elsewhere a working session's square steps around and a small dot pulses (both hold still with reduced motion). Appearance can turn tiling off (no gaps, square corners, no ring), reduce motion (or follow the system's setting), choose Fluid motion (sheets, menus, the launcher, and notices arrive on a spring and leave quickly, over a frosted scrim; what they hold, and a tool group's first steps, follow a step apart; a message sent lifts off from the message box; each new paragraph of Pi's answer fades in, and its caret breathes; a pressed button springs back; and folding the sidebar morphs the windows into place; Width and tiling change at once, as they are set from a sheet or the launcher, which morphs skip; Auto never picks it), change the conversation's text size (13, 15, 17, or 20, or any size from 10 to 32 px typed in, in half pixels), set the width (Comfortable, which grows with a wide window, Wide, or Full: how much of the window the conversation and the message box take, per browser; phones stay as they are; a reply's code block with long lines grows past the column, centered on it, where plain text and Markdown wrap in the column, and a wide table grows toward the window's edge), set the density (Comfortable, Compact, or Tight: less room between turns, inside message cards and activity groups, between the conversation's lines, in the session list's rows, around the message box and the status line, in sheets and their lists, and in the top bar, while font sizes stay and rows on a touch screen stay a thumb tall), show Pi's thinking while it works, and show the reply speed under the message box.
10
- - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Recent, Folders, and Archived in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet that pins it, marks it unread or read, archives or unarchives it, or selects it. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
10
+ - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Recent, Folders, and Archived in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
11
11
  - **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
12
12
  - **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
13
13
  - **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
14
14
  - **The menu.** The top bar's **⋯** opens a 360px popover below it on wide screens, and a bottom sheet on phones. Three columns of rounded place tiles open Files, Changes, Browser, Artifacts, Chat, Find, Launcher (on touch screens), Branch, PiP, and Peeks when available; badges show counts or news, and open places are tinted. Session actions, Subagents, and App rows have right-aligned hints and separate groups. App includes **Keyboard shortcuts** (`?`). Arrows, Home/End, and Tab move through the controls; Esc, Back, Close, or a tap outside closes the menu. Back from a sheet it opened returns to the menu.
15
15
  - **Keyboard.** Alt+1…9 jumps to a session (hold Alt to see the numbers), Alt+↑/↓ goes to the previous or next one, Alt+N starts a new one (where Ctrl/⌘+1…9 starts it in a favorite folder), Alt+B opens or closes the browser, Alt+E the Files tile, Alt+T turns Show thinking on or off, Alt+V starts or stops dictation, and `?` lists every shortcut. On a computer, a session opens with the caret in its message box, ready to type; on a touch screen it waits for a tap, so the keyboard does not cover the conversation, and on a Mac a session opened with Alt+1…9 or Alt+↑/↓ leaves the box alone, so the next Alt shortcut still works (Option types characters in a box).
16
- - **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; queued messages can be withdrawn, and your own, tapped open, can move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card.
16
+ - **The conversation.** A column of turns, made for phones. Your messages are cards with the sender's avatar (the accent for yours, the sender's color for someone else's), who sent each and when; Pi's replies are plain prose at Appearance's text size, streamed as they come (lists keep a quiet marker column; code, tables, and rich blocks are rounded cards). The **Message time** item under completed replies shows the time, with the date for earlier days, and can be hidden or moved in Appearance → Layout. What Pi does between its words, its thinking and tool calls, folds into one line that says what it did and for how long ("Thought, searched, read 2 files, ran 1 command · 18s"), and opens, as a card, into a timeline: a line per call with a circle for how it went (✓ done, × failed or denied, ! waiting for an approval, a spinner while it runs, ⑂ for a subagent, ✦ for a thought) and what it came to (lines added and removed, lines read, matches, tests passed, an exit code, "needs approval"), and tapped, its input and output, with the diff viewer's diffs for edits (line numbers, syntax colors, and the words that changed) and bash's live output. The newest turn's groups are open and earlier ones closed, unless Appearance's **Keep activity folded** (off by default) keeps them on their line until you open one; a thought alone still follows Show thinking. An approval is a card at the end of its turn (the command, the reason, Deny and Allow; once answered, the call's line says who allowed or denied it), and while Pi works one line, a pulsing dot with the state in the accent (the warning color while it waits for an approval), says what it does (thinking, working, waiting for an approval, retrying) and for how long. With **Show thinking** on in Appearance (or Alt+T, or the launcher), the current thought shows above that line as it streams, and the thoughts in the conversation show their words once written (a thought alone in its group opens, and one on a timeline opens its step). A chevron before the line's dot folds the live thought away, and again brings it back. Alt+T shows a short on/off notice, even while Pi is idle. During tool calls the latest thought stays; a new response clears it until the model shares new thinking. Models that share none say so, rather than showing an old thought as current. A fold holds in that session, also over a reload, until you open it again; the setting is off until you turn it on, in each browser, and while it is off or folded the live thought is neither selected nor drawn. The reading area follows new words until you scroll up in it, and follows again for each new thought. While Pi works, **Steer**, **Queue**, or **Interrupt** beside the model chip says whether a message steers the run, waits for it to end, or stops the run at once (the tool call too, as Stop does, which also withdraws what waits in the queue) and is sent after; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; queued messages can be withdrawn, and your own, tapped open, can go back into the message box to change (**Edit**: its words above what you were typing, on a line of their own, with its files), move to Queue or Steer until Pi reads it, or go now as an Interrupt (a second tap confirms; `CONFIRM_INTERRUPT` in `web/composer.js` turns that off): that stops the run and sends only that message, while every other queued message, from everyone, stays queued in its order with its sender and mode (a restart in between loses or repeats none), and so do subagents' reports; with take turns on, moving one to Steer or Interrupt waits for your turn at the wheel, as sending does; Stop (or Esc twice) stops the run. A run stopped in the middle of a tool call ends with a "Stopped." line under its card.
17
17
  - **Getting around on a phone, with one hand.** Back (the swipe, Android's back button, the browser's) goes back to where you were: it closes what opened last (a sheet, the menu's next sheet back to the menu, a file back to the Files tree, back to Changes when the file was opened from there, the Files tile or the Browser panel, the drawer) before it leaves the session, and leaving goes to the session before or to the list, scrolled and searched as you left it. A session opened straight away (a link, a notification) has the list under it, so back does not leave the app. What you use most is a thumb's reach from the bottom edge: the button beside the message box (or a swipe up from it) opens the places, a short sheet of big tiles (Files, Changes, Browser, Artifacts, Chat, Find, Branch, Peeks) with the session menu below them. On the conversation, swipe left for Files and right to go back; in Files, swipe right to go back. Each swipe shows a mark that lights when letting go will act. The top bar leads back to the list (counting other sessions that wait for an approval) and keeps only the buttons with something to say. Every control is a thumb's size on a touch screen (small ones, such as a code block's Copy or a reply's Pin, keep their look and take a wider tap); a tap anywhere on the message box, off its one line of text, still goes to the text; a quick second tap does not land on whatever just slid in under it; tables in replies scroll sideways instead of crushing their columns; a diff's header keeps the file's name on a line of its own on a phone; and the command a peek tile asks about opens its session when tapped. The Files tile and the browser slide in as screens of their own and slide away on back, a file slides in over the tree, and the browser's tools sit on their own row under the address. Drag a sheet down, or the drawer left, to close it. In an iPhone home screen app, which has no back gesture of its own, swipe in from the left edge to go back.
18
+ - **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words.
18
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.
19
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.
20
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.
@@ -26,10 +27,11 @@ The full tour. For setup, see the [README](../README.md).
26
27
  - **Shell commands.** `!git status` runs in the session's folder, and Pi sees the command and what it printed with your next message, as in Pi's terminal app; `!!git status` shows it only to the people here. While it runs, a row says so, with Stop (it is in Running now too). A restart while it runs does not run it again: its entry says it was cut off. With Lancet Guard on, a command from anyone but the owner must be one the guard allows outright. A command Pi sees counts as its person's message: Pi works for them from there, as for a steer. These are a person's own commands, not Pi's: plan mode does not hold them back. Stop one from its row, or from Running now on any device.
27
28
  - **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. In the conversation, that message shows as a card: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background** (a tap opens Running now), its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. Linux only (it follows processes through `/proc`); it needs bash and `split`.
28
29
  - **Extensions' commands.** A module can add commands to the message box (`/clock-zone Europe/Berlin`), which do something without asking Pi: show a status, change a setting. They show in the suggestions with the app's own, after them; a prompt template of the same name wins. What one gives back is a notice for you alone, or a card of plain text in the conversation for everyone there, which Pi never sees and which does not change whom Pi works for; Find in session and export include it. A conversation command is for whoever may steer (whoever drives, while people take turns); a global one is the owner's, also while someone else drives; viewers get none. Each run is a durable task: sending the same text again after a lost reply gets the first run's result, a restart never runs one again, and Running now shows and stops it. See [Writing extensions](extensions/commands.md).
30
+ - **A person's role and the page's scroll, for extensions.** Since 0.27.0, two experimental members. `host.roleOf(personId)` gives a person's role (`owner`, `guest`, or `viewer`), or `undefined` for an id that is not a person here. It reads the role that core already uses, so a module that guards owner-only things can ask whether Pi works for the owner (`host.requesterOf` gives the id). The snapshot of `host.browser` has a `scroll` field, `{ y, viewport, height }` in CSS pixels, the same numbers that Pi's `browser` tool shows as "scrolled 0 of 800px". See [Writing extensions](extensions/host.md).
29
31
  - **What you sent before.** ↑ in the message box goes back through what you sent from this browser in the current session (↓ comes forward, then back to your draft), and Ctrl+R searches it. The browser keeps up to 200 entries in total across people and sessions, with duplicates removed only within your session. Old browser-wide history stays untouched, but does not appear here: it has no session IDs.
30
32
  - **Dictation.** The mic beside Send, in the message box and in PiP's, dictates with the browser's own speech recognition, in the language the browser is set to. Words show in the box as they are heard and stay once the browser settles on them: at the caret while the box has the focus, after its text when it does not, with a space where they meet; words typed meanwhile stay too, and a phrase still being heard when you type or move the caret elsewhere finishes where it is, the next one going to the caret. It never sends by itself: tap the mic again (or Alt+V, which dictates into PiP's box while PiP is open, else into the session's) to stop, read it over, and send. Sending, leaving the session, closing PiP, or switching away from the tab stops it as well. What was heard is kept as a draft, like typing. While it listens the mic takes the accent, with a ring that breathes (still, with reduced motion), and the box says "Listening…". On a phone while Pi works, the mic takes Send's place until there is something to send. It needs a browser with the Web Speech API: Chrome, which sends the audio to Google's servers to recognise it, and Safari, on iOS too; where there is none (Firefox), the mic does not show. Browsers give a page the microphone only over https or on localhost, as Pi Pocket is served through the Cloudflare Tunnel, Tailscale, or on this device. A blocked microphone, silence, a missing microphone, or no network says so in a notice.
31
33
  - **Long pastes.** Pasting more than 20 lines puts a placeholder such as `[Pasted text #1 · 240 lines]` in the box; the message goes out with the text in its place.
32
- - **Files at a tap.** Inline code paths in Pi's replies (`src/app.ts`, `app.ts:42`), Markdown links to local paths (such as `[config](/etc/app/web.env)`), file mentions in messages, read/write/edit cards, and Changes open a viewer: text with line numbers and syntax colors (Markdown rendered too), images, and folders to browse, with **@ Mention** to put the file in the message box. While the Files tile is open, they open there instead of in a sheet. Someone invited to one session sees its folder only, and only the owner opens Pi's own folder and Pi Pocket's data. For the owner, Ctrl+click (⌘+click on a Mac) on such a path, or on a row in the Files tile, shows it in the file manager of the machine Pi Pocket runs on (Files, Dolphin, Finder, Explorer), selected in its folder; so does the folder button in the viewer, with a mouse. It opens on that machine, not on the device you click from.
34
+ - **Files at a tap.** Inline code paths in Pi's replies (`src/app.ts`, `app.ts:42`), Markdown links to local paths (such as `[config](/etc/app/web.env)`), file mentions in messages, read/write/edit cards, and Changes open a viewer: text with line numbers and syntax colors (Markdown rendered too), images, and folders to browse, with **@ Mention** to put the file in the message box. While the Files tile is open, they open there instead of in a sheet. Opening a file that is already shown reads it again, so after an edit the viewer shows the new text; the old text stays on screen until the new text arrives. Someone invited to one session sees its folder only, and only the owner opens Pi's own folder and Pi Pocket's data. For the owner, Ctrl+click (⌘+click on a Mac) on such a path, or on a row in the Files tile, shows it in the file manager of the machine Pi Pocket runs on (Files, Dolphin, Finder, Explorer), selected in its folder; so does the folder button in the viewer, with a mouse. It opens on that machine, not on the device you click from.
33
35
  - **Files tile.** Menu → **Files** (or Alt+E, `/files`, or the launcher; the folder button in the top bar, where the pane has room) shows the session's folder beside the conversation on wide screens, where the Browser and People panels dock (one of the three at a time), and full screen on phones. Its bar has a switch between **Files** and **Changes** (with the count of changes), the folder's path, and close. **Files** is a tree of the folder that opens as you go (changed files carry an M, A, or D, folders holding changes a dot, and arrow keys move through it), a **Go to file** box that matches across the whole folder as the `@` menu does, and the file you pick, beside the tree when the tile is wide enough (600px) and in its place when not. **Changes** is the review below. Drag the tile's edge to resize it. Esc closes a file open over the tree, and then the tile where it covers the conversation, as back does.
34
36
  - **Find in session.** Ctrl/⌘+F, `/find`, or Menu → **Find in session**: every message, command, and note in the session, earlier history included, newest first; tap one to jump to it.
35
37
  - **Stop with Esc.** Esc twice stops Pi while it works.
@@ -82,7 +84,7 @@ The full tour. For setup, see the [README](../README.md).
82
84
  - **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.
83
85
  - **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.
84
86
  - **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.19.0, Pi writes its tasks for subagents in ASD-STE100 (Simplified Technical English) and asks for their reports in it 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 (**Models for subagents** 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.
85
- - **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. 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. 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. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. 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; **Open as a conversation** 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.
87
+ - **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. 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. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. 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; **Open as a conversation** 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.
86
88
  - **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 four header actions stay available.
87
89
  - **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; **Open as a conversation** keeps its existing 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.
88
90
  - **Files and images in chat.** Pick files with the attach button, paste files or images from the clipboard, or drop them into PiP's message box. Remove attachments before sending; upload status shows while they are saved. You can send files with text or on their own. They belong to PiP's conversation, not the session behind the panel. Images have previews and open full screen; other files show their names. As in normal chat, supported images go directly to an image-capable model and other files are given as saved paths. PiP does not choose a different model for you. Draft attachments stay when you close and reopen the panel.
@@ -97,7 +99,7 @@ The full tour. For setup, see the [README](../README.md).
97
99
  - 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".
98
100
  - 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".
99
101
  - 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.
100
- - **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.
102
+ - **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.
101
103
  - **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, 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.
102
104
  - **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 what it does this moment, 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.
103
105
  - **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.
@@ -118,7 +120,7 @@ The full tour. For setup, see the [README](../README.md).
118
120
  - **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (above Models for subagents), 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.
119
121
  - **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.
120
122
  - **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact_inline` call shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
121
- - **Images inline.** Attached images show as thumbnails (also in the composer before you send). When Pi writes `![description](path)` with a path on the server (absolute, `~/…`, or relative to the session's folder), the image shows in its reply. Images a tool returns and SVG artifacts show inline too. Tap any image to see it full screen. Only real image files are shown: the server checks a file's bytes, not just its name.
123
+ - **Images inline.** Attached images show as thumbnails (also in the composer before you send). When Pi writes `![description](path)` with a path on the server (absolute, `~/…`, or relative to the session's folder), the image shows in its reply. Images a tool returns and SVG artifacts show inline too; an image Pi reads with `read` (often one you just sent) shows only when its call is opened, so it is not on screen twice. Tap any image to see it full screen. Only real image files are shown: the server checks a file's bytes, not just its name.
122
124
  - **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, or Tailscale. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
123
125
 
124
126
  ## Limitations
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.27.0-beta.2",
3
+ "version": "0.27.0-beta.4",
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
@@ -783,6 +783,7 @@ export class PocketApp {
783
783
  },
784
784
  fetchPublic: createPublicFetch(),
785
785
  requesterOf: (conversationId) => this.attribution.requesterOf(conversationId),
786
+ roleOf: (personId) => this.config.userById(personId)?.role,
786
787
  on: (event, listener) => this.events.on(event, listener),
787
788
  ask: (request, askContext) => ask(this.approvals, request, askContext),
788
789
  hide: (value) => this.hidden.add(value),
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { randomUUID } from "node:crypto";
8
8
  import { readFileSync, statSync } from "node:fs";
9
- import { basename, extname, join } from "node:path";
9
+ import { basename, extname, join, sep } from "node:path";
10
10
  import { type Context, copyJson } from "@earendil-works/chord";
11
11
  import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
12
12
  import {
@@ -21,6 +21,7 @@ import {
21
21
  AgentDoc,
22
22
  type ConversationCreateOptions,
23
23
  type ConversationId,
24
+ type Cursor,
24
25
  defineTask,
25
26
  type EntryId,
26
27
  type InputEntry,
@@ -90,6 +91,33 @@ const context = BACKGROUND_CONTEXT;
90
91
 
91
92
  export type Attachment = { path: string; name: string; mime: string; size: number };
92
93
 
94
+ /**
95
+ * A file in a message's list of attached files (`- path (name, type, size bytes)`, as `submit` writes it), if it is one of
96
+ * the session's uploads. A name can hold " (", so the path is the part that ends with "-name".
97
+ */
98
+ function attachedFile(line: string, uploads: string): Attachment[] {
99
+ const tail = /, ([^,]+), (\d+) bytes\)$/.exec(line);
100
+
101
+ if (!line.startsWith("- ") || tail === null) {
102
+ return [];
103
+ }
104
+
105
+ const head = line.slice(2, tail.index);
106
+
107
+ for (let at = head.indexOf(" ("); at !== -1; at = head.indexOf(" (", at + 1)) {
108
+ const path = head.slice(0, at);
109
+ const name = head.slice(at + 2);
110
+
111
+ if (path.startsWith(uploads + sep) && path.endsWith(`-${name}`)) {
112
+ const mime = tail[1] === "unknown type" ? "" : tail[1]!;
113
+
114
+ return [{ path, name, mime, size: Number(tail[2]) }];
115
+ }
116
+ }
117
+
118
+ return [];
119
+ }
120
+
93
121
  export interface SubmitRequest {
94
122
  text: string;
95
123
  attachments?: Attachment[];
@@ -1292,6 +1320,57 @@ export class Commands {
1292
1320
  return result;
1293
1321
  }
1294
1322
 
1323
+ /**
1324
+ * Take one's own queued message back to change it: it leaves the queue, as with `withdraw`, and its words and
1325
+ * attached files come back for the message box. Only its sender may, as with moving it.
1326
+ */
1327
+ async editQueued(
1328
+ id: ConversationId,
1329
+ user: User,
1330
+ submissionId: number,
1331
+ ): Promise<{ text: string; attachments: Attachment[] }> {
1332
+ const app = this.#app;
1333
+
1334
+ app.requireSee(user, id);
1335
+ app.requireSteer(user);
1336
+
1337
+ if (!Number.isInteger(submissionId) || submissionId <= 0) {
1338
+ throw new HttpError(400, "Say which queued message to edit.");
1339
+ }
1340
+
1341
+ if ((await app.attribution.submitter(submissionId)) !== user.id) {
1342
+ throw new HttpError(403, "Only its sender can edit a queued message.");
1343
+ }
1344
+
1345
+ const item = (await app.harness.snapshot(InboxDoc, id, context))?.items.find(
1346
+ (entry) => Number(entry.id) === submissionId,
1347
+ );
1348
+ // Taken back only if Pi has not read it yet: then what it says is the message as it was queued.
1349
+ const result =
1350
+ item === undefined || item.mode === "write"
1351
+ ? "not_found"
1352
+ : await app.harness.abortSubmission(
1353
+ submissionId as unknown as SubmissionId,
1354
+ context,
1355
+ id,
1356
+ );
1357
+
1358
+ if (item === undefined || item.mode === "write" || result !== "aborted") {
1359
+ throw new HttpError(409, "That message has already gone to Pi.");
1360
+ }
1361
+
1362
+ // shortcut: a `/skill:` or prompt template message comes back as it was sent, expanded.
1363
+ const [written, files] = splitAttachments(
1364
+ userContent({ content: item.content }).text.replace(FROM_PREFIX, ""),
1365
+ );
1366
+ const uploads = app.workspace.uploadDirectory(id);
1367
+
1368
+ return {
1369
+ text: written,
1370
+ attachments: (files ?? "").split("\n").flatMap((line) => attachedFile(line, uploads)),
1371
+ };
1372
+ }
1373
+
1295
1374
  /**
1296
1375
  * Move a queued message to Steer or Queue, or send it now as an Interrupt. Only its sender may, as with taking it
1297
1376
  * back (`withdraw`): who else may move someone's message is left to the maintainers. Interrupt stops the run like
@@ -1940,13 +2019,27 @@ export class Commands {
1940
2019
  }
1941
2020
  }
1942
2021
 
1943
- /** A new session with this session's history through `entryId`, which then goes its own way. */
2022
+ /**
2023
+ * A new session with this session's history through `entryId`, which then goes its own way. Without `entryId`, the
2024
+ * whole session as it stands: through Pi's latest finished reply (a session list's Fork), or none of it before one.
2025
+ */
1944
2026
  async fork(
1945
2027
  id: ConversationId,
1946
2028
  user: User,
1947
2029
  request: { entryId?: unknown; worktree?: unknown },
1948
2030
  ): Promise<{ id: ConversationId }> {
1949
2031
  this.#requireForkable(id, user);
2032
+
2033
+ if (request.entryId === undefined) {
2034
+ return {
2035
+ id: await this.#branch(id, user, {
2036
+ at: await this.#latestReply(id),
2037
+ label: "fork",
2038
+ worktree: request.worktree === true,
2039
+ }),
2040
+ };
2041
+ }
2042
+
1950
2043
  const entryId = entryIdOf(request.entryId);
1951
2044
  const entry = await this.#app.transcripts.visibleEntry(id, entryId);
1952
2045
 
@@ -2092,6 +2185,34 @@ export class Commands {
2092
2185
  return { id: forked };
2093
2186
  }
2094
2187
 
2188
+ /**
2189
+ * The id of Pi's newest finished reply in a session, or undefined before its first: where a fork of the whole session
2190
+ * ends. A reply that called tools is not finished (a fork from it would wait for their results), nor is one cut off.
2191
+ */
2192
+ async #latestReply(id: ConversationId): Promise<number | undefined> {
2193
+ const conversation = await this.#app.conversation(id);
2194
+ let cursor: Cursor | undefined;
2195
+
2196
+ do {
2197
+ const page = await conversation.entries({}, 64, cursor, context);
2198
+
2199
+ for (const entry of page.items) {
2200
+ const reply = entry.model?.[0];
2201
+
2202
+ if (
2203
+ entry.kind === "pi.assistant" &&
2204
+ !(reply?.role === "assistant" && reply.stopReason === "toolUse")
2205
+ ) {
2206
+ return Number(entry.id);
2207
+ }
2208
+ }
2209
+
2210
+ cursor = page.next;
2211
+ } while (cursor !== undefined);
2212
+
2213
+ return undefined;
2214
+ }
2215
+
2095
2216
  /** Forks are new sessions: who may start one may fork, from a session they can see. */
2096
2217
  #requireForkable(id: ConversationId, user: User): void {
2097
2218
  const app = this.#app;
@@ -898,6 +898,7 @@ export async function withRender<T>(
898
898
  server = await serveBundle(bundle);
899
899
  browser = await Chromium.launch(executable, profile, [
900
900
  "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
901
+ ...(process.env.PI_POCKET_BROWSER_ARGS?.split(/\s+/).filter(Boolean) ?? []),
901
902
  ]);
902
903
  controller.signal.throwIfAborted();
903
904
  const context = await browser.connection.send("Target.createBrowserContext");
@@ -195,6 +195,11 @@ export function browserHandle(page: BrowserPage): BrowserPageHandle {
195
195
  text: outline.lines,
196
196
  controls: outline.items ?? [],
197
197
  truncated: outline.truncated,
198
+ scroll: {
199
+ y: outline.scrollY,
200
+ viewport: outline.innerHeight,
201
+ height: outline.scrollHeight,
202
+ },
198
203
  };
199
204
  },
200
205
  inspect: async (at: BrowserTarget) => {
@@ -205,16 +205,29 @@ export default function createPip(host: PocketHost) {
205
205
  const read = defineTool({
206
206
  name: "session_read",
207
207
  description:
208
- "Read the newest part of a session: its state, calls waiting for approval, scheduled messages, and its last messages, with Pi's last answer in full.",
208
+ "Read the newest part of a session: its state, calls waiting for approval, scheduled messages, and its last messages. Pi's last answer comes in parts of up to 12000 characters: when it is cut, a note says how many characters are left, and answerFrom reads them.",
209
209
  parameters: Type.Object({
210
210
  session,
211
211
  entries: Type.Optional(
212
212
  Type.Number({ description: "How many of the newest entries to read (default 40)" }),
213
213
  ),
214
+ answerFrom: Type.Optional(
215
+ Type.Number({
216
+ description:
217
+ "Read only Pi's last answer, from this character on (use the number in the note of a cut answer)",
218
+ }),
219
+ ),
214
220
  }),
215
221
  replay: "safe",
216
222
  execute: async (args, api) =>
217
- reply(await host.pip.read(api.conversationId, args.session, args.entries)),
223
+ reply(
224
+ await host.pip.read(
225
+ api.conversationId,
226
+ args.session,
227
+ args.entries,
228
+ args.answerFrom,
229
+ ),
230
+ ),
218
231
  });
219
232
 
220
233
  // The GitHub tools need a server that has them: one started before they were added gets them at its restart.
@@ -179,7 +179,13 @@ export interface BrowserPageHandle {
179
179
  readonly url: string;
180
180
  readonly title: string;
181
181
  /** The page as Pi reads it (`text`, with refs such as `[e12]`) and its controls as data. Refs last until the next. */
182
- snapshot(): Promise<{ text: string; controls: BrowserControl[]; truncated: boolean }>;
182
+ snapshot(): Promise<{
183
+ text: string;
184
+ controls: BrowserControl[];
185
+ truncated: boolean;
186
+ /** Where the page is scrolled, in CSS pixels: the viewport's top and height, and the page's height. */
187
+ scroll: { y: number; viewport: number; height: number };
188
+ }>;
183
189
  /** What a target is: its description, its kind (an input's type, or a tag), and whether it is a field or a password. */
184
190
  inspect(
185
191
  target: BrowserTarget,
@@ -374,6 +380,12 @@ export interface PocketHost {
374
380
  readonly fetchPublic: FetchPublic;
375
381
  /** Who Pi works for in a conversation now: whose message led to its current work. */
376
382
  requesterOf(conversationId: ConversationId): string | undefined;
383
+ /**
384
+ * The role of a person by id, as core decides it; undefined for an id that is not a person here.
385
+ *
386
+ * @experimental In 0.27: it can change in a minor release (docs/extensions/policies/api-stability.md).
387
+ */
388
+ roleOf(personId: string): Role | undefined;
377
389
  /**
378
390
  * Listen to what happens in the app: sessions made, renamed, and archived, messages people send to Pi, and
379
391
  * runs that start and end. Returns how to stop; pass that to `web.onDispose`. PiP's conversations send none.
@@ -167,6 +167,16 @@ export async function conversationRoutes(
167
167
  });
168
168
  }
169
169
 
170
+ if (third === "edit-queued" && method === "POST") {
171
+ const body = await readJson<{ submissionId?: number }>(request);
172
+
173
+ return json(
174
+ response,
175
+ 200,
176
+ await app.commands.editQueued(id, user, Number(body.submissionId)),
177
+ );
178
+ }
179
+
170
180
  if (third === "move" && method === "POST") {
171
181
  const body = await readJson<{ submissionId?: number; mode?: string }>(request);
172
182