pi-pocket 0.29.0-beta.2 → 0.29.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.
- package/docs/architecture.md +6 -5
- package/docs/extensions/reference/pocket.md +1 -1
- package/docs/extensions/reference/theme-surface.md +4 -2
- package/docs/features.md +9 -7
- package/docs/map.md +3 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/server/app.ts +25 -0
- package/src/server/commands.ts +126 -3
- package/src/server/config.ts +5 -0
- package/src/server/docs.ts +11 -4
- package/src/server/extensions/guard.ts +3 -2
- package/src/server/extensions/memory.ts +36 -14
- package/src/server/extensions/schedules.ts +1 -1
- package/src/server/extensions/subagents.ts +224 -8
- package/src/server/files.ts +7 -2
- package/src/server/hidden.ts +106 -34
- package/src/server/http/conversation-routes.ts +27 -0
- package/src/server/lancet.ts +32 -0
- package/src/server/linked-sessions.ts +3 -1
- package/src/server/memory.ts +163 -32
- package/src/server/pip.ts +3 -1
- package/src/server/room.ts +30 -9
- package/src/server/running.ts +13 -3
- package/src/server/schedules.ts +316 -39
- package/src/server/secrets.ts +689 -0
- package/src/server/when.ts +281 -26
- package/web/composer.js +693 -66
- package/web/pip.js +1 -1
- package/web/quote-box.js +192 -0
- package/web/quote-text.js +444 -5
- package/web/running-board.js +54 -18
- package/web/sheets/appearance.js +21 -0
- package/web/sheets/file.js +14 -1
- package/web/sheets/memory.js +71 -20
- package/web/sheets/menu.js +15 -1
- package/web/sheets/schedules.js +746 -52
- package/web/store.js +33 -21
- package/web/style.css +822 -90
- package/web/theme-surface.js +2 -0
- package/web/theme.js +2 -0
- package/web/transcript.js +9 -5
- package/web/ui.js +52 -0
- package/web/voice.js +15 -3
package/docs/architecture.md
CHANGED
|
@@ -132,10 +132,11 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
|
|
|
132
132
|
|
|
133
133
|
## Memory
|
|
134
134
|
|
|
135
|
-
Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project or for
|
|
135
|
+
Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project, for everywhere, or for one session. A project is keyed by the real path of its git common folder (`git rev-parse --git-common-dir`), so a repository and all its worktrees share lessons; outside a repository, by the folder itself. `Memory` (`memory.ts`) works out a folder's project (kept a minute per folder) and keeps the rules:
|
|
136
136
|
|
|
137
|
-
- The memory extension's section renders, before each request, the lessons in force for the conversation's folder: its project's and
|
|
138
|
-
-
|
|
137
|
+
- The memory extension's section renders, before each request, the lessons in force for the conversation's folder: its project's, everywhere's, and its session's own, not pending, oldest first. It reads committed state only, so it renders the same text until a lesson changes. PiP has no project: it gets everywhere's and its own.
|
|
138
|
+
- **Session lessons** (since 0.29.0) are stored as a project whose key no folder has: `project` is `pocket-session:<root id>` (`sessionKey`, `sessionOf`, `scopeOf`), and `projectName` is `session “<title>”`. A project key is always an absolute path or a `scheme://` workspace address, so it never matches one. A server from before them (0.29.0-beta.3 and older) reads such a lesson as some other project's: it puts it in no prompt and no session's sheet, never everywhere, and lists one that waits in the owner's pending queue under that name (checked by opening a data folder written by this code with beta 3's). The key is the session's root (`rootOf`), so its subagents share them; a linked session is a root of its own. Because the lessons are in the prompt's section, not the transcript, they last through compaction and restarts. Each session keeps `MAX_SESSION_LESSONS` (20) approved ones in a room of its own, and a person's waiting session lessons count against `MAX_PENDING` in that session only, and against `MAX_PENDING_SESSIONS` (40) in all sessions. A fork (`commands.ts` `#fork`, in the fork's own commit) copies the parent's session lessons in force as its own, with new ids and no call key; pending ones and proposals stay with the parent. Pi Pocket never deletes a session, only archives it: an archived session keeps its lessons, which apply nowhere else. The memory extension offers `scope: "session"` only when the running `Memory` lists it in `scopes`, so a newer extension on an older server refuses it rather than saving a lesson for everywhere.
|
|
139
|
+
- Pi proposes, the owner approves. Every lesson Pi saves, and every one a person who is not the owner saves, is pending, and no prompt has it until the owner approves it: what Pi read anywhere in its context could have talked it into one. Pi's (or a guest's) new text for a lesson in force, and Pi's forgetting one, are a `proposal` on the lesson, which stays as it was until the owner approves or discards it. The tool's result names the lesson (`details.lesson`), so the transcript offers Approve and Discard under the call. An approval names what it saw (`POST …/memory/:id/approve` with `{ text }` or `{ forget: true }`); when what waits differs, `change` answers 409, so text or a proposal swapped after the owner looked is not approved with it. Pi proposing the text in force withdraws its own waiting proposal. Pending lessons do not count toward a project's, everywhere's, or a session's cap; approving one does. Only the owner, or whoever saved a lesson, changes or removes it, Pi included (as the person it works for).
|
|
139
140
|
- Pi's adds carry the tool call's key, so a replayed call finds its lesson. A subagent's lesson comes from its session (`rootOf`).
|
|
140
141
|
- Every write adds an activity line to the session's chat in the same commit. `#committed` tells `Memory` when the document changed; it sends tabs a `memory` event, and the Memory sheet and menu fetch the lessons again (`GET /api/c/:id/memory`).
|
|
141
142
|
|
|
@@ -302,11 +303,11 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
|
|
|
302
303
|
|
|
303
304
|
**PiP chat (`pip.js`, `pip-attachments.js`).** The panel's uploads, submits, image thumbnails, and Markdown image paths use its own conversation ID, never the session behind it. The browser-only attachment draft outlives panel mounts, scopes itself to account and PiP ID, and holds upload identities and submit tokens so late callbacks cannot restore removed files or clear newer drafts. Unknown authentication or conversation IDs during reconnect are not a scope change. Files survive closing and reopening the panel, not a page reload; text keeps its existing local-storage draft. The normal upload and submit endpoints retain their size, file-access, and image-capability checks; PiP does not choose another model for an attachment. Opening the pending-memory sheet uses the private PiP ID even on Home. Panel cleanup restores focus only if it is still in the outgoing panel or on the body, not when a destination sheet already took it.
|
|
304
305
|
|
|
305
|
-
**A session's send on its way (`composer.js`).** The box keeps no send of its own: `onTheWay` holds each conversation's message, `!` command, or command on its way (`beginSend`, `endSend`), so a box shown again meanwhile holds it read only and cannot send it twice. Its words and files stay in the draft until it went, and meanwhile its words are all the draft holds: what comes for the box waits until it ended: an insert in the store, and a queued message taken back (Edit) in the person's storage (`keepBack`), which a box of its conversation takes once no send is on its way there, also after a reload or a move. One taken back during a send waits until that send ended (`endSend`), or, in another tab or after a reload, until its request id is gone: before, the box's words may go again with that id. Once it went, the draft empties (unless another tab wrote it since), and a file added meanwhile stays. A failure leaves them
|
|
306
|
+
**A session's send on its way (`composer.js`).** The box keeps no send of its own: `onTheWay` holds each conversation's message, `!` command, or command on its way (`beginSend`, `endSend`), so a box shown again meanwhile holds it read only and cannot send it twice. Its words and files stay in the draft until it went, and meanwhile its words are all the draft holds: what comes for the box waits until it ended: an insert in the store, and a queued message taken back (Edit) in the person's storage (`keepBack`), which a box of its conversation takes once no send is on its way there, also after a reload or a move. One taken back during a send waits until that send ended (`endSend`), or, in another tab or after a reload, until its request id is gone: before, the box's words may go again with that id. Once it went, the draft empties (unless another tab wrote it since), and a file added meanwhile stays. A failure leaves them; the box's quotes are in its words (or its strips, in Separate), so they stay too. Every send of the box that the server runs (a message or template, a `!` command, an extension's command) has one request id for its conversation and exact message (`requestFor`: its kind, words, and files; Reply's quotes are part of the words, or of the strips that go first), kept with the draft in the person's storage until it went. Sent again before, from a box shown again or after a reload (no answer came, or one that does not say: a 5xx, or one that `answered` in `store.js` cannot read), it reuses that id, and the server gives back the first submission, task, or run (`Commands.submit`, `ShellRequestsDoc`, `CommandRequestsDoc`). A 4xx refusal keeps the id: the server stored nothing for it, and a first send that went may be behind it. A 2xx (also an extension's command that ran and failed) ends the id, and so does a change of the words in the box (`edit`): the same words then are a new request, and run again. Sign-out clears it with the draft.
|
|
306
307
|
|
|
307
308
|
**Shared notes drafts (`notes-drafts.js`, `chat.js`).** `personStorage` keeps `{ text, base }` per person and conversation; sign-out clears it and an account change clears the helper's memory. The original revision survives reload, so newer shared saves still require **Use theirs** or **Keep mine**. Blocked or full storage keeps edits in memory with a reload warning. Save, Cancel, and **Use theirs** remove the saved edit or its last stored value after a failed write, never a newer draft from another tab. Failed cleanup shows a warning. A pending save locks its original draft across panel mounts; the textarea stays focused and read-only.
|
|
308
309
|
|
|
309
|
-
**PiP's place (`pip.js`, Appearance → PiP).** Floating, `openPip` sets `pipOpen` (and `OPEN_KEY`, and tells the server, which sends `pipview` only while it is on), as before. With `pip: "board"`, PiP is its own conversation opened as a session is: `openPip` gets PiP's id (asking the server once, with no `pipview`, when the tab does not know it) and calls `navigate`, clearing the drawer, page, and launcher, and the sheet unless the setting's own sheet moved it. `pipBoard()` is true while the route is PiP's conversation (`showsPip`, as its view says, or PiP's id once known) with no board or page over it; `pipShown()` (either place) drives the rail button, the unread mark, and `togglePip`. The session's top bar gets a fixed `core:pip-close` × while `pipBoard()`. The route it was opened over is kept on PiP's history entry (`navigate(id, { over })` → `pushRoute`, read back into `store.state.over` on each route), so it holds through back and forward and a reload; `closePip` goes back there with `navigate(id, { back: true })` (`popRoute`, `back.js`), which steps history back past PiP's entry, so none is left for back to open again, and keeps a sheet still open (Appearance) over that route; or home when the entry has none (the address typed). While a route is `over` a session, `openId()` (not `conversationId`) is the session the list, the folded rail, the tabs, peek tiles, the launcher, and Alt+arrows treat as open, so the one under PiP stays marked, as under Running now. PiP has one message box: on its board the session's place draws PiP's own `Composer` (`PipBoardBox`, with the messages that wait over it and the status line under it) instead of the session composer, on the same `composerDraft` (words, files, the send on its way), so a move changes nothing in it. Text for PiP (`openPip(text)`) goes into it as `pipDraft`, in either place; on the board it also takes what `insertIntoComposer` puts in that place's box (`takeInsert`, which gives each insert to one box). PiP's quote (Ask PiP, or Reply on its board) is one, `pipQuote`, over that box, while the session's own Reply
|
|
310
|
+
**PiP's place (`pip.js`, Appearance → PiP).** Floating, `openPip` sets `pipOpen` (and `OPEN_KEY`, and tells the server, which sends `pipview` only while it is on), as before. With `pip: "board"`, PiP is its own conversation opened as a session is: `openPip` gets PiP's id (asking the server once, with no `pipview`, when the tab does not know it) and calls `navigate`, clearing the drawer, page, and launcher, and the sheet unless the setting's own sheet moved it. `pipBoard()` is true while the route is PiP's conversation (`showsPip`, as its view says, or PiP's id once known) with no board or page over it; `pipShown()` (either place) drives the rail button, the unread mark, and `togglePip`. The session's top bar gets a fixed `core:pip-close` × while `pipBoard()`. The route it was opened over is kept on PiP's history entry (`navigate(id, { over })` → `pushRoute`, read back into `store.state.over` on each route), so it holds through back and forward and a reload; `closePip` goes back there with `navigate(id, { back: true })` (`popRoute`, `back.js`), which steps history back past PiP's entry, so none is left for back to open again, and keeps a sheet still open (Appearance) over that route; or home when the entry has none (the address typed). While a route is `over` a session, `openId()` (not `conversationId`) is the session the list, the folded rail, the tabs, peek tiles, the launcher, and Alt+arrows treat as open, so the one under PiP stays marked, as under Running now. PiP has one message box: on its board the session's place draws PiP's own `Composer` (`PipBoardBox`, with the messages that wait over it and the status line under it) instead of the session composer, on the same `composerDraft` (words, files, the send on its way), so a move changes nothing in it. Text for PiP (`openPip(text)`) goes into it as `pipDraft`, in either place; on the board it also takes what `insertIntoComposer` puts in that place's box (`takeInsert`, which gives each insert to one box). PiP's quote (Ask PiP, or Reply on its board) is one, `pipQuote`, over that box, while the session's own Reply quotes (`replyQuotes`, in order) wait for the session composer, under the board too, as long as `openId()` stays that session; the composer takes them all in once no send is on its way (`dropQuote`, by identity), into its text or its strips. PiP's send takes its quote out of its box as it starts and gives it back if it fails and nothing took its place (`giveBackQuote`), so no box offers a quote on its way. A board open waits for the tab to know its person and connection, and opens nothing if the person went elsewhere or chose Floating meanwhile. Another board, page, or session simply takes the route. A store subscriber moves PiP when the setting changes, after the change reaches every listener and only if the setting is still the same: to the board it closes the floating panel and navigates; to the corner it navigates away first, then opens the panel; `PipHost` draws nothing while `pipBoard()`, so never both places. A floating `pipOpen` kept across a reload is dropped when the setting says Board. PiP turned off in Extensions closes the board, as it closes the panel; PiP's conversation keeps no panel layout (`followLayout`, `store.js`), so it opens again as PiP, not under a panel left open. The panel no longer has an **Open as a conversation** button: Board is that view. Its **Pending memories** strip (`PendingMemories`, `sheets/memory.js`) shows in both places, only while something waits (or a restart is needed to list them): PiP's box draws it, in both places.
|
|
310
311
|
|
|
311
312
|
**PiP resize (`pip-window.js`).** Resize uses pointer capture on the same edge/corner zones for mouse and touch, at widths of 768px and above, for the floating window only. The preferred size is local to the account/browser; CSS clamps it to the viewport without overwriting it.
|
|
312
313
|
|
|
@@ -1255,7 +1255,7 @@ What shows comes in layers, the last one wins: each item's default place, then t
|
|
|
1255
1255
|
| Slot | Ids, in their default order | Fixed | Modules' items go |
|
|
1256
1256
|
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------- |
|
|
1257
1257
|
| `topbar` | `core:subagents`, `core:changes`, `core:peeks`, `core:files`, `core:browser`, `core:artifacts`, `core:people`, `core:menu` | `core:menu`, last | after `core:browser` |
|
|
1258
|
-
| `status` | `core:connection`, `core:here`, `core:speed`, `core:context`, `core:cache`, `core:spend`, `core:background`, `core:guard`
|
|
1258
|
+
| `status` | `core:connection`, `core:schedules`, `core:here`, `core:speed`, `core:context`, `core:cache`, `core:spend`, `core:background`, `core:guard` | `core:connection`, `core:guard` | after `core:cache` |
|
|
1259
1259
|
| `places` | `core:files`, `core:changes`, `core:browser`, `core:artifacts`, `core:chat`, `core:find`, `core:launcher` (touch screens), `core:branch`, `core:pip`, `core:peeks` | none | last: a tile for each panel |
|
|
1260
1260
|
| `composer` | `core:places`, `core:attach`, `core:model`, `core:plan` | none (Send, Stop, the mic, and Steer, Queue and Interrupt are not in the slot) | after `core:plan` |
|
|
1261
1261
|
| `reply` | `core:time`, `core:react`, `core:discuss`, `core:pin`, `core:copy`, `core:more` | `core:more`, last | before `core:more` |
|
|
@@ -151,7 +151,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
151
151
|
| `presented-more` | The button beside that line that opens its message sheet (since 0.28.0) |
|
|
152
152
|
| `presented-choice` | In its message sheet: Show, Fold, and Hide for every input of its kind (since 0.28.0) |
|
|
153
153
|
| `reply` | Pi's answer |
|
|
154
|
-
| `reply-quote` |
|
|
154
|
+
| `reply-quote` | A passage a message quotes, where it was written in it (since 0.27.0) |
|
|
155
155
|
| `reply-actions` | The row under an answer: react, discuss, pin, copy |
|
|
156
156
|
| `activity`, `activity-head`, `activity-chevron` | A group of what Pi did, its head (what it did, how long), and the chevron that opens it |
|
|
157
157
|
| `timeline` | The open group's steps, on a rule |
|
|
@@ -173,7 +173,9 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
173
173
|
| `dock` | What sits above the message box: the queue and the bars |
|
|
174
174
|
| `subagents-bar` | The subagents' bar |
|
|
175
175
|
| `message-box` | The box you type in, with its buttons |
|
|
176
|
-
| `quote-strip` | Above
|
|
176
|
+
| `quote-strip` | Above a box: a passage quoted (Ask PiP's, or Reply's in Separate), with a button to remove it (since 0.27.0) |
|
|
177
|
+
| `quote-count` | Above the session's box: how many quotes Reply put in it, with Clear quotes (since 0.29.0) |
|
|
178
|
+
| `quote-block` | In the session's box: one quote Reply put in it, as drawn under the text. Colours and fills only (since 0.29.0) |
|
|
177
179
|
| `composer-tools` | The row of buttons in it |
|
|
178
180
|
| `composer-button` | Each of its own buttons: Places, Attach, Plan, the mic, Steer and Queue, Stop, and an extension's button (since 0.19.0) |
|
|
179
181
|
| `plan-chip`, `mode-switch`, `stop-button` | Plan, Steer and Queue, and Stop, each also a `composer-button` |
|
package/docs/features.md
CHANGED
|
@@ -13,16 +13,16 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
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) and is sent first, while the queued messages stay in order with their senders and modes; **Stop** stops the run and holds the queued messages (since 0.28.1): a bar above the message box says how many, **Send** sends them in their order as the people who wrote them, and **Show** lists them, each with **Edit** for its sender and a × to withdraw it (anyone their own, the driver anyone’s), while subagents’ reports, and PiP’s queue, are still withdrawn; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; Ctrl/⌘+Enter sends a message the other way while Pi works (queued when Steer is chosen, steering when Queue is) and leaves the choice as it was, and on Interrupt or with nothing running it sends as Enter does (since 0.28.0); 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), with these buttons in a quiet row at its right (since 0.28.0): 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. A session you go back to shows at once where you were in it, as this browser tab kept it, and what came while you were away rises in: at the bottom the conversation glides up to it, and scrolled up the row you read stays where it is. With Appearance's **Wait for updates** (off by default), a session that changed while you were away shows only once its updates have come (or after 2.5 seconds). Scrolled up, a round button above the end of the message box goes back down to the newest message.
|
|
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) and is sent first (on a narrow message box, such as a phone's, they are one button with the chosen mode that opens a menu of the three, so the model chip stays in view; since 0.29.0), while the queued messages stay in order with their senders and modes; **Stop** stops the run and holds the queued messages (since 0.28.1): a bar above the message box says how many, **Send** sends them in their order as the people who wrote them, and **Show** lists them, each with **Edit** for its sender and a × to withdraw it (anyone their own, the driver anyone’s), while subagents’ reports, and PiP’s queue, are still withdrawn; Interrupt goes back to Steer after one use, or when Pi stops before it was used, while Steer and Queue stay as chosen; Ctrl/⌘+Enter sends a message the other way while Pi works (queued when Steer is chosen, steering when Queue is) and leaves the choice as it was, and on Interrupt or with nothing running it sends as Enter does (since 0.28.0); 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), with these buttons in a quiet row at its right (since 0.28.0): 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. A session you go back to shows at once where you were in it, as this browser tab kept it, and what came while you were away rises in: at the bottom the conversation glides up to it, and scrolled up the row you read stays where it is. With Appearance's **Wait for updates** (off by default), a session that changed while you were away shows only once its updates have come (or after 2.5 seconds). Scrolled up, a round button above the end of the message box goes back down to the newest message.
|
|
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
|
|
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 the message box as a Markdown quote (up to 1,500 characters), right after what is there, with the caret on the line right under it, ready to type; Reply again stacks another quote, so one message can answer several passages, each with its own words. In the box each quote is one piece: drawn as one block apart from your words, its empty lines in it (Appearance → **Quotes in the message box**: **Fade**, the default, a tint that fades out to the right; **Tint**, a soft block; **Ghost**, faded words only), with a × on its first line, and a "2 quotes · Clear quotes" line above the box. Typing inside a quote writes on the line under it instead; Backspace on the line under a quote turns it red, and a second Backspace removes it; a reload keeps the quotes and their pieces. The box knows each quote by where it is, so one typed by hand ("> …"), even with the same words, is plain text; undo after removing a quote brings it back as one. The message goes to Pi as written, with a blank line set around each quote so Markdown keeps it apart; a paste placeholder or an `@file` inside a quote stays the passage's words (nothing expands or goes along). It shows in the conversation with each quote as a quote block where it was written. **Separate**, the fourth choice there, keeps quotes out of your words instead: each Reply adds a strip over the box (× on each, **Clear quotes** with more than one, and a reload keeps them), and the next message goes with every strip's passage quoted first, in order, then your words. With PiP on, PiP's orb (**Ask PiP**) sits beside **Reply** in the same pill: it opens PiP with the passage in a quote strip over its box, ready to type (as a board, Appearance → PiP → Board, the quote strip of the board's message box); your message goes with the passage quoted first, and shows with it as a quote block. PiP also gets, unseen by people, which session the passage came from (its number, title, and folder: `about` on the submit request, a `<pocket-context>` part after the message that no view or resend shows), so it can read that session for more. In Appearance, **Reply to a passage** and **Ask PiP about a passage** (both on by default) each turn their own button off in that browser; with both off, nothing shows.
|
|
19
19
|
- **Forks.** Tap Pi's reply → More → **Fork from here**: a new session with everything up to that reply, which then goes its own way. Tap one of your messages to **edit it and send it again**, or send any message again, to the same model or another one (a retry). Each makes a new session that forks just before the message; the original stays as it is. A fork gets its own chat (with the pins of what it inherited), a link back to where it came from, and optionally a git worktree of its own.
|
|
20
20
|
- **A new context.** Menu → **New context** (or `/reset [note]`): Pi starts fresh and no longer sees the messages so far, while everyone still does. An optional handoff note carries over what matters.
|
|
21
21
|
- **Instructions for Pi.** Menu → **Instructions for Pi** (or `/instructions …`): ground rules Pi gets with every message in this session, such as "use pnpm, not npm". Everyone in the session can see them.
|
|
22
|
-
- **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for
|
|
22
|
+
- **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project, for everywhere, or for this session alone: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), everywhere's reach every session and PiP, and a session's own reach that session and its subagents for the rest of its life, through compaction and restarts, and no other session (since 0.29.0; Pi uses `scope: "session"` for something to keep only here). A fork starts with its session's lessons in force, as its own; what waits for approval stays with the session it was saved in. Archiving a session keeps its lessons for when it comes back. In PiP the same part is **PiP only**: lessons for PiP that no session gets. Menu → **Memory** (its hint says how many apply here, everywhere, and in this session) opens as a wide sheet; a switch at its top, **This project**, **Everywhere**, or **This session**, each with how many it holds and how many of them wait for approval, picks which it lists and where a lesson you type in goes. Each shows who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons, everywhere 30, and each session 20 of its own, each in a room of its own; past that, forget one first. A person's session lessons that wait count in that session only (20 at most there, and 40 in all sessions), not toward the 20 waiting elsewhere. A server from before 0.29.0 uses a session's lessons nowhere (it shows one that waits in the owner's queue, for "session “…”"), never as lessons for everywhere. Changes show as lines in the chat. Turn it off in Extensions.
|
|
23
23
|
- **A lean prompt.** A new session gets only the tools most conversations use. `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools wait, and so do their prompt sections; the prompt lists them with a line each, and Pi loads one with `tool_search` when a task needs it. On a model whose provider takes tool changes in the messages (Claude 4.8 and 5, and later), the tool joins the list and stays for the conversation; on any other, Pi calls it from a `codemode` script, so the tool list and the prompt cache never change. Long guides, such as the design guide and the page-to-app messages of artifacts, are files that Pi reads when it needs them. Turn the **Tool search** module off in Menu → Extensions to offer every tool every time. A test keeps Pi Pocket's own part of a plain session's prompt under 14,000 characters (about 5,000 tokens: schemas and this prose run at about 2.75 characters a token), so it does not grow by accident.
|
|
24
24
|
- **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
|
|
25
|
-
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages
|
|
25
|
+
- **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or `/schedule every 30m between 9:00 and 17:00 on weekdays check the queue`, or Menu → **Scheduled messages** (also the violet pill on the left of the status line, which shows how many are set and, hovered, counts down to the next): Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Since 0.29.0 a repeat every so many minutes can run only inside a time window: `between 9:00 and 17:00`, and optionally `on weekdays`, `on weekends`, `on mon,wed`, or `on day`. It runs at the window's start on each day the window opens, then every so many minutes while before the end, which is excluded (9:00, 9:30 … 16:30); a repeat longer than the window runs once, at its start. An end at or before the start ends on the next day, so `between 22:00 and 6:00 on fri` runs from Friday night to Saturday morning; the start and the end cannot be the same. The start and the end are wall-clock times, and the runs between them are real minutes apart: on a night the clocks change, a window that holds the change is an hour shorter or longer, with a run less or more. A server older than 0.29.0 ignores the window and runs such a repeat all day. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. A repeat whose last message still waits in the session's queue (Pi is at work, or a run failed and holds it) sends no other at its next time: the time is skipped, a line in the chat counts the skips, and the Schedules sheet, the Running now board, and Pi's `schedule` tool list show how many there were (since 0.28.1). Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. The **Schedules** sheet lists them with a live countdown each; a tap on one opens an editor in its place, to change its message and when it goes out (**Once** on a date and time, **On days** at a time of day, or **Every** so many minutes, hours, or days, with **Only between** for a window and its days) with a preview of the next time, or to delete it, and **New schedule** opens the same editor, beside quick add in words. A change goes out as the work of whoever made it; a new time of day is on their device's clock, and other changes keep the time zone it was set in. **Pause** beside each schedule (and in its editor, and on Running now) stops it at once, without asking Pi: it sends nothing and stays in the list, dashed, until someone taps **Resume**. A repeat then goes on from its next time still to come, and a one-time message whose time passed while paused goes out at once. An edit keeps it paused. The pill and the countdowns count only schedules that go out; a session whose schedules are all paused shows "N paused". Pi's `schedule` tool lists a paused one as paused, and only a person resumes it. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
|
|
26
26
|
- **Done when.** `/until npm test`: after each of Pi's answers, the check runs in the session's folder; while it fails, Pi gets the end of its output and keeps going, for five checks at most. A bar above the message box shows how it stands. With Lancet Guard on, the check must be a command the guard allows outright. In plan mode the check waits until the plan is approved, and past a spend limit Pi stops going on. A check cut off by a server restart is not run again, as it may have done part of its work: Pi hears so, and its next answer is checked.
|
|
27
27
|
- **Mention files.** Type `@` in the message box to pick a file or folder from the session's folder: `@` alone lists its top, `@src/` a folder's own files, and anything else matches across the whole folder (`@srvapp` finds `src/server/app.ts`). Tab or Enter (or a tap) puts the path in, and a folder opens to its files. Pi gets the message as written, `@src/server/app.ts` and all, and reads what it names; or tap **Send them along** above the box to send the files' contents with the message, as Claude Code does (text files up to 100 KB each, images as images when the model takes them). The list is git's in a repository (so ignored files stay out), and a walk that skips hidden and dependency folders elsewhere; your browser fetches it once and matches as you type, so suggestions never wait on the network.
|
|
28
28
|
- **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.
|
|
@@ -34,7 +34,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
34
34
|
- **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 per person across sessions, with duplicates removed only within your session. Signing out clears this history. What 0.27 kept moves to its person the first time 0.28 opens signed in as them (a sign-out before that clears it); older unscoped history is discarded.
|
|
35
35
|
- **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 Serve, or on this device. A blocked microphone, silence, a missing microphone, or no network says so in a notice.
|
|
36
36
|
- **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.
|
|
37
|
-
- **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.
|
|
37
|
+
- **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. **Download** saves a regular file (binary files, images, and text) to your device, even when there is no preview. Folders and special files have no download control. 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.
|
|
38
38
|
- **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. Each session remembers which panel it showed (Files and its tab, Browser, People, or an extension's, such as Design): going back to it, reloading, or opening it in another tab of the same device shows that panel again; PiP's floating panel stays as it is across sessions, and PiP as a board opens with no panel beside it. 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.
|
|
39
39
|
- **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.
|
|
40
40
|
- **Stop with Esc.** Esc twice stops Pi while it works.
|
|
@@ -42,7 +42,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
42
42
|
- **Prompt templates.** Pi's prompt templates (`~/.pi/agent/prompts/*.md`, the project's `.pi/prompts/*.md`, and the paths in Pi's settings) show up as slash commands: `/review src/auth.ts` sends the `review` template with its arguments filled in. Pi's skills do too, as `/skill:name what to do`: Pi gets the skill's instructions with the request. The `skills` setting of Pi's `settings.json` works as in Pi: `-path` and `!pattern` leave skills out, `+path` puts one back, and a relative entry starts from Pi's folder (since 0.28.0).
|
|
43
43
|
- **Project trust.** A project's own skills (`.agents/skills`) load only in a project Pi trusts, as in Pi's terminal app. When a session's project has some and nobody has decided, the owner is asked above the message box: **Review** says what trusting it loads, here and in Pi's terminal app, and offers to trust the folder, the folder above it, or not; **Don't trust** answers at once, and **Not now** (×) puts the question off in that tab. `/trust` or Menu → **Project trust** changes the answer later. Answers are saved where Pi's terminal app keeps its own, so a project trusted there is trusted here too. Pi has the skills from its next message. A project's `.pi/skills` load until it is told "Don't trust", then stay out too (Pi's terminal app asks before loading them at all); the sheet lists both kinds and says what each answer does to them. Only the owner is asked.
|
|
44
44
|
- **Changes.** The Files tile's **Changes** tab (or the count of lines added and removed in the top bar, `/changes`, or Menu → **Changes**): every uncommitted change in the session's folder as one review, file by file. Summary counts include new text files before and after staging (an untracked one over 2 MB shows no count); binary files have no line counts. Each file has a header that stays in view while you scroll its lines, with a fold chevron, what kind of change it is (M, A, D, or R in a small tile), its counts, and a **Viewed** checkbox button that folds the file; viewed files stay folded on this device until their diff changes again, and the summary says how many you have seen. Diffs show side by side when there is room and unified when not (Auto, Unified, or Split, as you pick, with long lines wrapped or not), with line numbers on both sides, syntax colors, and the words that changed within a line marked; a changed line is paired with its new version by likeness, not just position. The unchanged lines between changes are a tap away, a few at a time or all at once, read from the file as it is now (and only when it still matches the diff). Tap a line number to open the file there. A tree of the changed files (beside the diffs when wide, behind **Files** when narrow) jumps to one, a filter narrows them, and **π only** keeps the files Pi edited. Diffs load as they near the screen, a few at a time, and the review looks again a moment after Pi moves on. Keys: `j`/`k` the next or previous file, `n`/`p` the next or previous change, `v` viewed, `s` the layout, `w` wrapping. From a file's header, **↺** (tapped twice) puts it back as the last commit has it, or deletes it if it is new; Pi is told, and it waits while Pi works. A file with a merge conflict, or a rename, is left to git. Outside a repository it lists Pi's edits alone. Someone invited to one session sees the changes in its folder only.
|
|
45
|
-
- **Running now.** Menu → **Running now** (also on the sidebar's rail and in the launcher) shows, in the conversation's place as the subagents board does, everything at work and everything scheduled in the sessions you can see. A **Coming up** timeline at the top has a lane per session: its scheduled messages as marks at their times (a diamond for a repeat, a ring for one that goes out once, amber while a spend limit or a lost right to steer holds it), a bar for how long the session has been at work, and a line at now; 24h, 3d, or 7d, it scrolls sideways, hovering a mark says what and when, and hovering (or tapping) a session's bar shows the last message sent to it, which its run works on. Under it, filter pills (All, Running, Scheduled, Needs approval, Held) and a search, then one row per session: the session, with its folder, Busy, calls to approve, and **Stop** on one line under its name; **Now**, what is at work there from Pi Durable's task graph (answers, tool calls, subagents, compactions, background tasks, shell and extension commands, PiP's follows and watches) with how long each has been at it, Stop where it can stop, and the session's model and spend; and **Schedule**, its scheduled messages with the next time, the repeat in words, and how many times each went out. A schedule picked there or on the timeline opens at the side on a wide screen, under the rows on a narrower one, and in a bar at the bottom on a phone: its message, repeat, next time in its own zone, who set it up, its next five times, **Open session**, and **Cancel
|
|
45
|
+
- **Running now.** Menu → **Running now** (also on the sidebar's rail and in the launcher) shows, in the conversation's place as the subagents board does, everything at work and everything scheduled in the sessions you can see. A **Coming up** timeline at the top has a lane per session: its scheduled messages as marks at their times (a diamond for a repeat, a ring for one that goes out once, amber while a spend limit or a lost right to steer holds it), a bar for how long the session has been at work, and a line at now; 24h, 3d, or 7d, it scrolls sideways, hovering a mark says what and when, and hovering (or tapping) a session's bar shows the last message sent to it, which its run works on. Under it, filter pills (All, Running, Scheduled, Needs approval, Held, Paused) and a search, then one row per session: the session, with its folder, Busy, calls to approve, and **Stop** on one line under its name; **Now**, what is at work there from Pi Durable's task graph (answers, tool calls, subagents, compactions, background tasks, shell and extension commands, PiP's follows and watches) with how long each has been at it, Stop where it can stop, and the session's model and spend; and **Schedule**, its scheduled messages with the next time, the repeat in words, and how many times each went out. A schedule picked there or on the timeline opens at the side on a wide screen, under the rows on a narrower one, and in a bar at the bottom on a phone: its message, repeat, next time in its own zone, who set it up, its next five times, **Open session**, **Pause** or **Resume**, and **Cancel** (a paused one has no marks on the timeline); **Needs you** (calls waiting for approval, held schedules) and **Next up** stay beside it. Esc, back, or × closes it; it asks the server again every 2 seconds while it shows.
|
|
46
46
|
- **Watch a pull request.** Menu → **Watch pull request**, `/watch` (or `/watch 123`, `/watch <PR address>`), or Pi's `watch_pr` tool, which it can start after opening a PR (Pi only for its folder's repository, by number; a person for any): until the PR is merged or closed, Pi Pocket looks at it on GitHub every few minutes with the `gh` command signed in on the server, and tells Pi in the session what needs doing, as a message sent through the watch for whoever set it up: checks that failed on its last commit (once all of them finished, with the end of each GitHub Actions log), conflicts with its base branch, and new comments and reviews. Only comments from the repository's owner, and from organization members and collaborators whom GitHub says can write to it, count, and bots' reviews (a member may only read, a collaborator only triage: `gh` asks GitHub, at most every ten minutes for each person, and GitHub tells only an account that can push there, so on a PR where yours cannot, such as a fork's PR to someone else's repository, only the owner's count, and the watch says so); your own account's (which Pi posts as) only when they mention @pi in their own words (not in a quote or code), so Pi never answers itself. Comments keep their lines (a suggested change is code), 30 at most in a message (read newest first, so a burst never hides the new ones); each is told once, and what does not fit in one message comes in the next; nothing goes while Pi is busy there or, with take turns on, while someone else drives (the bar says it waits, and nothing counts as failed); and a watch sends 10 messages at most. While Triggers is off it asks GitHub nothing. A bar above the message box shows the PR, its checks, and how many messages went, with **Stop**. It ends, with a line in the chat and a notification, when the PR is merged or closed, when there is more to tell than it may send, after two weeks with nothing new, or after an hour of looks that failed (the bar says why). Logs reach Pi fenced as data, which nothing in them can end early, and titles, check names, and branches come on one line, quoted, as data too. It needs `gh` installed and signed in (`gh auth login`) on the server, on GitHub Enterprise hosts too: a host other than github.com is used only when `gh` is signed in there (`gh auth login --hostname <host>`; a token only in `GH_ENTERPRISE_TOKEN` does not count), for Pi, PiP, and people alike, and Pi names a PR by address only on github.com or its folder's own host.
|
|
47
47
|
- **Watch a repository.** Tell PiP in plain words, such as "watch acme/api: when CI fails on main, fix it and tell me" or "when I open an issue labelled pi in acme/web, work on it": it sets up a watch that looks at the repository on GitHub every few minutes with `gh` (no public address needed, unlike a webhook), and what is new there (issues and pull requests opened, CI failing on a branch, releases, someone writing @pi, as a word of its own, in a comment or an issue) comes to PiP, or to a session you name, with your instructions; PiP then acts on it: it starts a session in the repository (its checkout here, or a clone it makes in the data folder's `repos/`), sends it the task, follows it, and tells you what came of it. A watch can be narrowed to a label, to issues assigned to you, or to a branch's CI (mentions of @pi are not narrowed). CI is the branch's own runs: pushed to it, scheduled, started by hand or through the API, or started by another workflow, in the repository itself, never a pull request's or an issue's (a renamed repository keeps working). Only repositories `gh`'s account can push to can be watched or worked on, and issues and pull requests count only from the repository's owner, and organization members and collaborators whom GitHub says can write to it (and bots' pull requests), unless you turn on **From anyone** on the watch in Menu → Webhooks and watches (PiP cannot); @pi always only from them. PiP works in a checkout of a session you started, or in a clone it makes, which appears only once complete (a clone a restart cut off leaves a `~part-…` folder, removed at the next clone of that repository); a different folder already where the clone goes is reported, never overwritten. While Triggers is off, watches wait and ask GitHub nothing; while PiP is off, a watch to PiP holds what it found, and its note says so. What came from GitHub is fenced as data, each thing is told once, ten in a message and twelve messages an hour at most (the rest come next), and a look that fails is tried again, less often each time, with the reason shown. Menu → **Webhooks and watches** lists the watches, to remove one; or ask PiP ("what are you watching?", "stop watching acme/api"). PiP can also start a PR watch on a session ("see acme/api#12 through"), and Pi's own `watch_pr` takes a PR in another repository it can push to by its address or `owner/name#12`, telling Pi to work in a checkout of it. Part of the **Triggers** extension.
|
|
48
48
|
- **Webhooks.** Menu → **Webhooks and watches**: an address that other services (GitHub, a deploy, a monitor) post to, each post becoming a message to Pi in a session, or to PiP, as the work of whoever made the hook: their instructions first ("When a deploy fails, find out why and fix it"), then what was posted, trimmed of noise such as API addresses, and fenced as data. PiP gets them as folded cards and decides what to do: start a session, message one, or tell you. A GitHub hook is signed: GitHub gets the address and, separately, a secret (its Payload URL and Secret), and a post gets in only with GitHub's signature made with it, so whoever sees the address (the repository's admins do, in its settings) cannot post as the hook. Unless a GitHub hook is made **From anyone**, what people outside the repository wrote does not reach Pi (the repository's people are its owner, and the organization members and collaborators whom GitHub says can write to it, asked through `gh`, which must be signed in to the host and able to push there, or else only the owner counts; bots count on pull requests and what is said on them, never on issues): a post an outsider started (their issue, comment, pull request, review, or discussion) is dropped with a 202 that says so; in a post the repository's people started, the body of anything an outsider wrote in it (the issue under a member's comment, a review thread's comments) is left out, its title kept; a workflow run goes only when a branch of the repository itself started it (a push, a schedule, a manual or API dispatch, or another workflow), so one a pull request (a fork's too), an issue, or a comment started is dropped, and so is one whose head repository GitHub does not show; workflow jobs, check suites, and check runs do not say where their run came from, so they are dropped too, as are a commit status on no branch of the repository (a fork's commit) and a security advisory someone reported; and pushes, releases, and other posts that name no author go as they came. A hook for another service has the secret in its address instead: anyone who has the address can message Pi as the hook's person. **New secret** shuts out the old one, for an address or a secret that got out. Anything else gets 404. A post GitHub sends again goes to Pi once, GitHub's ping gets an answer and is nothing for Pi, a hook takes 30 posts an hour of up to 5 MB each (the server reads eight at a time, two to one hook, each within 15 seconds; past that, 503 with Retry-After), a hook to PiP answers 503 while PiP is turned off, and a post that cannot go now (someone else drives, a spend limit) gets a 409 that says no more. Services must be able to reach the server: through a tunnel, a public address works for GitHub. People who can steer make hooks for the sessions they can reach; each sees their own, the owner every one. Choose **Edit prompt** to change a hook's instructions, then **Save** or **Cancel**. Only the hook's creator or the server owner can save changes, and they need steering rights. You can enter up to 2000 characters. Leave the instructions empty to ask Pi to summarize what happened and whether anything needs doing. Saved changes apply to later posts. The address, secret, destination, and usage history stay unchanged. The watch and webhooks are the **Triggers** extension: turned off, watches wait and hooks answer 503.
|
|
@@ -89,7 +89,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
89
89
|
- **Ask someone.** Off until the owner turns it on in Menu → **Extensions**. When Pi needs an answer that only someone outside the chat can give (a manager, a client, an expert), **Ask someone** under one of Pi's answers puts a request in the message box, and Pi writes the question with its `ask_someone` tool so that it stands alone: the background, the question, the options, and its recommendation. Nothing goes anywhere yet: the draft waits in **Questions for others** (the status line under the message box, the session menu, or the launcher), where you edit it, **Copy text**, or **Create link** for a day, a week, or a month. The link opens a page with no sign-in, the question, and a box for one answer and an optional name; then it closes. **Copy link**, **Copy message**, and **Share…** (on a phone) send it on; **End link** takes the page down. When the answer comes, a notice says so, and **Give to Pi** puts it in the message box, quoted and marked as someone else's view, for you to send. People who steer every session use it; viewers and people invited to one session do not. Since 0.22.0.
|
|
90
90
|
- **Waiting out provider limits.** When a provider's limit stops a run (a 429 or an overload, a Claude or ChatGPT usage window, a model's cap), Pi Pocket waits for it to clear and goes on by itself, instead of failing. It waits until the reset time the provider gave (or, with none, tries again at growing intervals), then sends one request to find out; if that gets an answer, the sessions waiting on the same limit go on, one at a time. The live line says what Pi waits for, when it tries next, and when the limit resets, with **Retry now**; **Stop** or **Interrupt** end the wait at once, and a message you send meanwhile waits in the queue as always. The session's square is a hollow square with a dot, also on peek tiles, and a subagent's row says it waits. One push goes out when a wait of ten minutes or more begins (Menu → **Notifications** → **Waiting for a limit**). It survives a restart. The owner sets the longest wait (**Wait for a limit** in the Providers sheet: Off, 1, 6, 12, or 24 hours; default 6): what waits is any reset time within that longest wait, load with no time given (an ordinary 429 or an overload), which is tried again at growing intervals for up to 30 minutes, and, since 0.24.0, a plan's usage limit with no time given (OpenAI subscription sharing, Z.ai, MiniMax, OpenCode Go), which is tried again about every 15 minutes, up to the longest wait, counted from the first failure across restarts. What fails the run at once, with the reset in the message where there is one: a window of days (Claude's 7-day window, a Codex window of over 300 minutes), a reset after the longest wait, a usage limit that names a window of days (daily, weekly, monthly), with or without a reset time, and a sign-in that expired or billing. Retry now sends one try each 30 seconds. It never picks another model. Since 0.21.0.
|
|
91
91
|
- **Prompt cache keeper.** On by default; `PI_POCKET_CACHE_KEEPER=off` turns it off. While a run waits on a tool call, Pi Pocket replays the last request that ended in a tool call, with `maxTokens` 1, at 90% of the cache's lifetime or 10 seconds early, whichever is sooner. It does so only when the expected savings are more than the cost. It keeps the 5-minute cache only: no idle warming, no 1h cache, no request with `cacheRetention` none, and no Anthropic thinking set by a token budget. It stops on a real cached request, when the run ends (PiP's too), on an error, at shutdown, or after 30 minutes. A warm request does not wait for a provider limit. Its usage counts in `pi.usage` and in the spend of the person and session that were paying when it started, and spend limits are checked before each warm. A restart drops the warm timers and does not replay warm requests.
|
|
92
|
-
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.28.0 the tool waits for tool search, as `browser` does, so a session that starts none does not pay for its prompt. On a model without tool changes in the messages (all but Claude 4.8 and 5, and later), Pi then starts subagents from a codemode script: the conversation shows each start as a line of that script, without the subagent's card, and the subagents board still opens each one. Pi writes its tasks for subagents in the language of the person it works for, in ASD-STE100 (Simplified Technical English) when it is English (since 0.19.0; in other languages since 0.28.0), and asks for their reports in that language too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. A tool marked `subagents: "always"` by an extension comes along even when that list leaves it out, only while the extension runs there ([Tools](extensions/tools.md#tools-for-every-subagent)). Pi picks no model on its own: until the owner allows models for subagents (**Subagent models** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0).
|
|
92
|
+
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.28.0 the tool waits for tool search, as `browser` does, so a session that starts none does not pay for its prompt. On a model without tool changes in the messages (all but Claude 4.8 and 5, and later), Pi then starts subagents from a codemode script: the conversation shows each start as a line of that script, without the subagent's card, and the subagents board still opens each one. Pi writes its tasks for subagents in the language of the person it works for, in ASD-STE100 (Simplified Technical English) when it is English (since 0.19.0; in other languages since 0.28.0), and asks for their reports in that language too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A message sent to a subagent at work waits in its queue: a steer until its next pause (after its current tool call, or when its run ends), a follow-up until its run ends. The tool tells the main agent so when it sends one, and the tool's `status` lists the start of each message that still waits. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. A tool marked `subagents: "always"` by an extension comes along even when that list leaves it out, only while the extension runs there ([Tools](extensions/tools.md#tools-for-every-subagent)). Pi picks no model on its own: until the owner allows models for subagents (**Subagent models** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0). The tool's `status` lists the subagents at work, each with what it does (a call it runs, or one that waits for a person to allow it) and how long ago its transcript last got a message, a tool call, or a tool result; one at work with nothing new for 30 minutes is called stalled (the owner changes the time in Menu → Extensions, under Subagents). The rest are counted by how they ended, and `status` with `all` lists every one.
|
|
93
93
|
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. Appearance → **PiP → Board** (Floating is the default, per browser) opens PiP's own conversation in the session's place instead, as a session: its top bar with the model, its menu, every step, and a × at the end of the bar, with PiP's own message box at the session's width (the panel's box, without a session box's slash commands, @ mentions, ↑ history, or Steer and Interrupt). The sidebar stays, the rail's orb shows it open, and every way in opens it there; back, its ×, or the orb again gives the place back to what was there (home after a notification's link), and Running now, the subagents board, an extension's page, or another session simply take its place. Changing the setting while PiP shows moves it to the new place. PiP has one message box, so a move changes nothing in it: the same words, files, passage to ask about (Ask PiP), and message on its way show in both places. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. It writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in its person's language: ASD-STE100 (Simplified Technical English), at about 80% adherence, when it is English (since 0.19.0), the same short, plain style in another (since 0.28.0), so a session it worked in reads in your language; it asks each session to answer it in the same language and style, and a session answers a message that came through PiP (scheduled ones too) in the language of that message. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Board** (above) shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back. PiP follows its owner's standing instructions in `pip.md` in the data folder (since 0.28.0, [customizing.md](customizing.md#pips-instructions)).
|
|
94
94
|
- **Resize.** At widths of 768px and above, drag PiP's left edge, top edge, or top-left corner to resize it, with the bottom-right corner fixed. The same zones are finger-sized on touch screens. Its size is remembered for each account in this browser and fits back inside the viewport when it shrinks. Phones use a bottom sheet with rounded top corners and a grabber; the model, context meter, and all three header actions stay available.
|
|
95
95
|
- **Choose PiP's model.** Tap the model chip in PiP's header to use the existing model and thinking picker for PiP alone, from Home or over a session. The chip and picker choices are disabled while PiP works. Saving also checks that PiP is idle. This header path does not change the last picked model for new sessions; as a board, the top bar's model keeps a session's behavior. With no model, the welcome offers **Choose a model to use these suggestions**, which opens the same picker. Suggestions that send at once wait for a model; those that put text in the box stay usable, and choosing a model keeps the suggestions visible.
|
|
@@ -111,6 +111,8 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
111
111
|
- **The queue and the bars above the message box.** Messages waiting for Pi show above the message box, with how many wait whenever not all of them show. With the bars there (the subagents bar, plan mode, a goal, a PR watch, a trust question, who drives), they take less than half of the room they share with the conversation when the bars fit in it, and the conversation keeps the rest, staying where you were reading. The bars always show whole; the queue and the subagents' list take what the bars leave, and scroll. Unfolding the subagents bar gives the list the room, one whole row at least: the queue shows fewer rows, or folds to how many wait. With several bars on a short screen, the plan, goal, watch, and trust bars keep one line each, their words cut short and their buttons whole. When even that does not fit (a phone on its side with every bar up), the stack scrolls, and the conversation keeps a quarter of the room, or a few lines, whichever is less.
|
|
112
112
|
- **Live editing.** No build step. Edit a file in `web/` and every open browser reloads. Edit a file in `src/server/extensions/` and it is reinstalled into the running server (a running tool call finishes on the old code). For core server changes, use **Restart server** in the menu: running work resumes after the restart.
|
|
113
113
|
- **Lancet Guard.** Off by default: the owner turns it on in Menu → **Extensions**. If `specpi-lancet-guard` is installed in Pi and turned on there too, its rules and classifier check every bash, write, and edit call, and each command Pi starts in the background. A "risky" or "unsure" verdict shows Allow/Deny buttons to everyone in the session; the answer survives restarts. The classifier needs the LANCET Nano model, a one-time download of about 109 MB. While it is missing, the guard row in Extensions says so and the owner gets a **Download** button there: it fetches the pinned release from GitHub, checks it against fixed checksums, and installs it where Pi's own `/lancet-guard setup` puts it, so Pi uses it too. Progress shows in every tab, and nothing downloads it without that button. A guard that is on without its model blocks the bash calls its local rules leave open, and the status line shows "guard failed".
|
|
114
|
+
- **Core's secrets stay out of transcripts.** These secrets are hidden in every session, PiP and subagents included, as a value an extension hides with `host.hide` is: each module's `secret: true` settings (and their defaults), the owner token, the private key in `push.json`, and the keys and tokens in Pi's `auth.json`. The secrets Pi Pocket keeps in `pocket.sqlite` are not hidden, and Lancet Guard does not keep Pi from that file: a webhook's secret, an artifact's share token, and a public link's token. Each shows as its label, such as `[secret vault.apiKey]` or `[owner token]`, in commands' output, every tool's result, and people's messages. Core reads them again when the owner saves settings, and before each command and after each tool when a file changed; a value that changes stays hidden as the old one too, while the server runs. A module that is off has its values in `config.json` too: which are secret is unknown then, so none is hidden, except a value hidden while it was on, which stays hidden while the server runs. Hiding is by value: a command that encodes or splits a value on purpose shows it.
|
|
115
|
+
- **Lancet Guard keeps Pi from core's secret files.** While the Lancet Guard module is on, before the guard's own rules, and without its package, its model, its settings file, or `PI_POCKET_GUARD`, it blocks a call that would read `config.json`, `push.json`, or another secret file in the data folder, a drop-in's data folder (`x.*` there), Pi's `.pi/agent/auth.json`, or a `.env` file (`.env`, `.env.local`, `.plane.env`; not `.env.example`): read, edit, an artifact's path, and every tool's `path`, and bash, PowerShell, and background commands that name one. It is a block, not a question. For commands it reads their words: it sees a file named outright, through `~`, `$HOME`, a glob, a relative path in the session's folder or a folder the command names, or a symbolic link that exists. A glob of every file (`*`, `.*`) names no `.env` file (`.env*` does), and a name as text (an `echo` argument, an `--exclude=` value) or a write (`>`, where `cp` copies to) is not a read. It does not see a path a command computes, nor a folder read as a whole (`grep -r` over the data folder): there, hiding is what keeps the values out. Neither is a boundary between Pi and the files of the user Pi Pocket runs as.
|
|
114
116
|
- **Codemode.** On by default, like `"+codemode"` in Pi's `defaultTools`. The `codemode` tool runs JavaScript the agent writes in a QuickJS sandbox with no Node, files, network, or timers; its only capability is calling the agent's other tools as `tools.<name>(args)`. Use it to batch independent calls, chain them, or filter large output before it reaches the model. Each call a script makes goes through the same checks and hooks as a direct call, so Lancet Guard judges it and can ask for approval. `store()` and `load()` keep values per conversation. Its card shows the script, each call it made, and the output. Since 0.28.0, Codemode has a **Mode** setting in Menu → Extensions, for the owner and all sessions, as Pi's `codemode.mode`. **On** (the default) changes nothing. **Only** declares only `codemode`, `tool_search`, `artifact`, `ask`, and `memory` (the cards of the last 3 need a direct call). Pi calls every other tool only from scripts (except a drop-in tool whose `callers` names `"model"`), also the tools of a module that is turned on later, and a tool that a session loaded before. The codemode section of the prompt lists each of these tools with its description and parameters, up to 3,000 tokens (Pi's default `codemode.inlineBudget`), and then the names of the others. Tools that wait for `tool_search` still wait, and a tool that it loads goes through codemode. A subagent that gets one of these tools also gets `codemode`. One limit: a subagent started in On mode with a list of tools without `codemode` cannot call a tool in Only mode, because the setting cannot see each session's list.
|
|
115
117
|
- **Share to Pi.** With Pi Pocket on the home screen (Android), share a link, some text, or a screenshot from any app to Pi Pocket: pick a session or a new one, and it goes into the message box with the files attached, ready to send.
|
|
116
118
|
- **Pi's questions.** Since 0.27.0, Pi's `ask` tool asks the person it works for 1 to 4 questions on a card at its call, when a decision changes the work and only they can make it. Each question has a short tag, the question, and 2 to 4 answers as buttons, each with a line under it; a tap chooses one (or several, where the question allows it), and **Or type your own answer** takes a typed one instead. **Send** is on once each question has an answer; **Decline** answers nothing, and Pi goes on with its best judgment. Pi waits for the answer, for hours if it must, and after a restart the same card asks again. Pi gets one line per question (`Storage: Local storage`), and the call shows each question and its answer to everyone in the session. The card shows, and notifies, as an extension's question does (below). It runs in plan mode, the guard never asks about it, and subagents do not have it. The **Ask** module, on by default (Menu → Extensions).
|
package/docs/map.md
CHANGED
|
@@ -90,6 +90,7 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
90
90
|
| `share.ts` | Artifact shares (`/api/c/:id/shares`): publishing one artifact version, or the newest, to anyone with a link, ending it, and what a published token shows now (needs no sign-in); only people who see every session publish or end one A published bundle's files are served by `http/artifact-assets.ts`. |
|
|
91
91
|
| `public-links.ts` | Extension modules' public links (`web.links`): made, listed, and ended for their own module only, each closing at its time or after its uses; a use counts before the page handler runs and comes back when the page refuses the post (needs no sign-in) |
|
|
92
92
|
| `hidden.ts` | Values extensions hide (`host.hide`) from command output as it streams and from every tool's result, and the variables they add to each command (`host.commandEnv`), both through the environment each conversation's commands run in (`wrapEnv`) |
|
|
93
|
+
| `secrets.ts` | Core's own secrets: hides each in every session (settings marked secret, the owner token, `push.json`'s private key, Pi's `auth.json`), again on each change, and the rule Lancet Guard applies first to keep Pi from their files |
|
|
93
94
|
| `extension-points.ts` | `host.ask`, an extension's question on an approval card whose typed values go to the asker alone, and `host.browser`, a session's page for extensions with `fill` and controls as data, but no script |
|
|
94
95
|
| `app-events.ts` | What happens in the app, for extensions (`host.on`): sessions made, renamed, and archived, messages people send to Pi, and runs that start and end, each after its commit; PiP sends none |
|
|
95
96
|
| `extension-settings.ts` | Settings modules declare (`web.settings`): their fields checked as the module loads, the owner's values checked before config.json keeps them, and what browsers see (never a secret's value) |
|
|
@@ -223,7 +224,8 @@ Plain ES modules, loaded as they are. `math.js` finds Markdown math delimiters;
|
|
|
223
224
|
| `calls.js` | A tool call in one line, for the transcript's timeline and peek tiles; extensions' own tools as `extension-ui.js` gives them (`setCallDescriber`) |
|
|
224
225
|
| `slots.js` | Slots: the top bar's buttons, the status line's items, the places, the message box's left buttons, and the actions under answers as named items, the app's own (`defineItem`) and extensions' (`fromExtensions`), in one order: defaults, `before`/`after`, extensions' `pocket.arrange`, then the person's own choices (`prefs().layout`, Appearance → Layout) |
|
|
225
226
|
| `composer.js` | Message box, chips, the queue, plan and goal bars, `@` file suggestions, `!` commands, ↑ and Ctrl+R history, long-paste placeholders, the mic (`voice.js`), a subagent's way back to its session, the status line under it (kept to one row) |
|
|
226
|
-
| `quote-reply.js`, `quote-text.js` | Reply to a passage: the Reply and Ask PiP buttons by a selection in one of Pi's replies
|
|
227
|
+
| `quote-reply.js`, `quote-text.js` | Reply to a passage: the Reply and Ask PiP buttons by a selection in one of Pi's replies; the quote lines (cut at 1,500 characters), where Reply puts them in the message box, and how an edit treats each one as a piece (`quoteStep`) |
|
|
228
|
+
| `quote-box.js` | The drawing of the reply quotes in the message box under the box's text, with their × |
|
|
227
229
|
| `entry-presentation.js` | How this browser shows an input a module presents (`pocket.entryPresentation`): open, folded, or hidden, kept in this browser |
|
|
228
230
|
| `user-search.js` | What Find searches in a person's message: its presented label and summary, then the text written |
|
|
229
231
|
| `subagents.js` | The subagents bar above the message box: each subagent's state, what it was asked, and what it does now (its peek, through `useOnScreen` in `peeks.js`); Stop, open, put away. Its states and times (`stateOf`, `elapsed`, `ordered`) and failures dealt with (`unresolved`, `dismiss`, `seeFailure`) serve the board too |
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-pocket",
|
|
3
|
-
"version": "0.29.0-beta.
|
|
3
|
+
"version": "0.29.0-beta.4",
|
|
4
4
|
"lockfileVersion": 3,
|
|
5
5
|
"requires": true,
|
|
6
6
|
"packages": {
|
|
7
7
|
"": {
|
|
8
8
|
"name": "pi-pocket",
|
|
9
|
-
"version": "0.29.0-beta.
|
|
9
|
+
"version": "0.29.0-beta.4",
|
|
10
10
|
"license": "MIT",
|
|
11
11
|
"dependencies": {
|
|
12
12
|
"@earendil-works/chord": "1.5.2",
|
package/package.json
CHANGED
package/src/server/app.ts
CHANGED
|
@@ -132,6 +132,7 @@ import {
|
|
|
132
132
|
} from "./room.ts";
|
|
133
133
|
import { whyUnanswered } from "./subagent-runs.ts";
|
|
134
134
|
import { Schedules } from "./schedules.ts";
|
|
135
|
+
import { CoreSecrets } from "./secrets.ts";
|
|
135
136
|
import { BackgroundTasks } from "./background.ts";
|
|
136
137
|
import { Shares } from "./share.ts";
|
|
137
138
|
import { CommandEnvs, HiddenValues, wrapEnv } from "./hidden.ts";
|
|
@@ -452,6 +453,8 @@ export class PocketApp {
|
|
|
452
453
|
readonly browsers: Browsers;
|
|
453
454
|
/** What extension modules add to the app: their routes, browser modules, and events (`extension-web.ts`). */
|
|
454
455
|
readonly webs: ExtensionWebs;
|
|
456
|
+
/** Core's own secrets: hidden in every session, and kept from Pi by Lancet Guard (`secrets.ts`). */
|
|
457
|
+
readonly secrets: CoreSecrets;
|
|
455
458
|
#websTimer: NodeJS.Timeout | undefined;
|
|
456
459
|
/** Whose tabs the next `hello` for browser modules goes to: those who may use any of these. */
|
|
457
460
|
readonly #websFor = new Set<WebAccess>();
|
|
@@ -654,6 +657,15 @@ export class PocketApp {
|
|
|
654
657
|
links: this.publicLinks,
|
|
655
658
|
settings: (module) => this.config.extensionSettings(module),
|
|
656
659
|
});
|
|
660
|
+
this.secrets = new CoreSecrets({
|
|
661
|
+
hidden: this.hidden,
|
|
662
|
+
config: this.config,
|
|
663
|
+
dataDir: this.dataDir,
|
|
664
|
+
agentDir: getAgentDir(),
|
|
665
|
+
settingsOf: (module) => this.webs.settingsOf(module),
|
|
666
|
+
log: (line) => this.#log(line),
|
|
667
|
+
});
|
|
668
|
+
this.guard.protect = (tool, args, cwd) => this.secrets.blocked(tool, args, cwd);
|
|
657
669
|
}
|
|
658
670
|
|
|
659
671
|
/**
|
|
@@ -855,6 +867,8 @@ export class PocketApp {
|
|
|
855
867
|
hooks: [
|
|
856
868
|
hook(ToolTask, {
|
|
857
869
|
afterTool: (_call, result, api) => {
|
|
870
|
+
// A secret that changed while the tool ran is hidden from its result too.
|
|
871
|
+
this.secrets.sync();
|
|
858
872
|
const cleaned = this.hidden.result(result, api.conversationId);
|
|
859
873
|
|
|
860
874
|
return cleaned === result ? undefined : cleaned;
|
|
@@ -1057,6 +1071,8 @@ export class PocketApp {
|
|
|
1057
1071
|
void this.guard.warm().catch(() => {});
|
|
1058
1072
|
}
|
|
1059
1073
|
|
|
1074
|
+
// Core's secrets are hidden before any work goes on, with the settings the modules that loaded declare.
|
|
1075
|
+
this.secrets.sync();
|
|
1060
1076
|
await this.pip.tuneAll((line) => this.#log(line));
|
|
1061
1077
|
// Work a previous process left unfinished continues now.
|
|
1062
1078
|
this.harness.resume();
|
|
@@ -1606,6 +1622,9 @@ export class PocketApp {
|
|
|
1606
1622
|
|
|
1607
1623
|
/** A folder's environment, with what extensions add to each command and hide from its output in this session. */
|
|
1608
1624
|
#wrapped(id: ConversationId, cwd: string): ExecutionEnv {
|
|
1625
|
+
// Each command hides core's secrets as they are now.
|
|
1626
|
+
this.secrets.sync();
|
|
1627
|
+
|
|
1609
1628
|
return wrapEnv(this.#env(cwd), Number(id), cwd, this.commandEnvs, this.hidden);
|
|
1610
1629
|
}
|
|
1611
1630
|
|
|
@@ -2604,6 +2623,8 @@ export class PocketApp {
|
|
|
2604
2623
|
home: homedir(),
|
|
2605
2624
|
defaultCwd: this.defaultCwd,
|
|
2606
2625
|
extensions: this.loader.extensionNames(),
|
|
2626
|
+
// The shortest repeat, so the Schedules sheet's editor keeps Save off for one the server refuses.
|
|
2627
|
+
scheduleRepeatMinutes: this.schedules.limits.repeatMinutes,
|
|
2607
2628
|
// The browser modules this person's tabs load (`extension-ui.js`), each with the tools its module
|
|
2608
2629
|
// installs: the only ones whose calls it may describe (`pocket.toolCall`).
|
|
2609
2630
|
ui: this.#browserModules(user),
|
|
@@ -3664,6 +3685,8 @@ export class PocketApp {
|
|
|
3664
3685
|
`${module.title} is on but failed to load: ${describe(error)}`,
|
|
3665
3686
|
);
|
|
3666
3687
|
} finally {
|
|
3688
|
+
// A module that came or went changes which of its stored values are secret.
|
|
3689
|
+
this.secrets.sync();
|
|
3667
3690
|
await this.#refreshClients();
|
|
3668
3691
|
}
|
|
3669
3692
|
|
|
@@ -3835,6 +3858,8 @@ export class PocketApp {
|
|
|
3835
3858
|
}
|
|
3836
3859
|
|
|
3837
3860
|
this.config.setExtensionSettings(module, next);
|
|
3861
|
+
// Hidden at once in every session: the new value, and the old one too.
|
|
3862
|
+
this.secrets.sync();
|
|
3838
3863
|
this.webs.settingsChanged(module);
|
|
3839
3864
|
|
|
3840
3865
|
return shownSettings(fields, next, false);
|