pi-pocket 0.30.0-beta.3 → 0.30.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.
Files changed (41) hide show
  1. package/docs/architecture.md +5 -1
  2. package/docs/examples/time-gap.ts +40 -0
  3. package/docs/extensions/policies/api-stability.md +1 -0
  4. package/docs/extensions/reference/api-versions.md +1 -0
  5. package/docs/extensions/reference/host.md +44 -1
  6. package/docs/extensions/services-settings.md +1 -0
  7. package/docs/extensions/turn-notes.md +82 -0
  8. package/docs/extensions.md +1 -0
  9. package/docs/features.md +2 -1
  10. package/docs/map.md +5 -2
  11. package/npm-shrinkwrap.json +2 -2
  12. package/package.json +1 -1
  13. package/src/server/app-events.ts +5 -2
  14. package/src/server/app.ts +74 -0
  15. package/src/server/artifact-state.ts +6 -4
  16. package/src/server/artifacts.ts +192 -0
  17. package/src/server/commands.ts +40 -11
  18. package/src/server/docs.ts +70 -6
  19. package/src/server/entry-format.ts +8 -0
  20. package/src/server/extensions/artifacts.ts +22 -1
  21. package/src/server/extensions/design/system-routes.ts +3 -1
  22. package/src/server/extensions/session-cleanup/index.js +376 -0
  23. package/src/server/extensions/session-cleanup/style.css +92 -0
  24. package/src/server/extensions/session-cleanup.ts +71 -0
  25. package/src/server/host.ts +12 -0
  26. package/src/server/http/conversation-routes.ts +11 -0
  27. package/src/server/linked-sessions.ts +7 -2
  28. package/src/server/projection.ts +15 -0
  29. package/src/server/reload.ts +2 -0
  30. package/src/server/room.ts +8 -3
  31. package/src/server/session-cleanup.ts +592 -0
  32. package/src/server/share.ts +10 -0
  33. package/src/server/turn-notes.ts +254 -0
  34. package/src/server/workspace.ts +4 -6
  35. package/types/pocket.d.ts +69 -0
  36. package/web/rich.js +34 -2
  37. package/web/sheets/viewers.js +88 -24
  38. package/web/store.js +3 -0
  39. package/web/style.css +49 -0
  40. package/web/transcript.js +23 -0
  41. package/web/ui.js +1 -0
@@ -53,6 +53,8 @@ Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose funct
53
53
 
54
54
  `host.pendingApprovals` (`pending-approvals.ts`) observes the internal approval service in `host.ts`. It filters waits for the source session's requester and everyone who can see the source. It does not pass on commands, arguments, reasons, or answers. The guard hook keeps a wait's first creation time in its Durable call memo, so a resumed run can show the same wait. Approval decisions still use the app's existing paths.
55
55
 
56
+ `host.annotateTurns` (`turn-notes.ts`) relies on Pi Durable's admission: an input to an idle conversation with an empty `pi.inbox` is placed in the admitting commit, so `Commands.submit` admits it with `submit(tx, draft)` and appends each `pocket.turn-note` entry after it in that commit. A queued input is placed later by Durable's boundary, which no Pocket code joins, so it gets no note. Pi Durable would need an input draft that carries its own entries (placed at the same boundary, dropped on withdraw) for queued turns.
57
+
56
58
  ## Workspace execution providers
57
59
 
58
60
  `PocketApp` selects the execution environment by the session's working folder. Local folders keep the existing Node environment; URI workspaces use the last registered provider for their scheme. Removal restores the previous registration, and a missing provider fails closed. Resolution checks the provider identity and cancellation after awaited work. Only the owner can use a workspace URI. The provider's module, a drop-in outside the core package, owns host-key trust, connections, remote project context, and cleanup. Files/Git actions and managed worktrees remain local-only.
@@ -145,7 +147,7 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
145
147
  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:
146
148
 
147
149
  - 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.
148
- - **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.
150
+ - **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. An archived session keeps its lessons, which apply nowhere else; Remove and clean up (`session-cleanup.ts`, since 0.30.0) removes them with the session. 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.
149
151
  - 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).
150
152
  - 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`).
151
153
  - 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`).
@@ -262,6 +264,8 @@ Each browser tab is a `Client` (`room.ts`), fed by an event stream or by long po
262
264
 
263
265
  On the server, `WebRequest.sessions()` (`http/extension-routes.ts`) is `app.sessions(user)` for the person as they are when the handler asks, cut to `{ id, title, cwd, archived, updatedAt }`: modules check session ids with core's own rule of who sees what. Session tags (`extensions/session-tags.ts`) adds nothing on a server older than 0.20.0 (`host.pocketVersion`): such a server, running when its checkout moves to this file, would turn it on, with none of what it needs. It keeps its tags in its own document, gives each person only those of the sessions they see, and changes them in one commit, all or nothing.
264
266
 
267
+ **Removing a session** (`session-cleanup.ts`, since 0.30.0; the Session cleanup module is the owner's way to it) never touches Pi Durable's tables: Pi Durable has no way to purge a conversation yet, so the transcript stays in storage. One commit takes the archived session out of the catalogue (`pocket.sessions`), writes its entry in `pocket.deleted` (the session and its subagents' conversation ids, its worktree, and the uploads a live fork still reads), and takes out the webhooks and repository watches that target it, its artifact shares, the public links of modules about it, and its session lessons. Forks go before their parents in one request, and the entry keeps `forkedFrom`, so a live fork still reads uploads through a removed session in between (`app.forkedFrom`, used by `workspace.ts`). A run that started while the plan was made keeps the session. A removed lead takes no linked session's report, as an archived one. Then `#finish` ends its work (a run, schedules, background tasks, the PR watch, the browser page) and removes Pocket's own files: the worktree (never with uncommitted changes; its branch stays), `uploads/<id>`, and `background/<id>`. It marks the entry `done`; every start runs `resume`, which goes on with an entry that has none, so a crash between the commit and the files leaves nothing half done. `canSee` is false for every conversation of a removed session (its subagents' too), for everyone, so no route, tab, delivery, or message reaches it again; tabs that show it get `missing`. Extensions hear `session.removed`. When Pi Durable can purge a conversation, `pocket.deleted` is the list to purge. A session with Pi at work, or whose worktree has uncommitted changes or Pi works in it, stays. Cleaning up (`cleanUp`) removes only the worktrees of archived sessions, with the session's own Remove worktree.
268
+
265
269
  Public links (`public-links.ts`, since 0.22.0) are the one way a module answers people with no sign-in. Core keeps the links in `pocket.public-links`, each with its module's name, so `web.links` reaches only its own module's, and `http/link-routes.ts` answers `/l/<token>` only while that module is on (`ExtensionWebs.publicPage`). Core, not the module, closes a link at its time and counts its uses: a use is claimed in a commit before the handler runs, so two posts at once cannot both get in, and given back when the page refuses the post. Every page goes out with a sandbox policy and no script, so it has an opaque origin and the app's cookie gives it nothing. Ask someone (`extensions/ask-someone.ts`) is built on it, with nothing of Pi Pocket's but types, as a drop-in would be.
266
270
 
267
271
  People's values (since 0.22.0) go around Pi, never through it. `host.ask` is an approval with a `form` (`Approvals`, so it waits, notifies, and shows as one): the request that tabs see holds the fields, and the values come only in the answer to the asker, after `answerApproval` checked each field and that the person answering is the one Pi works for (`cannotAllow`). `host.commandEnv` and `host.hide` act in `wrapEnv` (`hidden.ts`), the execution environment the harness builds for each conversation, so bash, `!` commands, codemode, and checks all get the variables and lose the values the same way; an `afterTool` hook of `pocket-core` takes hidden values out of every tool's result before it is stored. `host.browser` (`extension-points.ts`) wraps a `BrowserPage` in a handle with no `evaluate`, and only while the Browser module is on.
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Time gap: tells Pi how long a session was quiet when a person writes after a long silence.
3
+ */
4
+ import type { Host, Turn, Web } from "../../types/pocket.d.ts";
5
+
6
+ const HOUR = 3_600_000;
7
+
8
+ /** "About 2 days" or "About 5 hours", or undefined for a gap shorter than 3 hours. */
9
+ function gap(turn: Turn): string | undefined {
10
+ if (turn.previousActivityAt === undefined) {
11
+ return undefined;
12
+ }
13
+
14
+ const hours = (turn.at - turn.previousActivityAt) / HOUR;
15
+
16
+ if (hours < 3) {
17
+ return undefined;
18
+ }
19
+
20
+ const days = Math.round(hours / 24);
21
+
22
+ return hours < 36 ? `About ${Math.round(hours)} hours` : `About ${days} days`;
23
+ }
24
+
25
+ export default function createTimeGap(host: Host, web: Web) {
26
+ // A server older than 0.30.0 has no turn notes: do nothing there.
27
+ if (typeof host.annotateTurns !== "function") {
28
+ return;
29
+ }
30
+
31
+ web.onDispose(
32
+ host.annotateTurns("time-gap", (turn) => {
33
+ const passed = gap(turn);
34
+
35
+ return passed === undefined
36
+ ? undefined
37
+ : `<system-reminder>\n${passed} have passed since the previous message.\n</system-reminder>`;
38
+ }),
39
+ );
40
+ }
@@ -54,6 +54,7 @@ These members are public:
54
54
  - `fetchPublic(url, init)` (experimental, since 0.20.0)
55
55
  - `ask(request, context)`, `hide(value)`, `commandEnv(provider)`, `browser(conversationId, options)` (experimental, since 0.22.0: [People's values and the browser](../people-values.md))
56
56
  - [`pendingApprovals`](../reference/host.md#pendingapprovals): read-only approval snapshots and events (experimental, since 0.30.0)
57
+ - [`annotateTurns(name, annotate)`](../reference/host.md#annotateturns), `Turn`, and `TurnAnnotator`: notes for the model after a person's message (experimental, since 0.30.0: [Turn notes](../turn-notes.md))
57
58
  - `on(event, listener)` and the events of `AppEvents` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md))
58
59
 
59
60
  These members are on `host` for Pi Pocket's own built-in extensions: `guard`, `approvals`, `schedules`, `goals`, `browsers`, `memory`, `watches`, `repoWatches`, `gallery`, `updates`, `pip`, `pipCompaction`, `toolNames`, `stopToolCall`, `waitsForLimit`, and `alertOwner`, and `linkedSessions.activity`, `linkedSessions.stopCall`, and `linkedSessions.onLedRun`. They are **internal**. A drop-in can read them, but their shapes can change in any release. One of them becomes public only through a request for an extension point ([core-or-extension.md](core-or-extension.md#ask-for-a-new-extension-point)).
@@ -104,3 +104,4 @@ Each member in the reference has its own Since line. These parts came together:
104
104
  | `options.artifact` and `options.version` in `pocket.openConversation`: open an artifact of that session (experimental) | 0.29.0 |
105
105
  | `subagents: "always"` on a tool: the tool comes with every subagent that has a tool list (experimental) | 0.29.0 |
106
106
  | `host.pendingApprovals`: read-only approval snapshots and events (experimental) | 0.30.0 |
107
+ | `host.annotateTurns`: notes for the model after a person's message (experimental) | 0.30.0 |
@@ -394,6 +394,18 @@ Since 0.22.0 · Experimental
394
394
 
395
395
  A session's browser page: the one that Pi's `browser` tool and the people in the session use. With `open: true`, it opens the page when it is not open. It is `undefined` while the Browser module is off, and without `open`, when no page is open. See [`BrowserPageHandle`](#browserpagehandle).
396
396
 
397
+ ## Turn notes
398
+
399
+ ### `annotateTurns`
400
+
401
+ ```ts
402
+ annotateTurns(name: string, annotate: TurnAnnotator): () => void;
403
+ ```
404
+
405
+ Since 0.30.0 · Experimental
406
+
407
+ Adds a note for the model right after a person's message, as a separate entry of the transcript. `annotate` gets the [`Turn`](#turn) and returns the note's text, or `undefined` for none. Pi Pocket stores the note in the same commit as the message, and never computes it again. The model reads `Note from extension <name>:` and a line break before the text. Only a message placed at once gets notes: Pi does not work in the session, and nothing is queued. A queued message, an Interrupt, a scheduled message, and PiP's own conversation get none. The annotators of all modules have 2 seconds together; one that is late, throws, or returns more than 4,000 characters adds nothing, and the session shows a warning. `name` is 1 to 60 letters, digits, `.`, `_`, `:`, or `-`, and the transcript shows it with each note. Pass the returned function to `web.onDispose`. See [Turn notes](../turn-notes.md).
408
+
397
409
  ## Notices and text
398
410
 
399
411
  ### `notice`
@@ -698,6 +710,7 @@ interface AppEvents {
698
710
  };
699
711
  "session.renamed": { conversationId: number; title: string };
700
712
  "session.archived": { conversationId: number; archived: boolean };
713
+ "session.removed": { conversationId: number };
701
714
  "message.sent": {
702
715
  conversationId: number;
703
716
  by: string;
@@ -721,6 +734,7 @@ What each event's listener gets.
721
734
 
722
735
  - `session.created`: a session in the list was made, by a person, a fork (`forkedFrom`), a linked start (`linkedFrom`), or a resend. `createdBy` is a person's id. Subagents are not sessions in the list, and send none.
723
736
  - `session.renamed`, `session.archived`: its new title, or whether it is archived now.
737
+ - `session.removed` (since 0.30.0): the owner removed an archived session from the app (Session cleanup). Its id is not shown again: drop what your module keeps for it.
724
738
  - `message.sent`: a person's message to Pi, a steer or a queued one too. `by` is their id. `text` is the words as stored, with values that extensions hide already hidden and attachments left out. `via` names what sent it for them, such as PiP or a schedule.
725
739
  - `run.started`, `run.ended`: Pi started or stopped working in a conversation. `conversationId` is that conversation, a session's or a subagent's; `session` is the session it belongs to. Since 0.28.0, `run.ended` also says how the run stopped: `outcome` is `done` when it finished, `failed` when it gave up, or `aborted` when it was stopped. `failure` is why it gave up, the same short line the session list shows, and only when `outcome` is `failed`. A session's failure stands until a later run starts.
726
740
 
@@ -732,7 +746,7 @@ type AppEventName = keyof AppEvents;
732
746
 
733
747
  Since 0.22.0 · Experimental
734
748
 
735
- The name of an event: `"session.created"`, `"session.renamed"`, `"session.archived"`, `"message.sent"`, `"run.started"`, or `"run.ended"`.
749
+ The name of an event: `"session.created"`, `"session.renamed"`, `"session.archived"`, `"session.removed"`, `"message.sent"`, `"run.started"`, or `"run.ended"`.
736
750
 
737
751
  ## Types for asking, hiding, and the browser
738
752
 
@@ -850,6 +864,34 @@ Since 0.22.0 · Experimental
850
864
 
851
865
  Gives the variables to add to one command. A name is letters, digits, and `_`, not starting with a digit; a value has no NUL. A variable that breaks these is left out. The variables of all providers for one command are 256 KB at most.
852
866
 
867
+ ### `Turn`
868
+
869
+ ```ts
870
+ interface Turn {
871
+ readonly conversationId: number;
872
+ readonly by: string;
873
+ readonly via?: string;
874
+ readonly text: string;
875
+ readonly at: number;
876
+ readonly previousActivityAt?: number;
877
+ readonly signal: AbortSignal;
878
+ }
879
+ ```
880
+
881
+ Since 0.30.0 · Experimental
882
+
883
+ One person's message, before Pi answers it: its session, the person's id, what sent it for them (`via`, when it is not their own typing), their words as stored (hidden values hidden, attachments left out), and when it came. `previousActivityAt` is the newest time of a message, an answer, or a tool result among the session's last 32 entries, also from before a reset. It is `undefined` when there is none. `signal` aborts when the time for annotators ends.
884
+
885
+ ### `TurnAnnotator`
886
+
887
+ ```ts
888
+ type TurnAnnotator = (turn: Turn) => string | undefined | Promise<string | undefined>;
889
+ ```
890
+
891
+ Since 0.30.0 · Experimental
892
+
893
+ Gives the text of a note for one turn, at most 4,000 characters, or `undefined` for no note. Pi Pocket trims the text; an empty text is no note.
894
+
853
895
  ### `BrowserTarget`
854
896
 
855
897
  ```ts
@@ -946,6 +988,7 @@ The host has more members, for Pi Pocket's built-in modules only. They are not i
946
988
  - `pip`: what the tools of PiP, the owner's assistant, do.
947
989
  - `pipCompaction`: PiP's own summaries when its context is compacted.
948
990
  - `gallery`: the extension gallery, for its own routes.
991
+ - `sessionCleanup` (since 0.30.0): archived sessions' plans, worktrees cleaned up, and sessions removed from the app, for the Session cleanup module.
949
992
  - `toolNames`: the names of the tools that the modules that are on give now (built-in and drop-in), for codemode's Only mode.
950
993
  - `stopToolCall`, `waitsForLimit`, `alertOwner` (since 0.29.0): for the stall watches of Subagents and Agent Teams. They stop one running call, say whether a run waits for a provider's limit, and tell the owner (a notice and a push).
951
994
  - `linkedSessions.activity`, `linkedSessions.stopCall`, `linkedSessions.onLedRun` (since 0.29.0): for the stall watch of Agent Teams. They give the led sessions at work, stop a stuck call of a led session, and call back when a led session starts a run.
@@ -17,6 +17,7 @@ if (typeof host.on !== "function" || typeof web.provide !== "function") {
17
17
  | `session.created` | A session is made: by a person, a fork, a linked start, or a resend. |
18
18
  | `session.renamed` | A session gets a new title. |
19
19
  | `session.archived` | A session is archived, or brought back. |
20
+ | `session.removed` | The owner removed an archived session from the app (since 0.30.0). |
20
21
  | `message.sent` | A person sends Pi a message, a steer or a queued one too. |
21
22
  | `run.started` | Pi starts to work in a session or a subagent. |
22
23
  | `run.ended` | Pi stops: the run finished (`done`), gave up (`failed`), or was stopped (`aborted`). |
@@ -0,0 +1,82 @@
1
+ # Turn notes
2
+
3
+ An extension can add a short note for the model to a person's message. For example, a note can say how much time has passed since the last activity in the session. Use `host.annotateTurns`. Its shape is in [the host reference](reference/host.md#annotateturns).
4
+
5
+ **Experimental, since 0.30.0.** It can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)). A module for an older server checks that `host.annotateTurns` is there, and a gallery entry that needs it sets `minPocket` to `0.30.0`.
6
+
7
+ ## What a note is
8
+
9
+ - A note is a separate entry in the transcript, right after the person's message. The person's message, its attachments, and its sender do not change.
10
+ - Pi Pocket stores the note in the same commit as the message. A restart cannot lose it or write it two times. A retry of a message that is already stored does not ask the annotators again. Two tries of one message at the same moment can both ask them, but only one note is stored.
11
+ - The model reads the note as a user message, on this turn and on all later turns, until compaction or a reset removes it. Compaction treats it like any other entry.
12
+ - The model reads the note's source first: `Note from extension <name>:` on its own line, then the text. `<name>` is the name the module gave to `annotateTurns`, and a note cannot change it. So a note that tries to look like a person or another source still shows where it came from. Pi Pocket writes this label into the stored entry one time, when it stores the note.
13
+ - A note never starts a run. The person's message starts the run, as usual.
14
+ - Pi Pocket writes the text one time and does not compute it again. Nothing older in the transcript changes, so the provider's prompt cache stays valid for each earlier request.
15
+ - The transcript shows the note as "Note for Pi from `name`", with its first 3 lines of text. A tap shows all of it. It never shows as a person's words.
16
+
17
+ ## Which messages get notes
18
+
19
+ Only a message that Pi Pocket can place at once gets notes. That is a message to a session where Pi does not work and nothing is queued.
20
+
21
+ - **A queued message gets no note.** Pi Durable puts a queued message in the context when it is its turn: at the end of the run for a follow-up, or after the tool round for a steer. A note could not go into the context at the same time, so Pi Pocket does not ask the annotators.
22
+ - A message sent with **Interrupt** gets no note, because it stops a run first.
23
+ - Notes come for every message that goes through Pi Pocket's message path: messages that people send in the app, a plan that a person approves, and messages sent for a person by PiP, by a linked session, by `host.sessions.start`, by `host.inbox` (webhooks, the relay), and by PR and repository watches. `turn.via` names what sent a message for a person.
24
+ - Scheduled messages, a message sent again (Resend), reports of background tasks and subagents, and PiP's own conversation get no notes.
25
+
26
+ ## The annotator
27
+
28
+ `annotate(turn)` gets the session, the person, the message's text, when it came (`at`), and the newest time of a message, an answer, or a tool result among the session's last 32 entries (`previousActivityAt`). These entries can come from before a reset. It returns the note's text, or `undefined` for no note. It can be `async`.
29
+
30
+ - Keep it fast. The message waits for the annotators, for 2 seconds at most together. An annotator that is late, throws, or returns more than 4,000 characters adds nothing, and the session shows a warning. The message goes on.
31
+ - `turn.signal` aborts when the 2 seconds end.
32
+ - Several modules can add annotators. Their notes come in the order the modules added them.
33
+ - The note's text is model input. Write it for the model, and do not put a value there that people must not see: everyone in the session can read the note.
34
+
35
+ ## An example: time gaps
36
+
37
+ This module tells the model when a person writes after a long silence.
38
+
39
+ ```typescript title="time-gap.ts"
40
+ /**
41
+ * Time gap: tells Pi how long a session was quiet when a person writes after a long silence.
42
+ */
43
+ import type { Host, Turn, Web } from "./_pocket.d.ts";
44
+
45
+ const HOUR = 3_600_000;
46
+
47
+ /** "About 2 days" or "About 5 hours", or undefined for a gap shorter than 3 hours. */
48
+ function gap(turn: Turn): string | undefined {
49
+ if (turn.previousActivityAt === undefined) {
50
+ return undefined;
51
+ }
52
+
53
+ const hours = (turn.at - turn.previousActivityAt) / HOUR;
54
+
55
+ if (hours < 3) {
56
+ return undefined;
57
+ }
58
+
59
+ const days = Math.round(hours / 24);
60
+
61
+ return hours < 36 ? `About ${Math.round(hours)} hours` : `About ${days} days`;
62
+ }
63
+
64
+ export default function createTimeGap(host: Host, web: Web) {
65
+ // A server older than 0.30.0 has no turn notes: do nothing there.
66
+ if (typeof host.annotateTurns !== "function") {
67
+ return;
68
+ }
69
+
70
+ web.onDispose(
71
+ host.annotateTurns("time-gap", (turn) => {
72
+ const passed = gap(turn);
73
+
74
+ return passed === undefined
75
+ ? undefined
76
+ : `<system-reminder>\n${passed} have passed since the previous message.\n</system-reminder>`;
77
+ }),
78
+ );
79
+ }
80
+ ```
81
+
82
+ The same module is in [examples/time-gap.ts](../examples/time-gap.ts).
@@ -26,6 +26,7 @@ This page is the map. Read all of it, then only the pages that your task needs.
26
26
  | Start sessions, and send messages between them | [Starting and messaging sessions](extensions/linked-sessions.md) |
27
27
  | Start an ordinary session, like New session | [Starting an ordinary session](extensions/sessions.md) |
28
28
  | Give a chat message or a feed's item to a session, as data | [Delivering outside data](extensions/inbox.md) |
29
+ | Add a note for the model to a person's message | [Turn notes](extensions/turn-notes.md) |
29
30
  | Add a kind of connection to the relay (a chat service, a feed) | [Relay connectors](extensions/relay.md) |
30
31
  | Add to the app: routes, a browser module, commands | [Adding to the app](extensions/app.md) |
31
32
  | Name how an input this module sends shows in the transcript | [Adding to the app](extensions/app.md), [`web.presentEntry`](extensions/reference/web.md#presententry) |
package/docs/features.md CHANGED
@@ -10,6 +10,7 @@ The full tour. For setup, see the [README](../README.md).
10
10
  - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. Appearance → **Switch sessions with → Tabs** (off until you turn it on, in each browser) also puts the first nine of those sessions in a strip of segments above the top bar, each in its folder's color: the open one fills, one that works pulses, one that waits for you shows in the warning color, and a tap opens it (the open session takes the ninth place when it is further down the list). Choosing Tabs folds the sidebar to its rail, and Sidebar unfolds it; Ctrl/⌘+B still folds and unfolds it either way. On a phone the strip is the bars alone, and the top bar names the open session. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
11
11
  - **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
12
12
  - **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
13
+ - **Session cleanup** (since 0.30.0, the owner's alone). **Remove and clean up** on an archived session (a held row, a right-click, or selected rows) takes it out of the app for everyone and removes Pi Pocket's own files of it: its worktree (its branch stays), its uploads, and its background logs. Its schedules, background tasks, PR watch, webhooks, repository watches, published artifact links, modules' public page links, and session lessons end too. The confirm says what goes and its size first. The transcript stays in Pi Pocket's database until Pi Durable can remove a conversation; Pi Pocket keeps a list of removed sessions for that. A session where Pi works, or whose worktree has uncommitted changes, stays, and says why; a fork's uploads stay while a fork still shows them. Menu or the launcher → **Clean up archived sessions** looks at the archived sessions not used for 7, 30, or 90 days (or any age): **Remove worktrees** removes their worktrees and keeps the sessions, and **Remove N sessions…** removes them, after the same confirm. A removal cut short by a restart goes on at the next start.
13
14
  - **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
15
  - **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
16
  - **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).
@@ -67,7 +68,7 @@ The full tour. For setup, see the [README](../README.md).
67
68
  - **Roles and invites.** An invite can let someone **steer** or make them **view only** (they read, react, and chat, but cannot send to Pi, approve, or upload). It can cover **every session** or **only this session**, and lasts 15 minutes, an hour, a day, or a week (**Expires after**); either way it works once, and a restart keeps it. Changing what the sheet's invite grants, or how long it lasts, ends the one it showed; **New invite** makes another and leaves the one before working. Only the owner can make an owner invite (**Sign in as me (owner)**): it makes no one new, but signs the device in with the owner's token, so it has full control, works once, and always expires in 15 minutes; rotating the owner token (`--rotate-token`) signs out every device signed in that way, and ends owner invites not yet used. Menu → **People** lists everyone, who is online, and when the others were last here. The owner can change what each person may do or remove them. The session list shows who is in each session, and a dot marks new chat messages.
68
69
  - **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished (or Pi stopped with an error, with why: a run that failed with no answer of its own, as when its context could not be compacted, says so too, and the open session keeps a "Run failed" line until the next run starts; since 0.28.1), Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel or Tailscale Serve, or another tunnel such as ngrok in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`. In a host around Pi Pocket (an app such as Pi Pocket GUI), they come as the app's own notifications, with no https address needed, while the app runs ([docs/embedders.md](embedders.md)).
69
70
  - **Built-in browser.** Menu → **Browser** (or Alt+B, `/browser localhost:5173`, or the globe in the top bar while a page is open; on a phone, a dot on the places button by the message box says so) opens a real Chromium page that runs on the server: beside the conversation on wide screens, full screen on phones. Type an address (`localhost:5173`, `example.com`), or (the owner) tap a row under **Running on this machine** on the start screen; a green dot in the rounded address field marks an open page. Tap, drag to scroll, and type into the page (the keyboard button sends text from a phone). The size button switches between fitting the panel (the page follows the panel when it changes size), desktop, phone, and tablet sizes, and the console button shows the page's logs and errors, with a warning-colored error count. Pi's `browser` tool uses the same page: it opens addresses (dev servers, HTML files on the machine, any site), reads a snapshot of the page's text and controls, clicks, types, takes screenshots it can see, reads the console, and runs JavaScript in the page, while everyone in the session watches. Each session has one page, in a browser context of its own; links that open a new tab open there instead, and dialogs are accepted. Anyone in the session can watch; using the page takes steering rights (and the wheel, while take turns is on), the addresses people open show in the chat, and only the owner opens files from the address bar. The browser reaches what the server reaches, `localhost` and its network included, and Lancet Guard does not check it (see SECURITY.md). A restart closes the pages, and each opens again at its last address and size. Where the panel covers the conversation, Esc closes it, unless the page has the keys (then Alt+B does). In plan mode Pi may look at pages but not click, type, or run scripts in them. It needs Chromium, Chrome, Brave, or Edge on the server (or `PI_POCKET_BROWSER`); the owner can turn it off in Extensions, which closes the panel too.
70
- - **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. `inline: true` (since 0.28.0, one tool; before it a second tool, `artifact_inline`, sent almost the same schema again on every request) is the same store for HTML only (`content` or `edits`, no path, no `type` but `html`): the call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but an `inline: true` call refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `inline` only in sessions whose `artifact` tool has it (PiP's has not), and says that only a direct call shows a card. Sessions from before 0.28.0 keep their `artifact_inline` calls and results as stored, and still show them as cards, also in forks; the model is shown those calls as `artifact` with `inline: true` in its requests, so it does not repeat a tool it is no longer offered. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's.
71
+ - **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. `inline: true` (since 0.28.0, one tool; before it a second tool, `artifact_inline`, sent almost the same schema again on every request) is the same store for HTML only (`content` or `edits`, no path, no `type` but `html`): the call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but an `inline: true` call refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `inline` only in sessions whose `artifact` tool has it (PiP's has not), and says that only a direct call shows a card. Sessions from before 0.28.0 keep their `artifact_inline` calls and results as stored, and still show them as cards, also in forks; the model is shown those calls as `artifact` with `inline: true` in its requests, so it does not repeat a tool it is no longer offered. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's. **Delete** (the bin in the viewer, and on each card of the Artifacts sheet, since 0.30.0) takes an artifact with all its versions, after a confirm: its pages, its share links, the state its page saved, and its design comments go in one commit, so a restart finds it all there or all gone, and the storage drops the older revisions that held them. Its asset files go too once no artifact in any session uses them (a sweep after the delete, run again at startup if a restart cut it off). Cards in replies say it was deleted, also after a reload (the session's view carries the last number of each deleted artifact). A share or saved state made while it is deleted is refused, and edits that Pi sent for a deleted version are refused too. What stays is Pi's own messages: the tool calls that made it still hold the text Pi sent, and the confirm says so. Anyone who steers the session may delete, never a viewer; Pi has no tool to delete. One version alone cannot be deleted, as cards in replies and design comments name versions by number. A fork keeps its own copy. Published again under the same id, it starts at the next number, never one a card names.
71
72
  - **All artifacts.** The rail's artifact button opens every artifact in every session you can see, grouped by session (archived sessions are left out), newest first. Each row shows its type, size, age, and the number of its current (latest) version, as `v3 / 3` of the versions it has (`v1` when it has one). A tap opens that version in its session. The launcher's **All artifacts** opens it too, which is the way on a phone. The list is `GET /api/artifacts`.
72
73
  - **Design.** On by default (Menu → **Extensions** turns it off). A canvas beside the chat for Pi's HTML designs: prototypes, screens, one-pagers, and slide decks. A design is an artifact, so versions, the sandbox, saved state, and share links work as they do for any artifact. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open` (with an artifact's id to open that one). On a wide screen the panel sits beside the chat; on a phone it covers the chat, and the way back keeps the canvas as it was. Since 0.26.0.
73
74
  - **The canvas.** A picker of the session's HTML artifacts (newest first, variations together); the page in the artifact sandbox, at phone (390×844), tablet (820×1180), desktop (1280×800), or a custom size; fit or zoom, and a light, dark, or theme backdrop. A new design that Pi makes opens by itself, unless you are in a mode, have a draft, or it is a variation of the open design.
package/docs/map.md CHANGED
@@ -90,17 +90,20 @@ A module split into parts keeps its name for the part others import, with the re
90
90
  | `watches.ts` | A session's PR watch: the durable task that looks at the PR with `gh` and tells Pi about failed checks, conflicts, and comments that count |
91
91
  | `hooks.ts` | Creates, edits, and removes webhooks. Checks each post's secret or GitHub signature, then sends the post to Pi as a message from the hook's creator. |
92
92
  | `inbox.ts` | `Inbox`, behind `host.inbox`: gives outside data to a session as one person's message. It checks the delivery and the person, delivers once for each key, caps a bucket's messages in an hour, and fences the payload (`fence.ts`). Webhooks and the relay use it. |
93
+ | `turn-notes.ts` | `TurnNotes`, behind `host.annotateTurns` (since 0.30.0): notes extensions add for the model after a person's message, as `pocket.turn-note` entries in the same commit as a message placed at once (an idle session with nothing queued); a queued message gets none. A note is stored once and never recomputed. |
93
94
  | `repo-watches.ts` | Repository watches: PiP's standing orders on a GitHub repository, and the durable task that looks at it and tells PiP or a session what happened |
94
95
  | `github.ts` | GitHub through `gh`: running it unattended, repository and PR names in every form, and whether `gh`'s account can push to a repository |
95
96
  | `memory.ts` | Memory: lessons Pi keeps across sessions, each for a project (a repository with its worktrees, or a folder) or everywhere; the lessons in force for a session, and people's view, writes, and approvals |
96
97
  | `folder-favorites.ts` | Each person's favorite folders (`/api/folder-favorites`): starring and unstarring one in a transaction, and each person's list sent only to their own tabs |
97
98
  | `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`. |
99
+ | `session-cleanup.ts` | Archived sessions cleaned up by the owner: their worktrees removed (`cleanUp`), or the sessions taken out of the app (`remove`) with Pocket's own files, their transcripts left in storage; `pocket.deleted`, the queue of a later purge, and `resume` at start |
98
100
  | `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) |
99
101
  | `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`) |
100
102
  | `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 |
101
103
  | `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 |
102
- | `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 |
104
+ | `app-events.ts` | What happens in the app, for extensions (`host.on`): sessions made, renamed, archived, and removed, messages people send to Pi, and runs that start and end, each after its commit; PiP sends none |
103
105
  | `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) |
106
+ | `artifacts.ts` | Deleting an artifact (`DELETE /api/c/:id/artifacts/:artifact`, anyone who steers): its bodies, shares, saved state, and design comments in one commit (those documents then store a base, which drops the old revisions); `sweepAssets`, which retires asset bytes no artifact names (after each delete and at startup), `keepAssets` for a commit that stores them again, and `nextVersion`, which never reuses a deleted artifact's numbers |
104
107
  | `artifact-state.ts` | What an artifact's page saves for each person (`/api/c/:id/artifact-state/:artifact`): one JSON value per artifact, person, and session, up to 16 KB, with a schema label that makes older values read as none, and a limit on saves; not in Pi's context, and a fork starts with none |
105
108
  | `reveal.ts` | Ctrl+click on a path (`/api/c/:id/reveal`, the owner's): shows it in the file manager of the machine the server runs on, selected in its folder (FileManager1 over D-Bus, else `xdg-open`; `open -R`; `explorer /select,`) |
106
109
  | `extension-sessions.ts` | Ordinary sessions an extension starts (`ExtensionSessions`, `host.sessions` as `SessionsApi` in `host.ts`): a top-level session, like New session, for the person Pi works for in the source, with its model and thinking written in that same commit and its first message sent once; the call's record is an item of `LinkedSessionCallsDoc`, written in the commit that makes the session (since 0.28.0) |
@@ -214,7 +217,7 @@ Outside `src/`: `flake.nix` and `nix/` build Pi Pocket with Nix (`nix/package.ni
214
217
 
215
218
  ## Extensions: `src/server/extensions/`
216
219
 
217
- Each default-exports `(host: PocketHost, web: ExtensionWeb) => Extension | Extension[] | void` (`web` adds to the app: [extensions/app.md](extensions/app.md)) and is installed in this order: `prompt` (system prompt, with where Pi Pocket's docs are), `artifacts` (the `artifact` tool, with `inline: true` for a card in the reply: one store, `publish`, and bundles: `assets`, `removeAssets`, `group`, `kind`; `legacyInline` shows old `artifact_inline` calls to the model as `artifact` calls; `withoutInline` is PiP's), `browser` (browser tool and its prompt section; through `host.browsers`), `diagrams` (Diagrams, on by default: no tools or routes, only the browser client `diagrams` in `diagrams/`: `index.js` renders Mermaid with Pele and math with KaTeX, `style.css` and `math.css` style them; it is the one built-in client that session invitations may load, `isTrustedDiagramsClient` in `extension-web.ts`), `subagents` (subagent tool and its tasks: anchors, reporters, and the courier that sends waiting reports to the parent together; a subagent runs on its session's model, or one the owner allowed, and the app rebuilds the module when that list changes; it waits for tool search, and provides its guide through `web.provide` for the codemode route), `agent-teams` (Agent Teams, off by default: the `team` tool and its prompt section, through `host.linkedSessions`; its browser module `agent-teams.js` describes the tool's calls with `pocket.toolCall`; it imports of Pi Pocket's only types and `model-facts.ts`, a pure helper that formats model facts), `schedules` (schedule tool and its four limits, as settings; installs the schedule task), `background` (the background tool and its one setting, through `host.background`; installs the watch task), `goals` (hook after each answer), `plan` (tool hook and prompt section), `anthropic-subscription` (Claude subscription billing), `guard` (tool hook that asks for approval), `codemode` (codemode tool; a script's calls go through the same hooks; its Mode setting Only hides the other tools with a `wraps` getter over `host.toolNames()`, read at each resolve, and lists them in its prompt section; `tool-search` asks it through `web.provide`, and still lists, finds, and loads the hidden tools that wait; `plan`, `browser`, and `agent-teams` look in `agent.callable` too), `memory` (memory tool and the prompt section of lessons in force; through `host.memory`), `pip` (PiP's tools, prompt, and follow task, through `host.pip`; only PiP's conversation selects it, as `PocketApp`'s settings leave it out of every other conversation's), `triggers` (the PR and repository watch tasks and the `watch_pr` tool, through `host.watches` and `host.repoWatches`; webhooks need it on), `pocket-relay` (Relay, off by default: connectors that bring chat messages and feed items to a session through `host.inbox`, and the `relay_reply` and `relay_fetch` tools. `pocket-relay.ts` has its routes under `/api/x/pocket-relay/` (the owner's), the tool, its prompt section, and a service for drop-in connectors; `pocket-relay/runtime.ts` the store, runners, delivery queue, limits, and reply; `pocket-relay/types.ts` the connector API ([extensions/relay.md](extensions/relay.md)); `pocket-relay/files.ts` the checks of the files Pi sends (`relay_reply`'s `files`) and the names of those it fetches (`relay_fetch`); `pocket-relay/connectors/` the kinds (`discord.ts`, `telegram.ts`, `slack.ts`, `matrix.ts`, `http.ts`, `rss.ts`); and `pocket-relay/index.js` with `style.css` the owner's sheet), `gallery` (the extension gallery's owner-only routes under `/api/x/gallery/`, through `host.gallery`, and its twice-daily look for revoked versions; it installs `pocket-gallery`, which tells the web app it is on), `session-tags` (Session tags, off by default: its `x.session-tags.tags` document, routes that check ids with `request.sessions()`, and its browser folder `session-tags/`, which uses the session list's extension points; it imports nothing of Pi Pocket's but types, as a drop-in would), `ask` (Ask: Pi's `ask` tool and its prompt section, questions with answers to pick on a card through `host.ask`; subagents do not get it, and plan mode lets it run), `ask-someone` (Ask someone, off by default: the `ask_someone` tool, which saves a draft question in its `x.ask-someone.questions` document; routes to edit, share, and end them; a public page (`web.publicPage`) for one answer through each link; and its browser folder `ask-someone/`; it imports nothing of Pi Pocket's but types), `updates` (Updates of Pi Pocket itself: owner-only routes under `/api/x/updates/`, through `host.updates`, its three settings (look, install by itself, beta updates), the look every 6 hours and the install by itself, and its browser folder `updates/`, the menu row, launcher action, and sheet, which says in words how the copy was installed and shows the hints that the server gives for a local or npx install), `design` (Design mode's workspace: its routes under `/api/x/design/` for comments, tweaks, "go back to this one", and the designs list, the `pocket.design-comments` document, the `/design-open` command, and the agent side from `../design/index.ts` (tools, prompt guide, export route); its browser folder `design/` is the canvas: only `index.js` (the store, the rail button, the launcher actions, the command, and a loading state), `paths.js`, and `state.js` (the workspace's one store) load at app start; `app.js` (the workspace, with `style.css`) loads when the panel first opens, and `docks.js`, `views.js`, and the System view (`system-ui.js`, with `system.css`) when first used; `unsaved.js` carries the System view's unsaved count and save; `workspace.js` is the picker, toolbar, and modes, `canvas.js` the frame and its bridge, `docks.js` the versions, comments, text edits, and tweaks, `system-view.js`, `system-sections.js`, `system-widgets.js`, `system-actions.js`, `system-data.js`, and `system-preview.js` the System view, `check.js` the Check tab, `picker.js` the design picker, `views.js` compare, the variations grid, the slide strip, and present mode, `data.js` what it asks of the server, `parts.js` small pieces, `style.css` the workspace's sheet, and `system.css` the System view's; `devices.js`, `tweaks.js`, `edits.js`, `messages.js`, `comments.js`, `system.js`, `color.js`, and `specimen.js` are pure helpers (`color.js`, with `color.d.ts`, is also the server's color math, through `../design/color.ts`); `system-routes.ts` and `system-api.ts` are the System view's routes (`system`, `system/check`, `system/docs`, `system/export`) and the engines they call; it imports the app's own `/store.js` and `/artifact-bridge.js`), and `tool-search` (the `tool_search` tool, and the list of tools that wait to be searched for: `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools; it marks them deferred with `wrapTool`, and shows their prompt sections only once one of their tools is loaded, with `wrapSection` (the design guide's section with any of the three design tools); on a model whose provider takes tool changes in the messages it loads a tool into the list, and on any other it gives the tool's description in the search result and Pi calls it from a codemode script, so the list, and the prompt cache that starts with it, never change; turn it off and they are offered every time).
220
+ Each default-exports `(host: PocketHost, web: ExtensionWeb) => Extension | Extension[] | void` (`web` adds to the app: [extensions/app.md](extensions/app.md)) and is installed in this order: `prompt` (system prompt, with where Pi Pocket's docs are), `artifacts` (the `artifact` tool, with `inline: true` for a card in the reply: one store, `publish`, and bundles: `assets`, `removeAssets`, `group`, `kind`; `legacyInline` shows old `artifact_inline` calls to the model as `artifact` calls; `withoutInline` is PiP's), `browser` (browser tool and its prompt section; through `host.browsers`), `diagrams` (Diagrams, on by default: no tools or routes, only the browser client `diagrams` in `diagrams/`: `index.js` renders Mermaid with Pele and math with KaTeX, `style.css` and `math.css` style them; it is the one built-in client that session invitations may load, `isTrustedDiagramsClient` in `extension-web.ts`), `subagents` (subagent tool and its tasks: anchors, reporters, and the courier that sends waiting reports to the parent together; a subagent runs on its session's model, or one the owner allowed, and the app rebuilds the module when that list changes; it waits for tool search, and provides its guide through `web.provide` for the codemode route), `agent-teams` (Agent Teams, off by default: the `team` tool and its prompt section, through `host.linkedSessions`; its browser module `agent-teams.js` describes the tool's calls with `pocket.toolCall`; it imports of Pi Pocket's only types and `model-facts.ts`, a pure helper that formats model facts), `schedules` (schedule tool and its four limits, as settings; installs the schedule task), `background` (the background tool and its one setting, through `host.background`; installs the watch task), `goals` (hook after each answer), `plan` (tool hook and prompt section), `anthropic-subscription` (Claude subscription billing), `guard` (tool hook that asks for approval), `codemode` (codemode tool; a script's calls go through the same hooks; its Mode setting Only hides the other tools with a `wraps` getter over `host.toolNames()`, read at each resolve, and lists them in its prompt section; `tool-search` asks it through `web.provide`, and still lists, finds, and loads the hidden tools that wait; `plan`, `browser`, and `agent-teams` look in `agent.callable` too), `memory` (memory tool and the prompt section of lessons in force; through `host.memory`), `pip` (PiP's tools, prompt, and follow task, through `host.pip`; only PiP's conversation selects it, as `PocketApp`'s settings leave it out of every other conversation's), `triggers` (the PR and repository watch tasks and the `watch_pr` tool, through `host.watches` and `host.repoWatches`; webhooks need it on), `pocket-relay` (Relay, off by default: connectors that bring chat messages and feed items to a session through `host.inbox`, and the `relay_reply` and `relay_fetch` tools. `pocket-relay.ts` has its routes under `/api/x/pocket-relay/` (the owner's), the tool, its prompt section, and a service for drop-in connectors; `pocket-relay/runtime.ts` the store, runners, delivery queue, limits, and reply; `pocket-relay/types.ts` the connector API ([extensions/relay.md](extensions/relay.md)); `pocket-relay/files.ts` the checks of the files Pi sends (`relay_reply`'s `files`) and the names of those it fetches (`relay_fetch`); `pocket-relay/connectors/` the kinds (`discord.ts`, `telegram.ts`, `slack.ts`, `matrix.ts`, `http.ts`, `rss.ts`); and `pocket-relay/index.js` with `style.css` the owner's sheet), `gallery` (the extension gallery's owner-only routes under `/api/x/gallery/`, through `host.gallery`, and its twice-daily look for revoked versions; it installs `pocket-gallery`, which tells the web app it is on), `session-cleanup` (Session cleanup, the owner's: routes under `/api/x/session-cleanup/` (`plan`, `clean-up`, `remove`) through `host.sessionCleanup`, and its browser folder `session-cleanup/`: Remove and clean up as a session action, and the Clean up archived sessions sheet in the menu and the launcher), `session-tags` (Session tags, off by default: its `x.session-tags.tags` document, routes that check ids with `request.sessions()`, and its browser folder `session-tags/`, which uses the session list's extension points; it imports nothing of Pi Pocket's but types, as a drop-in would), `ask` (Ask: Pi's `ask` tool and its prompt section, questions with answers to pick on a card through `host.ask`; subagents do not get it, and plan mode lets it run), `ask-someone` (Ask someone, off by default: the `ask_someone` tool, which saves a draft question in its `x.ask-someone.questions` document; routes to edit, share, and end them; a public page (`web.publicPage`) for one answer through each link; and its browser folder `ask-someone/`; it imports nothing of Pi Pocket's but types), `updates` (Updates of Pi Pocket itself: owner-only routes under `/api/x/updates/`, through `host.updates`, its three settings (look, install by itself, beta updates), the look every 6 hours and the install by itself, and its browser folder `updates/`, the menu row, launcher action, and sheet, which says in words how the copy was installed and shows the hints that the server gives for a local or npx install), `design` (Design mode's workspace: its routes under `/api/x/design/` for comments, tweaks, "go back to this one", and the designs list, the `pocket.design-comments` document, the `/design-open` command, and the agent side from `../design/index.ts` (tools, prompt guide, export route); its browser folder `design/` is the canvas: only `index.js` (the store, the rail button, the launcher actions, the command, and a loading state), `paths.js`, and `state.js` (the workspace's one store) load at app start; `app.js` (the workspace, with `style.css`) loads when the panel first opens, and `docks.js`, `views.js`, and the System view (`system-ui.js`, with `system.css`) when first used; `unsaved.js` carries the System view's unsaved count and save; `workspace.js` is the picker, toolbar, and modes, `canvas.js` the frame and its bridge, `docks.js` the versions, comments, text edits, and tweaks, `system-view.js`, `system-sections.js`, `system-widgets.js`, `system-actions.js`, `system-data.js`, and `system-preview.js` the System view, `check.js` the Check tab, `picker.js` the design picker, `views.js` compare, the variations grid, the slide strip, and present mode, `data.js` what it asks of the server, `parts.js` small pieces, `style.css` the workspace's sheet, and `system.css` the System view's; `devices.js`, `tweaks.js`, `edits.js`, `messages.js`, `comments.js`, `system.js`, `color.js`, and `specimen.js` are pure helpers (`color.js`, with `color.d.ts`, is also the server's color math, through `../design/color.ts`); `system-routes.ts` and `system-api.ts` are the System view's routes (`system`, `system/check`, `system/docs`, `system/export`) and the engines they call; it imports the app's own `/store.js` and `/artifact-bridge.js`), and `tool-search` (the `tool_search` tool, and the list of tools that wait to be searched for: `browser`, `subagent`, `background`, `schedule`, `watch_pr`, `ask_someone`, and the design tools; it marks them deferred with `wrapTool`, and shows their prompt sections only once one of their tools is loaded, with `wrapSection` (the design guide's section with any of the three design tools); on a model whose provider takes tool changes in the messages it loads a tool into the list, and on any other it gives the tool's description in the search result and Pi calls it from a codemode script, so the list, and the prompt cache that starts with it, never change; turn it off and they are offered every time).
218
221
 
219
222
  ## Web: `web/` (Preact and htm, no build)
220
223
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.30.0-beta.3",
3
+ "version": "0.30.0-beta.4",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-pocket",
9
- "version": "0.30.0-beta.3",
9
+ "version": "0.30.0-beta.4",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "@earendil-works/chord": "1.6.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.30.0-beta.3",
3
+ "version": "0.30.0-beta.4",
4
4
  "description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
5
5
  "keywords": [
6
6
  "pi",
@@ -1,6 +1,6 @@
1
1
  /**
2
- * What happens in the app, for extensions (`host.on`, since 0.22.0, experimental): sessions made, renamed, and
3
- * archived, messages people send to Pi, and runs that start and end. Each comes after its commit, so what it names is
2
+ * What happens in the app, for extensions (`host.on`, since 0.22.0, experimental): sessions made, renamed, archived,
3
+ * and removed, messages people send to Pi, and runs that start and end. Each comes after its commit, so what it names is
4
4
  * stored. PiP's conversations are private and send none.
5
5
  *
6
6
  * A listener runs after the change, never in its way: one that throws or rejects is logged, and the others run.
@@ -18,6 +18,8 @@ export interface AppEvents {
18
18
  };
19
19
  "session.renamed": { conversationId: number; title: string };
20
20
  "session.archived": { conversationId: number; archived: boolean };
21
+ /** The owner removed an archived session from the app (since 0.30.0): its id is never shown again. */
22
+ "session.removed": { conversationId: number };
21
23
  /**
22
24
  * A person sent Pi a message (also a steer or a queued one): who, and its words as stored (hidden values hidden,
23
25
  * attachments left out). `via` names what sent it for them: PiP, a schedule, a webhook.
@@ -50,6 +52,7 @@ export const APP_EVENTS: readonly AppEventName[] = [
50
52
  "session.created",
51
53
  "session.renamed",
52
54
  "session.archived",
55
+ "session.removed",
53
56
  "message.sent",
54
57
  "run.started",
55
58
  "run.ended",