pi-pocket 0.29.0-beta.2 → 0.29.0-beta.3

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.
@@ -302,11 +302,11 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
302
302
 
303
303
  **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
304
 
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, and gives the quote back (`giveBackQuote`). 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, and its quote when it has one, since a reload loses the quote), 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.
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; 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
306
 
307
307
  **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
308
 
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 quote (`replyQuote`), the only one the session composer shows, waits under the board as long as `openId()` stays that session. A send takes its quote out of its box as it starts (`dropQuote`, by identity) 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.
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 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
310
 
311
311
  **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
312
 
@@ -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` | `core:connection`, `core:guard` | after `core:cache` |
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` | The passage a reply quotes, at the top of a message (since 0.27.0) |
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 the box: the passage a reply quotes, with a button to remove it (since 0.27.0) |
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
@@ -15,14 +15,14 @@ The full tour. For setup, see the [README](../README.md).
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
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.
17
17
  - **Getting around on a phone, with one hand.** Back (the swipe, Android's back button, the browser's) goes back to where you were: it closes what opened last (a sheet, the menu's next sheet back to the menu, a file back to the Files tree, back to Changes when the file was opened from there, the Files tile or the Browser panel, the drawer) before it leaves the session, and leaving goes to the session before or to the list, scrolled and searched as you left it. A session opened straight away (a link, a notification) has the list under it, so back does not leave the app. What you use most is a thumb's reach from the bottom edge: the button beside the message box (or a swipe up from it) opens the places, a short sheet of big tiles (Files, Changes, Browser, Artifacts, Chat, Find, Branch, Peeks) with the session menu below them. On the conversation, swipe left for Files and right to go back; in Files, swipe right to go back. Each swipe shows a mark that lights when letting go will act. The top bar leads back to the list (counting other sessions that wait for an approval) and keeps only the buttons with something to say. Every control is a thumb's size on a touch screen (small ones, such as a code block's Copy or a reply's Pin, keep their look and take a wider tap); a tap anywhere on the message box, off its one line of text, still goes to the text; a quick second tap does not land on whatever just slid in under it; tables in replies scroll sideways instead of crushing their columns; a diff's header keeps the file's name on a line of its own on a phone; and the command a peek tile asks about opens its session when tapped. The Files tile and the browser slide in as screens of their own and slide away on back, a file slides in over the tree, and the browser's tools sit on their own row under the address. Drag a sheet down, or the drawer left, to close it. In an iPhone home screen app, which has no back gesture of its own, swipe in from the left edge to go back.
18
- - **Reply to a passage.** Select words in one of Pi's replies, on a phone or a desktop, and a **Reply** button appears by the selection (below it on a touch screen, where the system's menu sits above). It puts the passage in a quote strip above the message box (tap × to drop it); the next message goes to Pi with the passage first as a Markdown quote (up to 1,500 characters), and shows in the conversation as a quote block above your words. 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.
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
22
  - **Memory.** Short lessons Pi keeps across sessions: how to build and test a project, a gotcha it hit, a convention, a preference someone stated. Pi proposes one with its `memory` tool (one or two sentences each, never secrets) only when a person asks for it, or when Pi is sure that it will help in many later sessions, never for a one-off detail, and proposes fixing or forgetting one that turns out wrong; the owner approves. What Pi reads (a web page, a post, a comment, a file) could talk it into a "lesson" that would reach every later session, so nothing Pi saves, changes, or forgets counts until the owner says: **Approve** and **Discard** show right under Pi's memory call, with the words that wait and where they would apply (this project, or everywhere: every session and PiP), and in the sheet. Approve approves only what you saw: if Pi changed it since, the app says so and shows the new words. Lessons and project names are kept on one line, without invisible characters, so Pi reads only what the owner saw. A change or forgetting Pi proposes leaves the lesson as it was until then. Lessons you add yourself count at once. Each is for this project or for everywhere: a project's lessons reach every later session in the same repository, its worktrees included (or the same folder, outside a repository), and everywhere's reach every session and PiP. Menu → **Memory** (its hint says how many apply here and everywhere) opens as a wide sheet; a switch at its top, **This project** or **Everywhere**, each with how many it holds and how many of them wait for approval, picks which of the two it lists and where a lesson you type in goes. Each shows who saved it and a link to the session it came from (when you may see it), with Edit and Forget; type one in to add it by hand, or use `/remember run the tests with make check` or **Remember…** on a message. A guest's lessons wait for the owner too, and a guest's change to one in force is a proposal they can withdraw. What waits shows at the top of the owner's sheet; the menu's hint says how many. Lessons waiting take no room from the approved ones, and a person (or Pi for them) may have 20 waiting at most. Only the owner, or whoever saved a lesson, changes or forgets it; viewers only read. A project keeps 40 lessons and everywhere 30; past that, forget one first. Changes show as lines in the chat. Turn it off in Extensions.
23
23
  - **A lean prompt.** A new session gets only the tools most conversations use. `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools wait, and so do their prompt sections; the prompt lists them with a line each, and Pi loads one with `tool_search` when a task needs it. On a model whose provider takes tool changes in the messages (Claude 4.8 and 5, and later), the tool joins the list and stays for the conversation; on any other, Pi calls it from a `codemode` script, so the tool list and the prompt cache never change. Long guides, such as the design guide and the page-to-app messages of artifacts, are files that Pi reads when it needs them. Turn the **Tool search** module off in Menu → Extensions to offer every tool every time. A test keeps Pi Pocket's own part of a plain session's prompt under 14,000 characters (about 5,000 tokens: schemas and this prose run at about 2.75 characters a token), so it does not grow by accident.
24
24
  - **Plan mode.** The **Plan** chip by the message box (or `/plan`): Pi reads files, runs read-only commands, and uses tools their extensions mark read-only, then proposes a plan; writing, editing, and other commands are blocked. Subagents inherit plan mode and explore under the same restrictions. **Approve plan** turns plan mode off and tells Pi to go ahead; it waits until Pi has answered since plan mode went on.
25
- - **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, or Menu → **Scheduled messages**: Pi gets the message at its time, in this device's time zone, even with nobody watching, and the people in the session get the usual "Pi finished" notification. Pi can schedule its own follow-ups with its `schedule` tool. Each schedule is a durable task: a restart while it waits keeps waiting, one after its time sends at once, and none is ever sent twice. A schedule is cancelled, with a line in the chat saying why, once its person can no longer steer the session or a spend limit is reached. A repeat whose last message still waits in the session's queue (Pi is at work, or a run failed and holds it) sends no other at its next time: the time is skipped, a line in the chat counts the skips, and the Schedules sheet, the Running now board, and Pi's `schedule` tool list show how many there were (since 0.28.1). Limits (settable since 0.24.0): a session holds 50 schedules, a message 4000 characters, a repeat comes at most every 10 minutes (a short repeat can cost money in model calls), and `in …` reaches 366 days ahead. The owner changes each in Menu → Extensions, under Scheduled messages; a change applies at once, to new schedules only. Archiving a session that has repeating schedules says how many keep running there, with a tap to see them, and its Schedules sheet marks it as archived; nothing stops or moves (since 0.28.0).
25
+ - **Scheduled messages.** `/schedule in 2h check the deploy`, `/schedule tomorrow 9am …`, or `/schedule every weekday 8:00 summarize CI`, 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. 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 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.
@@ -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**; **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.
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.
@@ -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, and the quote lines (cut at 1,500 characters) that go before the message |
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 |
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.29.0-beta.2",
3
+ "version": "0.29.0-beta.3",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-pocket",
9
- "version": "0.29.0-beta.2",
9
+ "version": "0.29.0-beta.3",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "@earendil-works/chord": "1.5.2",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.29.0-beta.2",
3
+ "version": "0.29.0-beta.3",
4
4
  "description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
5
5
  "keywords": [
6
6
  "pi",
package/src/server/app.ts CHANGED
@@ -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);
@@ -89,7 +89,7 @@ import {
89
89
  } from "./resend.ts";
90
90
  import { whyUnanswered } from "./subagent-runs.ts";
91
91
  import { wantsTitle, writeTitle } from "./titles.ts";
92
- import { describeMoment, describeRepeat, knownZone } from "./when.ts";
92
+ import { checkRepeat, describeMoment, describeRepeat, knownZone, type Repeat } from "./when.ts";
93
93
  import {
94
94
  createWorktree,
95
95
  discardWorktree,
@@ -778,7 +778,9 @@ export class Commands {
778
778
  // Archiving leaves its repeating schedules running: the person is told how many.
779
779
  const repeating =
780
780
  patch.archived === true
781
- ? (await app.schedules.list(id)).filter((item) => item.every !== undefined).length
781
+ ? (await app.schedules.list(id)).filter(
782
+ (item) => item.every !== undefined && item.paused === undefined,
783
+ ).length
782
784
  : 0;
783
785
 
784
786
  return { repeating };
@@ -2220,7 +2222,13 @@ export class Commands {
2220
2222
  async schedule(
2221
2223
  id: ConversationId,
2222
2224
  user: User,
2223
- request: { when?: unknown; zone?: unknown },
2225
+ request: {
2226
+ when?: unknown;
2227
+ text?: unknown;
2228
+ next?: unknown;
2229
+ every?: unknown;
2230
+ zone?: unknown;
2231
+ },
2224
2232
  ): Promise<Schedule> {
2225
2233
  const app = this.#app;
2226
2234
 
@@ -2232,9 +2240,14 @@ export class Commands {
2232
2240
  throw new HttpError(400, `Unknown time zone ${zone}`);
2233
2241
  }
2234
2242
 
2243
+ // From the Schedules sheet's editor: the text, and when as data, instead of `when` typed in words.
2244
+ const given = request.next !== undefined || request.every !== undefined;
2245
+ const at = given ? this.#scheduleTime(request) : undefined;
2246
+
2235
2247
  app.spend.check(user, id);
2236
2248
  const schedule = await app.schedules.add(id, {
2237
2249
  when: optionalText(request.when, "when") ?? "",
2250
+ ...(at === undefined ? {} : { at, text: optionalText(request.text, "text") ?? "" }),
2238
2251
  by: user,
2239
2252
  ...(zone === undefined ? {} : { zone }),
2240
2253
  });
@@ -2248,6 +2261,115 @@ export class Commands {
2248
2261
  return schedule;
2249
2262
  }
2250
2263
 
2264
+ /**
2265
+ * Change a scheduled message: its text, and when it goes out: `next` (a moment) for one that goes out once, `every`
2266
+ * for a repeat (with `next` its first time, for one every so many minutes), in `zone`.
2267
+ */
2268
+ async updateSchedule(
2269
+ id: ConversationId,
2270
+ user: User,
2271
+ scheduleId: string,
2272
+ request: {
2273
+ text?: unknown;
2274
+ next?: unknown;
2275
+ every?: unknown;
2276
+ zone?: unknown;
2277
+ version?: unknown;
2278
+ },
2279
+ ): Promise<Schedule> {
2280
+ const app = this.#app;
2281
+
2282
+ app.requireSee(user, id);
2283
+ await app.requireDriver(id, user);
2284
+ const zone = optionalText(request.zone, "zone");
2285
+ const version = optionalText(request.version, "version");
2286
+
2287
+ if (zone !== undefined && !knownZone(zone)) {
2288
+ throw new HttpError(400, `Unknown time zone ${zone}`);
2289
+ }
2290
+
2291
+ const at = this.#scheduleTime(request);
2292
+
2293
+ app.spend.check(user, id);
2294
+ const schedule = await app.schedules.update(id, scheduleId, {
2295
+ text: optionalText(request.text, "text") ?? "",
2296
+ ...at,
2297
+ ...(zone === undefined ? {} : { zone }),
2298
+ ...(version === undefined ? {} : { version }),
2299
+ by: user,
2300
+ });
2301
+ const when =
2302
+ schedule.every === undefined
2303
+ ? `for ${describeMoment(schedule.next, schedule.zone)}`
2304
+ : describeRepeat(schedule.every);
2305
+
2306
+ await app.collab.activity(
2307
+ id,
2308
+ user,
2309
+ `changed the scheduled “${snippet(schedule.text, 60)}” to ${when}`,
2310
+ );
2311
+
2312
+ return schedule;
2313
+ }
2314
+
2315
+ /** A schedule's time as the editor sends it, its repeat checked: `next` (a moment), `every` (a repeat), or both. */
2316
+ #scheduleTime(request: { next?: unknown; every?: unknown }): {
2317
+ next?: number;
2318
+ every?: Repeat;
2319
+ } {
2320
+ if (request.next !== undefined && typeof request.next !== "number") {
2321
+ throw new HttpError(400, "next must be a time in milliseconds");
2322
+ }
2323
+
2324
+ try {
2325
+ return {
2326
+ ...(request.next === undefined ? {} : { next: request.next }),
2327
+ ...(request.every === undefined || request.every === null
2328
+ ? {}
2329
+ : {
2330
+ every: checkRepeat(request.every, {
2331
+ repeatMinutes: this.#app.schedules.limits.repeatMinutes,
2332
+ }),
2333
+ }),
2334
+ };
2335
+ } catch (error) {
2336
+ throw new HttpError(400, describe(error));
2337
+ }
2338
+ }
2339
+
2340
+ /** Pause a scheduled message, or resume it: paused, it sends nothing until someone resumes it. */
2341
+ async pauseSchedule(
2342
+ id: ConversationId,
2343
+ user: User,
2344
+ scheduleId: string,
2345
+ paused: unknown,
2346
+ ): Promise<Schedule> {
2347
+ const app = this.#app;
2348
+
2349
+ app.requireSee(user, id);
2350
+ await app.requireDriver(id, user);
2351
+
2352
+ if (typeof paused !== "boolean") {
2353
+ throw new HttpError(400, "paused must be true or false");
2354
+ }
2355
+
2356
+ if (!paused) {
2357
+ app.spend.check(user, id);
2358
+ }
2359
+
2360
+ const { schedule, changed } = await app.schedules.pause(id, scheduleId, paused, user);
2361
+
2362
+ if (changed) {
2363
+ await app.collab.activity(
2364
+ id,
2365
+ user,
2366
+ `${paused ? "paused" : "resumed"} the scheduled “${snippet(schedule.text, 60)}”`,
2367
+ );
2368
+ }
2369
+
2370
+ return schedule;
2371
+ }
2372
+
2251
2373
  async cancelSchedule(id: ConversationId, user: User, scheduleId: string): Promise<void> {
2252
2374
  const app = this.#app;
2253
2375
 
@@ -230,6 +230,11 @@ export class ConfigStore {
230
230
  return { ...(this.#config.extensionSettings?.[module] ?? {}) };
231
231
  }
232
232
 
233
+ /** The modules the owner set values for, on or off. */
234
+ extensionSettingModules(): string[] {
235
+ return Object.keys(this.#config.extensionSettings ?? {});
236
+ }
237
+
233
238
  /** Keep a module's values, all of them at once; none drops its entry. */
234
239
  setExtensionSettings(module: string, values: Record<string, string | number | boolean>): void {
235
240
  const all = { ...(this.#config.extensionSettings ?? {}) };
@@ -551,6 +551,10 @@ export type Schedule = {
551
551
  taskId: TaskId;
552
552
  /** Set by the same call already, when a tool call is replayed: its `taskId:callId`. */
553
553
  key?: string;
554
+ /** How many times it was edited: what an editor's save checks, so a save from an older copy is refused. */
555
+ revision?: number;
556
+ /** Paused by a person: it sends nothing until someone resumes it. When, and by whom. */
557
+ paused?: { at: number; by: string };
554
558
  };
555
559
 
556
560
  /** Messages that go to Pi later, or on repeat. A fork starts without them: they belong to who set them up. */
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Lancet Guard for Pi Pocket's tools. Before a bash, write, or edit call, the guard from the user's Pi install judges
3
- * it. Blocks become error results for the model. "Ask" verdicts wait for anyone in the conversation to approve or deny
4
- * the call in the app. The answer is stored in the call's memo, so a restart after the answer never asks twice.
3
+ * it. Before any call, core's rule blocks one that would read a file Pi Pocket keeps secrets in (`secrets.ts`).
4
+ * Blocks become error results for the model. "Ask" verdicts wait for anyone in the conversation to approve or deny the
5
+ * call in the app. The answer is stored in the call's memo, so a restart after the answer never asks twice.
5
6
  */
6
7
  import { AgentDoc, defineExtension, hook, ToolTask } from "@earendil-works/pi-durable";
7
8
  import type { ApprovalAnswer, PocketHost } from "../host.ts";
@@ -110,7 +110,7 @@ export default function createSchedules(host: PocketHost, web: ExtensionWeb) {
110
110
  execute: async (args, api) => {
111
111
  const reply = (text: string) => ({ output: [{ type: "text" as const, text }] });
112
112
  const line = (item: Schedule) =>
113
- `${item.id}: ${item.every === undefined ? describeMoment(item.next, item.zone) : `${describeRepeat(item.every)}, next ${describeMoment(item.next, item.zone)}`}${(item.skipped ?? 0) > 0 ? `, skipped ${String(item.skipped)}× (last ${describeMoment(item.skippedAt ?? item.next, item.zone)}): its last message still waits in the queue` : ""} · ${item.text}`;
113
+ `${item.id}: ${item.paused !== undefined ? `paused by a person (only they or another person can resume it) · ${item.every === undefined ? "once" : describeRepeat(item.every)}` : item.every === undefined ? describeMoment(item.next, item.zone) : `${describeRepeat(item.every)}, next ${describeMoment(item.next, item.zone)}`}${(item.skipped ?? 0) > 0 ? `, skipped ${String(item.skipped)}× (last ${describeMoment(item.skippedAt ?? item.next, item.zone)}): its last message still waits in the queue` : ""} · ${item.text}`;
114
114
 
115
115
  if (args.action === "list") {
116
116
  const items = await host.schedules.list(api.conversationId);
@@ -319,12 +319,17 @@ export async function viewFile(file: string): Promise<FileView> {
319
319
  /**
320
320
  * The files `@` mentions in a message name, as the message box writes them: `@src/app.ts`, or `@"my file.txt"` with
321
321
  * spaces. Each comes with the paths it may mean, best first: as written, then without the punctuation that may end a
322
- * sentence after it ("look at @app.ts.").
322
+ * sentence after it ("look at @app.ts."). One in a quote ("> …" lines, a passage Reply quoted) is the passage's, not a
323
+ * file the person asks to send along.
323
324
  */
324
325
  export function mentionedPaths(text: string): { written: string; candidates: string[] }[] {
325
326
  const found: { written: string; candidates: string[] }[] = [];
327
+ const own = text
328
+ .split("\n")
329
+ .filter((line) => !/^ {0,3}>/.test(line))
330
+ .join("\n");
326
331
 
327
- for (const match of text.matchAll(/(?:^|[\s([{])@(?:"([^"\n]+)"|([^\s"]+))/g)) {
332
+ for (const match of own.matchAll(/(?:^|[\s([{])@(?:"([^"\n]+)"|([^\s"]+))/g)) {
328
333
  const written = match[1] ?? match[2]!;
329
334
 
330
335
  if (found.some((each) => each.written === written)) {