pi-pocket 0.27.0-beta.5 → 0.27.0-beta.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -97,33 +97,41 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
97
97
 
98
98
  ### The frame
99
99
 
100
- | Part | What |
101
- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
- | `boot` | The screen while the app starts |
104
- | `brand-mark` | The π: on the rail, and on the boot screen |
105
- | `sidebar` | The rail and the session list, on wide screens |
106
- | `drawer` | The rail and the session list sliding in, on narrow screens |
107
- | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
- | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
109
- | `session-search` | The search field |
110
- | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
111
- | `session-tabs` | Recent, Folders, Archived |
112
- | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
113
- | `session-group`, `session-group-head` | A group of rows (a day, a folder), and its head, which folds it |
114
- | `session-group-name`, `session-group-count` | The head's name, and its count |
115
- | `session-row` | One session's line |
116
- | `session-button` | The row's button: its square, title, and what is on its right |
117
- | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
118
- | `session-branches` | The lines to a session that another one started |
119
- | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
120
- | `home` | The home screen on wide screens |
121
- | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
122
- | `home-actions` | Its buttons |
123
- | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
124
- | `home-list` | The session list as a phone's home screen |
125
- | `pane` | The conversation's window (or the subagents board, or an extension's page) |
126
- | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
100
+ | Part | What |
101
+ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
+ | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
+ | `boot` | The screen while the app starts |
104
+ | `brand-mark` | The π: on the rail, and on the boot screen |
105
+ | `sidebar` | The rail and the session list, on wide screens |
106
+ | `drawer` | The rail and the session list sliding in, on narrow screens |
107
+ | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
+ | `rail-needs` | The warning-colored count on the Sessions button: how many sessions need you (since 0.27.0) |
109
+ | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
110
+ | `session-search` | The search field |
111
+ | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
112
+ | `session-tabs` | Priority, Recent, Folders, and Archived (an icon) |
113
+ | `session-tab`, `session-tab-count` | One tab; and Priority's count of the sessions that need you (since 0.27.0) |
114
+ | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
115
+ | `session-group`, `session-group-head` | A group of rows (a day, a folder, a Priority group), and its head, which folds it; Priority's Needs you does not fold, and its head is not a button |
116
+ | `session-group-bar`, `session-group-action` | In Priority, a group's head with its button beside it (Dismiss N failed, Mark all read), and that button (since 0.27.0) |
117
+ | `session-clear`, `session-more` | In Priority, the line "Nothing needs you", and Show N more under Needs you (since 0.27.0) |
118
+ | `session-group-name`, `session-group-count` | The head's name, and its count |
119
+ | `session-row` | One session's line |
120
+ | `session-button` | The row's button: its square, title, and what is on its right |
121
+ | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
122
+ | `session-limit` | In Priority's Working group, the clock pill with the time a usage limit clears (since 0.27.0) |
123
+ | `session-quick`, `session-review`, `session-dismiss`, `session-read` | In Priority, the button at the right of a row: Review (a call waits), Dismiss (a failure), and Mark read on hover (since 0.27.0) |
124
+ | `session-ask`, `session-ask-command`, `session-ask-reason` | The call open in a row of Needs you, its command, and why the guard asks (since 0.27.0) |
125
+ | `session-deny`, `session-decline`, `session-allow`, `session-ask-open` | That call's buttons (since 0.27.0) |
126
+ | `session-branches` | The lines to a session that another one started |
127
+ | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
128
+ | `home` | The home screen on wide screens |
129
+ | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
130
+ | `home-actions` | Its buttons |
131
+ | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
132
+ | `home-list` | The session list as a phone's home screen |
133
+ | `pane` | The conversation's window (or the subagents board, or an extension's page) |
134
+ | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
127
135
 
128
136
  ### The conversation
129
137
 
@@ -200,7 +208,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
200
208
  | `session-row` | `data-state` | `working`, `waiting` (for you), `limited` (waiting for a provider's limit to clear, since 0.21.0), `failed`, `done` (since you looked), `idle` |
201
209
  | `peek-tile` | `data-state` | The same as `session-row`'s, but without `failed` |
202
210
  | `session-button` | `aria-current` | `page` on the open session's |
203
- | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open |
211
+ | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open; none on Priority's Needs you head, which does not fold |
204
212
  | `activity` | `data-state` | `open` while open |
205
213
  | `tool-call` | `data-state` | `running`, `ok`, `failed`, `waiting` (for approval), `denied`, `stopped` |
206
214
  | `prompt` | `data-from` | `me`, `person` (someone else), `linked` (a linked session), `other` (Pi's schedule, the main agent, a watch or a webhook) |
@@ -237,6 +245,8 @@ A part's `::before` and `::after` are a theme's to use, except these, which the
237
245
  | ---------------------------------------------- | --------------------------------------------------------------------------- |
238
246
  | `session-group-head` | `::after`: its tap area on touch screens |
239
247
  | `session-mark` | `::before`: the square that steps while the session works |
248
+ | `session-review`, `session-dismiss` | `::before`: their tap areas (since 0.27.0) |
249
+ | `session-group-action` | `::before`: its tap area on touch screens (since 0.27.0) |
240
250
  | `timeline` | `::before`: the rule |
241
251
  | `composer-button`, `model-chip`, `send-button` | `::before`: their tap areas on phones; the mic's `::after` while it listens |
242
252
  | `notice` | `::after`: the bar that counts down |
package/docs/features.md CHANGED
@@ -7,7 +7,7 @@ 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 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.
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 Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). 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.
package/docs/map.md CHANGED
@@ -18,25 +18,25 @@ A module split into parts keeps its name for the part others import, with the re
18
18
 
19
19
  ### The core
20
20
 
21
- | File | Owns |
22
- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
- | `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler` |
24
- | `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off Bundle readers for artifacts (`artifactBundle`: the page and its assets by hash, `artifactAsset`: one manifest asset), which callers must check access for. |
25
- | `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup |
26
- | `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`) |
27
- | `projection.ts` | Entries as compact JSON for browsers; `usageCost` |
28
- | `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed |
29
- | `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions |
30
- | `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait |
31
- | `cache-keeper.ts` | The prompt cache keeper around every model stream: replays a tool-call request with one output token just before its 5-minute cache expires, when that costs less than a rebill; stops on a real request, run end, error, shutdown, or 30 minutes; warm usage counts in spend |
32
- | `entry-format.ts` | The kinds of Pi Pocket's own entries, and the markers it writes into message text (`[from: …]`, attached files). Stored data and the web app depend on their exact values |
33
- | `fence.ts` | Text from elsewhere between tags as data, for Pi: no closing tag survives inside it |
34
- | `docs.ts` | Every durable document Pi Pocket defines The design workspace's `pocket.design-comments` (comments, tweaks, restores) and the artifact bundle documents (`pocket.artifact-asset`, by content hash). |
35
- | `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
36
- | `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
37
- | `lock.ts` | One process per data folder |
38
- | `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
39
- | `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
21
+ | File | Owns |
22
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
+ | `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler` |
24
+ | `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state; for Priority, the oldest waiting call and how many wait (`approval`), a failed run's reason (`failure`), and failed subagents nobody dealt with (`failedAgents`)), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off Bundle readers for artifacts (`artifactBundle`: the page and its assets by hash, `artifactAsset`: one manifest asset), which callers must check access for. |
25
+ | `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup |
26
+ | `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`) |
27
+ | `projection.ts` | Entries as compact JSON for browsers; `usageCost` |
28
+ | `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed |
29
+ | `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions |
30
+ | `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait |
31
+ | `cache-keeper.ts` | The prompt cache keeper around every model stream: replays a tool-call request with one output token just before its 5-minute cache expires, when that costs less than a rebill; stops on a real request, run end, error, shutdown, or 30 minutes; warm usage counts in spend |
32
+ | `entry-format.ts` | The kinds of Pi Pocket's own entries, and the markers it writes into message text (`[from: …]`, attached files). Stored data and the web app depend on their exact values |
33
+ | `fence.ts` | Text from elsewhere between tags as data, for Pi: no closing tag survives inside it |
34
+ | `docs.ts` | Every durable document Pi Pocket defines The design workspace's `pocket.design-comments` (comments, tweaks, restores) and the artifact bundle documents (`pocket.artifact-asset`, by content hash). |
35
+ | `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
36
+ | `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
37
+ | `lock.ts` | One process per data folder |
38
+ | `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
39
+ | `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
40
40
 
41
41
  `extension-request.ts` owns extension routes' request-lifetime document/context capabilities and fresh person/source authorization. `http/extension-routes.ts` binds named source parameters and supplies human linked-session capabilities. `linked-sessions.ts` keeps the short final-admission lease; its child context watches policy publications and checks current config when Durable enters admission. `models.ts` supplies exact local `host.modelInfo` metadata. `versions.ts` supplies `host.pocketVersion` and `hello.server.pocketVersion`, read by browser `pocket.pocketVersion`; `pocket.openConversation` delegates to normal `store.navigate`.
42
42
 
@@ -215,13 +215,13 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
215
215
  | `sheets.js` | Which sheet is open, the component that shows it, and the nested-sheet back action supplied to `Sheet` through `SheetBack` |
216
216
  | `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend, running now, schedules, webhooks, memory (the lessons Pi keeps, with the menu's hint), worktree, Pi's terminal sessions, appearance, shortcuts, the menu, a session's actions, the extension gallery (`gallery.js`: browsing, an entry, its source, an update, sharing; `galleryAvailable`), with the artifact viewer's **Open in Design** button (`viewers.js`) |
217
217
  | `peeks.js` | Peek tiles: their switches (the top bar's and the rail's), which sessions get one and in what order (working, waiting, with subagents at work, finished, or pinned), the column and the strip, each tile's subagents at work (the first few as rows, the rest counted, opening the board at them) and their own peeks, the watch list |
218
- | `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it |
218
+ | `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it; the list also puts looks back (`seenSnapshot`, `restoreSeen`) when it undoes marking sessions read |
219
219
  | `clock.js` | The server's clock as a tab knows it, without the DOM: how far it is ahead of this browser's, fitted to what each hello proves, so a hello handled late (a tab woken from the background) moves no time shown |
220
220
  | `chat.js` | People panel: presence roster, take-turns shortcut, chat bubbles, pins, notes; the chat sheet |
221
221
  | `avatar.js` | People's avatars and colors, and folders' colors |
222
222
  | `subagents-board.js` | The subagents board: every subagent in every session (the server's `subagents` events, while it shows), soft state-colored cells and rounded session rows, a sub-tile for each at work saying what it does now, the proportional state bar and filter pills, Needs you, the selected detail card (its peek), the arrows, and the phone's layout |
223
223
  | `extension-ui.js` | Extensions' browser modules: loading them as `hello` lists them (`server.ui`), `pocket` (the app's API for them), and what they add: rail buttons (`ExtensionRailButtons`), menu rows, launcher actions, pages in the conversation's place (`ExtensionPage`, `state.page`), panels beside it (`ExtensionPanel`, `state.extPanel`, with `ExtensionPanelButtons` in the top bar and `extensionPlaces` in the places), status-line items (`extensionStatusItems`, drawn by `composer.js`), sheets (`ExtensionSheet`), and the session list's chips, words, filters, and actions (`sessionChips`, `sessionWords`, `sessionFilters` and `sessionFilterTest`, `sessionActions`, drawn by `sessions.js`, `sheets/session.js`, and `launcher.js`); one that fails, alone, and how their tools' calls show (`pocket.toolCall`, given to `calls.js` and `turns.js`) |
224
- | `sessions.js` | The sidebar: the rail (`RailNav`: the tools, you, and, folded, numbered sessions) and the session list beside it (sidebar, drawer, a phone's home screen), a line per session, with extensions' chips under its title; extensions' filters beside the search; selecting rows and archiving them with undo (`setArchived`), and extensions' actions in the bar for them, and a touch screen's long press on a row, which opens `sheets/session.js`; linked sessions under the one that started them, with branch lines (`session-tree.js`, the tree as data) |
224
+ | `sessions.js` | The sidebar: the rail (`RailNav`: the tools, you, and, folded, numbered sessions) and the session list beside it (sidebar, drawer, a phone's home screen), a line per session, with extensions' chips under its title; extensions' filters beside the search; selecting rows and archiving them with undo (`setArchived`), and extensions' actions in the bar for them, and a touch screen's long press on a row, which opens `sheets/session.js`; linked sessions under the one that started them, with branch lines (`session-tree.js`, the tree as data); and Priority (`priorityGroups`, `slotOf`, `needOf`): sessions by what they ask of you, with a call open in its row (`NeedAsk`), dismissing failures, and marking sessions read, each with an undo where one is possible; the rail's count of sessions that need you (`needsYouCount`) |
225
225
  | `home.js`, `signin.js` | The wide home screen; the sign-in screen |
226
226
  | `notify.js`, `sw.js` | Push, the icon badge, approvals from notifications, shares; the notifications sheet |
227
227
  | `share.js` | Share to Pi |
package/docs/releases.md CHANGED
@@ -4,13 +4,12 @@ Pi Pocket ships a stable release every Friday. Between two Fridays, the next rel
4
4
 
5
5
  ## The week
6
6
 
7
- | When | What happens |
8
- | ----------------------- | ------------------------------------------------------------------------------------------------------- |
9
- | Friday, after a release | The branch of the next release opens: `release/X.Y.0`, from `main`. |
10
- | Saturday to Wednesday | Ready pull requests merge into the release branch. A beta comes out when something worth trying lands. |
11
- | Wednesday, end of day | Code freeze: from now on, only fixes go into the release branch. The last beta comes out. |
12
- | Thursday | The review and live-test rounds run on the release branch, and their fixes go in. |
13
- | Friday | The release pull request merges into `main`. The tag `vX.Y.0` and the GitHub release publish it to npm. |
7
+ | When | What happens |
8
+ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Friday, after a release | The branch of the next release opens: `release/X.Y.0`, from `main`. |
10
+ | Saturday to Thursday | Ready pull requests merge into the release branch. A beta comes out when something worth trying lands. |
11
+ | Thursday, end of day | Code freeze: from now on, only fixes go into the release branch. The last beta comes out. |
12
+ | Friday | The review and live-test rounds run on the release branch, and their fixes go in. Then the release pull request merges into `main`, and the tag `vX.Y.0` and the GitHub release publish it to npm. |
14
13
 
15
14
  A week with nothing to ship has no release. A change that is not ready by the freeze waits for the next week.
16
15
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.27.0-beta.5",
3
+ "version": "0.27.0-beta.6",
4
4
  "description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
5
5
  "keywords": [
6
6
  "pi",
@@ -44,7 +44,7 @@
44
44
  "start": "node bin/pi-pocket.js",
45
45
  "dev": "node bin/pi-pocket.js --cwd .",
46
46
  "check": "tsc --noEmit -p . && node test/types-file.ts && node docs-site/check-reference.mjs",
47
- "test": "node --test test/*.test.ts",
47
+ "test": "node --test --test-concurrency=4 test/*.test.ts",
48
48
  "design:check": "node src/server/design/check-cli.ts",
49
49
  "site:publish": "gh workflow run pages.yml",
50
50
  "format": "eslint --fix . && prettier --write .",
package/src/server/app.ts CHANGED
@@ -113,6 +113,7 @@ import { PushStore } from "./push.ts";
113
113
  import { type ExtensionInfo, ExtensionLoader, linkTypes, prepareDropInFolder } from "./reload.ts";
114
114
  import { ResendTask } from "./resend.ts";
115
115
  import { type Client, reportingOf, Room, ROOM_DOCS, subagentView } from "./room.ts";
116
+ import { whyUnanswered } from "./subagent-runs.ts";
116
117
  import { Schedules } from "./schedules.ts";
117
118
  import { BackgroundTasks } from "./background.ts";
118
119
  import { Shares } from "./share.ts";
@@ -173,6 +174,30 @@ export const MAX_PEEKS = 20;
173
174
  */
174
175
  const FAILED_RUN = new Set(["model_error", "no_model", "faulted"]);
175
176
 
177
+ /** How much of a failed run's reason the session list carries: it goes to every tab on each change. */
178
+ const FAILURE_TEXT = 120;
179
+ /** How much of a waiting call the session list carries (a tile's peek has more): enough to tell calls apart. */
180
+ const ASK_SUBJECT = 200;
181
+ const ASK_REASON = 200;
182
+ /** The most failed subagents a session's row names: the list goes to every tab. */
183
+ const FAILED_AGENTS = 5;
184
+
185
+ /** The call a session waits on, as its row in the session list carries it. */
186
+ type SessionAsk = {
187
+ id: string;
188
+ conversationId: number;
189
+ tool: string;
190
+ subject: string;
191
+ reason: string;
192
+ requestedBy?: string;
193
+ /** An extension's question (`host.ask`): answered on its card, where its fields are. */
194
+ form?: true;
195
+ /** When it asked (the server's clock). */
196
+ at: number;
197
+ /** How many calls wait in the session, its subagents' too. */
198
+ count: number;
199
+ };
200
+
176
201
  /** A conversation's subagents document, as far as the app reads it. */
177
202
  type SubagentsValue = {
178
203
  agents?: Record<string, SubagentRecord>;
@@ -258,6 +283,24 @@ function countSubagents(
258
283
  return counts;
259
284
  }
260
285
 
286
+ /**
287
+ * A session's failed subagents that nobody dealt with, newest first: what the list's Dismiss needs (the failure is
288
+ * named by when it failed, as `dismissSubagent` takes it). Stopped ones did not fail, and the rest are dealt with.
289
+ */
290
+ function failedSubagents(
291
+ entries: readonly SubagentEntry[],
292
+ ): { name: string; conversationId: number; at: number }[] {
293
+ return entries
294
+ .filter((entry) => subagentState(entry) === "failed" && entry.dealt !== true)
295
+ .sort((a, b) => (b.answeredAt ?? 0) - (a.answeredAt ?? 0))
296
+ .slice(0, FAILED_AGENTS)
297
+ .map((entry) => ({
298
+ name: entry.name,
299
+ conversationId: Number(entry.conversationId),
300
+ at: entry.answeredAt ?? 0,
301
+ }));
302
+ }
303
+
261
304
  export interface OpenOptions {
262
305
  dataDir: string;
263
306
  defaultCwd: string;
@@ -370,7 +413,7 @@ export class PocketApp {
370
413
  * Conversations whose last run ended because the model or provider failed (not stopped by someone), since this
371
414
  * server started: the session list marks them until their next run starts.
372
415
  */
373
- readonly #failed = new Set<ConversationId>();
416
+ readonly #failed = new Map<ConversationId, string>();
374
417
  /** How many commands each session runs in the background now (`background.ts`): the list and status line show it. */
375
418
  readonly #background = new Map<ConversationId, number>();
376
419
  readonly #agents = new Map<ConversationId, AgentState>();
@@ -1061,7 +1104,13 @@ export class PocketApp {
1061
1104
  this.#sessions[String(change.value.conversationId)] !== undefined &&
1062
1105
  !this.#failed.has(change.value.conversationId)
1063
1106
  ) {
1064
- this.#failed.add(change.value.conversationId);
1107
+ this.#failed.set(
1108
+ change.value.conversationId,
1109
+ whyUnanswered(change.value.reason, change.value.detail).slice(
1110
+ 0,
1111
+ FAILURE_TEXT,
1112
+ ),
1113
+ );
1065
1114
  sessionsChanged = true;
1066
1115
  }
1067
1116
  }
@@ -2313,6 +2362,39 @@ export class PocketApp {
2313
2362
  }
2314
2363
  }
2315
2364
 
2365
+ /**
2366
+ * The call each session waits on, by session: the oldest one waiting there or in a subagent of it, as a tile's peek
2367
+ * shows its calls, cut short (the list goes to every tab), and how many wait.
2368
+ */
2369
+ #oldestAsks(): Map<string, SessionAsk> {
2370
+ const asks = new Map<string, SessionAsk>();
2371
+
2372
+ for (const request of this.approvals.all()) {
2373
+ const session = String(this.rootOf(request.conversationId));
2374
+ const kept = asks.get(session);
2375
+
2376
+ if (kept !== undefined && kept.at <= request.createdAt) {
2377
+ kept.count++;
2378
+
2379
+ continue;
2380
+ }
2381
+
2382
+ asks.set(session, {
2383
+ id: request.id,
2384
+ conversationId: Number(request.conversationId),
2385
+ tool: request.tool,
2386
+ subject: request.subject.slice(0, ASK_SUBJECT),
2387
+ reason: request.reason.slice(0, ASK_REASON),
2388
+ ...(request.requestedBy === undefined ? {} : { requestedBy: request.requestedBy }),
2389
+ ...(request.form === undefined ? {} : { form: true as const }),
2390
+ at: request.createdAt,
2391
+ count: (kept?.count ?? 0) + 1,
2392
+ });
2393
+ }
2394
+
2395
+ return asks;
2396
+ }
2397
+
2316
2398
  /** The session list, with who is in each session and its newest chat message. Scoped people see only theirs. */
2317
2399
  sessions(user?: User) {
2318
2400
  const waiting = new Set(
@@ -2320,6 +2402,7 @@ export class PocketApp {
2320
2402
  );
2321
2403
  const people = new Map<string, Map<string, string>>();
2322
2404
  const subagents = this.#subagentsBySession();
2405
+ const asks = this.#oldestAsks();
2323
2406
  // The sessions in a wait for a provider's limit, their subagents' included: when the next request goes out.
2324
2407
  const limited = new Map<string, number>();
2325
2408
 
@@ -2358,6 +2441,9 @@ export class PocketApp {
2358
2441
  const endedAt = this.#endedAt.get(Number(id) as unknown as ConversationId);
2359
2442
  const counts = countSubagents(subagents.get(id) ?? []);
2360
2443
  const background = this.#background.get(Number(id) as unknown as ConversationId);
2444
+ const failure = this.#failed.get(Number(id) as unknown as ConversationId);
2445
+ const failedAgents = failedSubagents(subagents.get(id) ?? []);
2446
+ const ask = asks.get(id);
2361
2447
  // Which of Pi's sessions it continues is the owner's to know (the Pi sessions sheet), not the list's.
2362
2448
  const { fromPi: _fromPi, linkedFrom, ...shown } = meta;
2363
2449
  // Linking does not share the origin: do not leak its id to someone who only sees the new chat.
@@ -2384,9 +2470,9 @@ export class PocketApp {
2384
2470
  waiting: waiting.has(id),
2385
2471
  ...(limited.has(id) ? { limited: limited.get(id)! } : {}),
2386
2472
  ...(endedAt === undefined ? {} : { endedAt }),
2387
- ...(this.#failed.has(Number(id) as unknown as ConversationId)
2388
- ? { failed: true }
2389
- : {}),
2473
+ ...(failure === undefined ? {} : { failed: true, failure }),
2474
+ ...(failedAgents.length === 0 ? {} : { failedAgents }),
2475
+ ...(ask === undefined ? {} : { approval: ask }),
2390
2476
  ...(model === undefined ? {} : { model: model.modelId }),
2391
2477
  ...(here.length === 0 ? {} : { people: here }),
2392
2478
  ...(chat === undefined ? {} : { chatAt: chat.at, chatBy: chat.userId }),
package/web/peeks.js CHANGED
@@ -479,7 +479,7 @@ function PeekLine({ line }) {
479
479
  * Whether a call's command is short enough to show whole on its tile: only then may it be allowed from there. Shown
480
480
  * whole, it is never clamped; the tile also measures that it fits (`PeekTile`), as wide characters take more room.
481
481
  */
482
- const wholeOnTile = (approval) =>
482
+ export const wholeOnTile = (approval) =>
483
483
  approval.subject.length <= ALLOW_LENGTH && !/[\r\n]/.test(approval.subject);
484
484
 
485
485
  /** The call a session waits on, in full when it is short, and why the guard asks. */
package/web/seen.js CHANGED
@@ -79,6 +79,43 @@ export function markSeen(...ids) {
79
79
  }
80
80
  }
81
81
 
82
+ /** When this browser last looked at each of these sessions (0 for never), to put back with `restoreSeen`. */
83
+ export function seenSnapshot(ids) {
84
+ return Object.fromEntries(ids.map((id) => [id, store.state.peekSeen?.[id] ?? 0]));
85
+ }
86
+
87
+ /**
88
+ * Put looks back as `seenSnapshot` took them: what undoes marking sessions read from the list. With `expected` (a
89
+ * snapshot taken just after the marking), only looks still as the marking left them go back: a session looked at since,
90
+ * in this tab or another, stays seen. Returns the ids put back.
91
+ */
92
+ export function restoreSeen(snapshot, expected) {
93
+ const peekSeen = { ...store.state.peekSeen };
94
+ const back = new Set();
95
+
96
+ for (const [id, at] of Object.entries(snapshot)) {
97
+ const now = Number(localStorage.getItem(SEEN_PREFIX + id)) || 0;
98
+
99
+ if (expected !== undefined && now !== (expected[id] ?? 0)) {
100
+ continue;
101
+ }
102
+
103
+ back.add(Number(id));
104
+
105
+ if (at > 0) {
106
+ localStorage.setItem(SEEN_PREFIX + id, String(at));
107
+ peekSeen[id] = at;
108
+ } else {
109
+ localStorage.removeItem(SEEN_PREFIX + id);
110
+ delete peekSeen[id];
111
+ }
112
+ }
113
+
114
+ store.set({ peekSeen });
115
+
116
+ return back;
117
+ }
118
+
82
119
  /**
83
120
  * A session whose run ended since this browser last had it open. A run older than the marks are kept counts as seen:
84
121
  * its mark may be gone, with the server up all that time.