pi-pocket 0.28.0-beta.3 → 0.28.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 (46) hide show
  1. package/README.md +1 -1
  2. package/contrib/systemd/pi-pocket@.service +1 -1
  3. package/docs/architecture.md +2 -2
  4. package/docs/extensions/linked-sessions.md +20 -4
  5. package/docs/extensions/policies/api-stability.md +3 -1
  6. package/docs/extensions/policies/core-or-extension.md +1 -1
  7. package/docs/extensions/reference/api-versions.md +2 -0
  8. package/docs/extensions/reference/host.md +42 -7
  9. package/docs/extensions/services-settings.md +8 -8
  10. package/docs/features.md +1 -1
  11. package/docs/map.md +66 -64
  12. package/docs/systemd.md +1 -1
  13. package/npm-shrinkwrap.json +2 -2
  14. package/package.json +1 -1
  15. package/src/launcher/access.ts +8 -1
  16. package/src/launcher/main.ts +101 -41
  17. package/src/launcher/options.ts +1 -1
  18. package/src/launcher/serve.ts +51 -22
  19. package/src/server/app-events.ts +11 -1
  20. package/src/server/app.ts +162 -15
  21. package/src/server/background.ts +62 -29
  22. package/src/server/build.ts +1 -1
  23. package/src/server/design/scan-facts.ts +1 -0
  24. package/src/server/design/scan-import-eval.ts +15 -8
  25. package/src/server/design/scan-import.ts +15 -3
  26. package/src/server/design/scan.ts +18 -15
  27. package/src/server/design/system-types.ts +6 -0
  28. package/src/server/design/system.ts +106 -8
  29. package/src/server/design/tokens-resync.ts +542 -0
  30. package/src/server/design/tokens.ts +34 -3
  31. package/src/server/docs.ts +30 -1
  32. package/src/server/entry-presentation.ts +20 -0
  33. package/src/server/guides/design.md +1 -0
  34. package/src/server/host.ts +19 -0
  35. package/src/server/linked-sessions.ts +214 -2
  36. package/src/server/room.ts +1 -1
  37. package/types/pocket.d.ts +44 -2
  38. package/web/index.html +50 -0
  39. package/web/running-board.js +107 -32
  40. package/web/sheets/find.js +8 -2
  41. package/web/store.js +1 -1
  42. package/web/style.css +14 -0
  43. package/web/text-hash.d.ts +2 -0
  44. package/web/{fingerprint.js → text-hash.js} +2 -1
  45. package/web/transcript.js +10 -0
  46. package/web/fingerprint.d.ts +0 -2
package/README.md CHANGED
@@ -82,7 +82,7 @@ Choose a mode in the launcher, or pass `--access`:
82
82
  | `tailscale` | Your tailnet | Plain http on the tailnet address |
83
83
  | `tailscale-serve` | Your tailnet | https at the tailnet name; needs `tailscale` 1.52 or newer |
84
84
 
85
- `tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet. It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. `--host` cannot be combined with it: serve always listens on `127.0.0.1` and lets tailscaled reach it. For another tunnel (ngrok), choose `local` and point it at port 8787.
85
+ `tailscale-serve` needs the `tailscale` command on your `PATH`, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet, and, when the launcher does not run as root, that user as tailscaled's operator (`sudo tailscale set --operator=$USER`). It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. `--host` cannot be combined with it: serve always listens on `127.0.0.1` and lets tailscaled reach it. For another tunnel (ngrok), choose `local` and point it at port 8787.
86
86
 
87
87
  Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `--host` overrides the address a named mode would listen on, and one launcher runs per data folder (a second one says which pid holds it). `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_SESSION_CACHE=off` keeps browsers from saving the sessions they open on the device (IndexedDB), so that they keep them in each tab's memory only; it is on by default. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)).
88
88
 
@@ -3,7 +3,7 @@
3
3
  [Unit]
4
4
  Description=Pi Pocket (%i access)
5
5
  Documentation=https://github.com/TannerMidd/pi-pocket/blob/main/docs/systemd.md
6
- Wants=network-online.target
6
+ Wants=network-online.target tailscaled.service
7
7
  After=network-online.target tailscaled.service
8
8
 
9
9
  [Service]
@@ -18,7 +18,7 @@ Some state lives in this process alone, and a restart forgets it. For example:
18
18
  - who is connected, typing, or away;
19
19
  - which tool calls wait for approval;
20
20
  - the browser's pages;
21
- - when each run ended, which peek tiles and session-list squares use, and whether its last run failed;
21
+ - when each run ended, which peek tiles and session-list squares use (why a session's last run failed is kept: `pocket.run-failure`);
22
22
  - provider sign-ins in progress;
23
23
  - the edit and write calls Changes found in each session's history, so a look reads only the entries added since.
24
24
 
@@ -173,7 +173,7 @@ A full view for a tab of protocol 4 has the order of every entry in the active c
173
173
 
174
174
  A tab of protocol 5 gets those entries light at first (`lightEntry` in `projection.ts`, marked `partial`): without a thought's words, with a tool's input and output cut to their first 300 characters, and without large details. That is what shows only when a step is opened, and most of a session's weight: the first view of a long session goes from hundreds of kilobytes to tens. The server does not count a light entry as sent, so the update right after the first view (`Room.push`) brings it whole. A long poll answers the first time as soon as the first view is built, so the whole entries come in the next answer. Until then, a call's line may say nothing of its outcome (a result of 300 characters or fewer, with small details, is never made light: it comes whole, so its line can show it), and a thought does not open.
175
175
 
176
- A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/fingerprint.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
176
+ A tab of protocol 6 keeps the sessions it leaves (`keptViews` in `web/store.js`: the newest 1,500 entries of each, as many sessions as fit in 16 million characters of JSON, about 25 MB once parsed, the one left longest ago dropped first), and shows the one it goes back to at once, before the server answers. It tells the server what it kept (`have=<from>.<count>.<key>.<build>`): the first `count` ids of the order, as a fingerprint (`key`, from `web/text-hash.js`), whose entries it has whole from `from` on, as a server of build `build` sent them. The build (`src/server/build.ts`) is a hash of the server's code and its package: an entry is as that code projects it, so what a tab kept is good across a restart with the same code, and not across new code. The server checks `have` against the session (`Room.push`): its own build, and an order that still starts with those ids (no compaction since). If it fits, the full view counts those entries as sent, and its order is only what comes after them, with `orderFrom` where it goes on: a session that did not change sends no entries and no order. If it does not, the tab gets the full view any tab gets. An update to a tab of protocol 6 likewise sends only the end of the order when entries were only added: a long session's order has thousands of ids, and each entry added sent them all again. A view whose `orderFrom` does not fit the order the tab has, which should not happen, makes the tab drop what it kept and connect again. The tab keeps only views a server of the running build sent whole. It forgets them all when the server runs other code, when the person's rights change or another person signs in, or when a session leaves the list; and a session's own when the server says it is missing. Each of these but the last also keeps the view on screen from being kept when the tab leaves it: after a reconnect the list can come first, and a tab that leaves at once never hears that the session is missing.
177
177
 
178
178
  The browser also keeps those sessions on the device (`web/session-cache.js`, IndexedDB), for every tab of it: about 100 MB of JSON in all (`DEVICE_CHARS`), the session used longest ago dropped first. A session saved there shows at once after a reload, a tab the system closed in the background, or a restart of a server with the same build, and a tab opens a session its memory no longer holds from there in a moment. A tab that starts reads the ones used last back into its memory while it is idle, as many as its memory keeps, so that going to them after a reload is as quick as before it. A tab saves a session there as it leaves it, and the one it shows a few seconds after it last changed and as the page goes to the background. Each record names its build and whose it is (a fingerprint of the person's id, role, and shared sessions): a tab uses only one of its server's build and of the person signed in with the same rights, and the server checks `have` as for one from memory. What the device kept goes when the tab forgets what it kept (above), on sign-out, and, per session, when the server says it is missing. `PI_POCKET_SESSION_CACHE=off` keeps sessions off devices (`hello.server.deviceCache` false): tabs keep them in memory only, and drop what their browser kept on the device.
179
179
 
@@ -1,6 +1,6 @@
1
1
  # Starting and messaging sessions
2
2
 
3
- A tool can start a session from the session that it runs in, and send messages between such sessions. Agent Teams does this ([agent-teams.ts](../../src/server/extensions/agent-teams.ts)). Use `host.linkedSessions`. Its members are in [the host reference](reference/host.md).
3
+ A tool can start a session from the session that it runs in, send messages between such sessions, and stop or archive one. Agent Teams does this ([agent-teams.ts](../../src/server/extensions/agent-teams.ts)). A team or orchestration extension uses the same calls. Use `host.linkedSessions`. Its members are in [the host reference](reference/host.md).
4
4
 
5
5
  **Experimental** in 0.14: it can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)).
6
6
 
@@ -44,18 +44,34 @@ Check for `web.conversationRoute` at runtime and set gallery `minPocket: "0.16.0
44
44
  - `send` returns when the session takes the message, not when it answers.
45
45
  - The session that gets the message reads it in a fence. Words before it say that another session's agent wrote it, that it is a request and not an order from a person, and which address to reply to.
46
46
 
47
+ ## Stop a run
48
+
49
+ `stop(source, { to }, key)` stops the run of the linked session at the address `to`, and withdraws what waits in its queue. Stopping is the safe direction: it needs the same access as `send`, including the turn and room under the spend limit.
50
+
51
+ - When the session is idle, it has no run to stop: the call only withdraws what waits in its queue.
52
+ - It returns `{ busy }`. `busy` is true when the session was working.
53
+ - Since 0.28.0. An older Pi Pocket has no `stop`, so a module checks for it and sets `minPocket` to `0.28.0` when it needs it.
54
+
55
+ ## Archive a session
56
+
57
+ `archive(source, { to, archived? }, key)` archives the linked session at the address `to`. With `archived: false`, it brings the session back. Without `archived`, it archives.
58
+
59
+ - It returns `{ archived, repeating }`. `archived` says whether the session is archived now. `repeating` is how many of its repeating schedules keep running: an archive does not stop them.
60
+ - It needs the same access as `send`.
61
+ - Since 0.28.0, with the same check as `stop`.
62
+
47
63
  ## List the sessions
48
64
 
49
65
  `list(source)` gives the sessions linked to the source, at any distance, that the person whom Pi works for can see.
50
66
 
51
67
  - Each one has an `address` of the source's own, so no session's id goes into the source's transcript.
52
- - Each one has its title, folder, and state only when all the people who see the source also see it.
68
+ - Each one has its title, folder, and state only when all the people who see the source also see it. Since 0.28.0 that state includes `failed`: why its last run gave up, the same short line the session list shows, and only while that failure stands. A later run clears it. A run that was stopped is not a failure.
53
69
 
54
70
  Addresses belong to the session that has them. A fork starts with none, so it leaves the team: the addresses in the history that it copied do not work there.
55
71
 
56
72
  ## Who it acts for
57
73
 
58
- `start` and `send` act for the person whom Pi works for in the source. They need that person's access and right to steer. To start a session, that person must also have access to all sessions.
74
+ `start`, `send`, `stop`, and `archive` act for the person whom Pi works for in the source. They need that person's access and right to steer. To start a session, that person must also have access to all sessions. `stop` and `archive` reach only a session of this team that the person can see.
59
75
 
60
76
  Pi Pocket refuses them while the source is in plan mode, past a spend limit, or while another person has the turn. `send` also needs the turn, and room under the spend limit, in the target session.
61
77
 
@@ -73,6 +89,6 @@ Pi Pocket keeps a team small. Past these limits ([Limits](reference/limits.md#li
73
89
 
74
90
  ## Replays
75
91
 
76
- Give a `key` that stays the same when the call runs again: `${api.taskId}:${api.callId}`. A start or a send with a key that Pi Pocket saw before returns what the first call returned. So a replay makes one session, and sends one message. Pi Pocket keeps the record of a key for a limited time, and for a limited number of calls ([limits](reference/limits.md#linked-sessions)).
92
+ Give a `key` that stays the same when the call runs again: `${api.taskId}:${api.callId}`. A call with a key that Pi Pocket saw before returns what the first call returned, and does not act again. So a replay makes one session, sends one message, stops one run, and archives once. A repeated `stop` returns the first call's `{ busy }`. A repeated `archive` returns the first call's `{ archived, repeating }`, not a state someone changed later. Pi Pocket keeps the record of a key for a limited time, and for a limited number of calls ([limits](reference/limits.md#linked-sessions)).
77
93
 
78
94
  The errors say what is wrong. They do not tell Pi what to do about it: your tool tells Pi that.
@@ -45,7 +45,7 @@ These members are public:
45
45
  - `roleOf(personId)` (experimental, since 0.27.0)
46
46
  - `skillPaths()`, `skills(cwd)`
47
47
  - `heldBack(conversationId)`, `onLimitsChanged(listener)`
48
- - `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental))
48
+ - `linkedSessions`: `start`, `send`, `list` (experimental in 0.14, see [Experimental](#experimental)); `stop`, `archive` (experimental, since 0.28.0)
49
49
  - `text`: `quoted`, `defang`
50
50
  - `thinkingLevels`
51
51
  - `fetchPublic(url, init)` (experimental, since 0.20.0)
@@ -168,6 +168,8 @@ Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` fi
168
168
 
169
169
  Since 0.28.0, `web.presentEntry` and `pocket.entryPresentation` are experimental, with `PresentEntry`; so is `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage`. A module names how an input it sends shows. The model still reads that message in full. Since then too, `pocket.messages` leaves out an input stored as a module's own kind: before, such an input was not a message in the transcript at all.
170
170
 
171
+ Since 0.28.0, `run.ended` carries `outcome` (`done`, `failed`, or `aborted`) and, when the run gave up, `failure`: the same short line the session list shows. `LinkedSession.failed` carries that line for a linked session's last run, with the same audience rule as its title, and only while the failure stands. Both are experimental.
172
+
171
173
  Since 0.20.0, the session list's extension points are experimental: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, and `sessionSearch`, `WebRequest.sessions`, and their types. So is `pocket.composerKey`, with `ComposerKeySpec` and `ComposerBox`, and so are `pocket.onConversation`, `messages`, and `reveal`, with `MessagesOptions`, `MessagePage`, and `MessageInfo`. So are `host.registerModelProvider`, and `host.fetchPublic` with `PublicFetchInit`.
172
174
 
173
175
  ### Deprecated
@@ -54,7 +54,7 @@ Ask these questions in this order. The first "yes" gives the answer.
54
54
 
55
55
  ### Linked sessions and Agent Teams
56
56
 
57
- - **Core: linked sessions** (`linked-sessions.ts`, `host.linkedSessions`). Core starts a linked session, carries messages, and lists the sessions. It acts with the rights of the person Pi works for. It refuses work in plan mode. It counts the cost of the team against the budget of the top session. It stops a team at its [limits](../reference/limits.md#linked-sessions) of sessions, and of messages with no message from a person. It uses keys, so a replay acts once. It gives sessions addresses, so no session ID goes into a transcript.
57
+ - **Core: linked sessions** (`linked-sessions.ts`, `host.linkedSessions`). Core starts a linked session, carries messages, lists the sessions, and stops or archives one of the team. It acts with the rights of the person Pi works for. It refuses work in plan mode. It counts the cost of the team against the budget of the top session. It stops a team at its [limits](../reference/limits.md#linked-sessions) of sessions, and of messages with no message from a person. It uses keys, so a replay acts once. It gives sessions addresses, so no session ID goes into a transcript.
58
58
  - **Extension: Agent Teams** (`extensions/agent-teams.ts` and `agent-teams.js`). The `team` tool, its words to Pi, and how its calls show. It is off by default. At run time it uses only `host` and `web`, as a drop-in does.
59
59
  - **Why:** pull request #84 first put Agent Teams in core. In 0.14 the mechanism stayed in core, because it decides permissions, stored data, and spend (C1 to C3). The workflow became a built-in extension (C6, C7). Another team workflow can use the same linked sessions.
60
60
 
@@ -75,6 +75,7 @@ Each member in the reference has its own Since line. These parts came together:
75
75
  | `pocket.panel` and `pocket.status` (experimental) | 0.19.0 |
76
76
  | Slots: `pocket.topbar`, `composerButton`, `replyAction`, `insertText`, `arrange` (experimental) | 0.19.0 |
77
77
  | `cwd` in `host.linkedSessions.start` and the human-bound `linkedSessions.start` | 0.19.0 |
78
+ | `stop` and `archive` on `host.linkedSessions` (experimental) | 0.28.0 |
78
79
  | The session list: `pocket.sessionChips`, `sessionAction`, `sessionFilter`, `sessionSearch`, and `WebRequest.sessions` (experimental) | 0.20.0 |
79
80
  | `host.registerModelProvider` (experimental) | 0.20.0 |
80
81
  | `host.fetchPublic` (experimental) | 0.20.0 |
@@ -89,3 +90,4 @@ Each member in the reference has its own Since line. These parts came together:
89
90
  | The page's scroll position: `scroll` in the `host.browser` snapshot (experimental) | 0.27.0 |
90
91
  | Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
91
92
  | Read-only conversation and descendant usage: `ConversationWebRequest.conversationUsage` (experimental) | 0.28.0 |
93
+ | How a run stopped: `outcome` and `failure` on `run.ended`, and `failed` on a linked session (experimental) | 0.28.0 |
@@ -216,9 +216,9 @@ Calls `listener` each time something happens in the app: a session is made, rena
216
216
 
217
217
  ```typescript
218
218
  web.onDispose(
219
- host.on("run.ended", ({ conversationId, session }) => {
220
- if (conversationId === session) {
221
- counts.set(session, (counts.get(session) ?? 0) + 1);
219
+ host.on("run.ended", ({ conversationId, session, outcome, failure }) => {
220
+ if (conversationId === session && outcome === "failed") {
221
+ log.push({ session, failure });
222
222
  }
223
223
  }),
224
224
  );
@@ -391,7 +391,7 @@ readonly linkedSessions: LinkedSessions;
391
391
 
392
392
  Since 0.14.0 · Experimental
393
393
 
394
- Lets a tool start sessions from the session that it runs in, and send messages between them, as Agent Teams does. A linked session is an ordinary session. [Starting and messaging sessions](../linked-sessions.md) tells you how they work, what they cannot do, and how to call them.
394
+ Lets a tool start sessions from the session that it runs in, send messages between them, and stop or archive one, as Agent Teams does. A team or orchestration extension uses the same calls. A linked session is an ordinary session. [Starting and messaging sessions](../linked-sessions.md) tells you how they work, what they cannot do, and how to call them.
395
395
 
396
396
  Each call acts as the person that Pi works for in `source`, and that person's checks apply. Give each call a `key` that stays the same when the call runs again, such as `${api.taskId}:${api.callId}`. A second call with the same `key` does nothing again: it returns what the first call returned.
397
397
 
@@ -431,6 +431,34 @@ Sends `message` to the linked session at the address `to`. Without `steer`, the
431
431
 
432
432
  The session that gets the message reads it between tags. Words before it say that the agent of another session wrote it, and that it is a request, not a person's order. They also give the address to reply to.
433
433
 
434
+ #### `linkedSessions.stop`
435
+
436
+ ```ts
437
+ stop(
438
+ source: ConversationId,
439
+ request: { to: string },
440
+ key: string,
441
+ ): Promise<{ busy: boolean }>;
442
+ ```
443
+
444
+ Since 0.28.0 · Experimental
445
+
446
+ Stops the run of the linked session at the address `to`, and withdraws what waits in its queue. When the session is idle, it has no run to stop, and the call only withdraws what waits in its queue. `busy` is true when it was working. It needs the same access as `send`, and it reaches only a session of this team. An older Pi Pocket has no `stop`: check for it, and set `minPocket` to `0.28.0` when you need it.
447
+
448
+ #### `linkedSessions.archive`
449
+
450
+ ```ts
451
+ archive(
452
+ source: ConversationId,
453
+ request: { to: string; archived?: boolean },
454
+ key: string,
455
+ ): Promise<{ archived: boolean; repeating: number }>;
456
+ ```
457
+
458
+ Since 0.28.0 · Experimental
459
+
460
+ Archives the linked session at the address `to`. With `archived: false`, it brings the session back. Without `archived`, it archives. `archived` in the result says whether the session is archived now. `repeating` is how many of its repeating schedules keep running: an archive does not stop them. It needs the same access as `send`. An older Pi Pocket has no `archive`.
461
+
434
462
  #### `linkedSessions.list`
435
463
 
436
464
  ```ts
@@ -450,6 +478,7 @@ interface LinkedSession {
450
478
  cwd?: string;
451
479
  busy?: boolean;
452
480
  archived?: boolean;
481
+ failed?: string;
453
482
  }
454
483
  ```
455
484
 
@@ -458,7 +487,8 @@ Since 0.14.0 · Experimental
458
487
  A linked session, as `list` gives it.
459
488
 
460
489
  - `address`: the address that the asking session uses for it. It is never the session's id.
461
- - `title`, `cwd` (its folder), `busy` (Pi works in it now), and `archived`: these are there only when all the people who see the asking session see this session too.
490
+ - `title`, `cwd` (its folder), `busy` (Pi works in it now), `archived`, and `failed`: these are there only when all the people who see the asking session see this session too.
491
+ - `failed` (since 0.28.0): why its last run gave up, the same short line the session list shows. It is there only while that failure stands. A later run clears it, and a run that was stopped leaves none.
462
492
 
463
493
  ## Types for events
464
494
 
@@ -483,7 +513,12 @@ interface AppEvents {
483
513
  via?: string;
484
514
  };
485
515
  "run.started": { conversationId: number; session: number };
486
- "run.ended": { conversationId: number; session: number };
516
+ "run.ended": {
517
+ conversationId: number;
518
+ session: number;
519
+ outcome: "done" | "failed" | "aborted";
520
+ failure?: string;
521
+ };
487
522
  }
488
523
  ```
489
524
 
@@ -494,7 +529,7 @@ What each event's listener gets.
494
529
  - `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.
495
530
  - `session.renamed`, `session.archived`: its new title, or whether it is archived now.
496
531
  - `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.
497
- - `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.
532
+ - `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.
498
533
 
499
534
  ### `AppEventName`
500
535
 
@@ -12,14 +12,14 @@ if (typeof host.on !== "function" || typeof web.provide !== "function") {
12
12
 
13
13
  `host.on(event, listener)` calls `listener` each time something happens in the app ([reference](reference/host.md#on)):
14
14
 
15
- | Event | When |
16
- | ------------------ | -------------------------------------------------------------------- |
17
- | `session.created` | A session is made: by a person, a fork, a linked start, or a resend. |
18
- | `session.renamed` | A session gets a new title. |
19
- | `session.archived` | A session is archived, or brought back. |
20
- | `message.sent` | A person sends Pi a message, a steer or a queued one too. |
21
- | `run.started` | Pi starts to work in a session or a subagent. |
22
- | `run.ended` | Pi stops. |
15
+ | Event | When |
16
+ | ------------------ | ------------------------------------------------------------------------------------ |
17
+ | `session.created` | A session is made: by a person, a fork, a linked start, or a resend. |
18
+ | `session.renamed` | A session gets a new title. |
19
+ | `session.archived` | A session is archived, or brought back. |
20
+ | `message.sent` | A person sends Pi a message, a steer or a queued one too. |
21
+ | `run.started` | Pi starts to work in a session or a subagent. |
22
+ | `run.ended` | Pi stops: the run finished (`done`), gave up (`failed`), or was stopped (`aborted`). |
23
23
 
24
24
  ```typescript
25
25
  web.onDispose(
package/docs/features.md CHANGED
@@ -74,7 +74,7 @@ The full tour. For setup, see the [README](../README.md).
74
74
  - **Variations.** Artifacts of one group show as a grid of live thumbnails. **Use this one** puts a message about it in the message box.
75
75
  - **Export and share.** PNG, PDF, PPTX (decks), and an HTML zip, from the menu. The file is written in the session's `exports/` folder and the browser downloads it. **Share a link** is the artifact viewer's Share. There is no Canva export.
76
76
  - **What Pi does.** Its guide, `src/server/guides/design.md`, which Pi reads before it makes or changes a design (a short prompt section, only while the module is on, points to it), gives Pi an order of work, after Claude Design's (since 0.27.0): one round of questions when the work is new or unclear, then a start from what exists (the design system, the code, the screens) rather than a mock from scratch, a first version early, iterations, a check, and a short reply. A screen that exists is redesigned from itself: Pi reads its code and data first, makes version 1 the screen as it is today (in its place in the app, compared with a screenshot of the real one when it can get one), and then changes it in new versions, within what the code supports; a change that needs new data or server work is marked in the design and named in the reply, and a different direction becomes a new artifact in the same group. The product's own type sizes, spacing, and density win over the guide's craft defaults. It also gives Pi a page skeleton and craft rules: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs bound to the system's tokens, assets for images and fonts, variations as a group of 2 to 4 artifacts, a link to `ds/tokens.css` when the project has a design system, and a check with `design_preview` before it replies. When the project has a system, the prompt section carries a summary of it (roles and components first) as untrusted project data. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes, or the sizes asked for, and returns screenshots and a short report (see **Checks**); its options are `checks` (on by default), `tweaks`, `colorScheme`, `page` (another page of the bundle), and `actions` (hover, click, or focus on a selector before the screenshot). `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; it also takes `tweaks`, a custom `viewport`, and, for a deck's PNG, `slide` (a number, or `"all"` for a zip of every slide). A page's PDF is as wide as its viewport, and PPTX slide images have twice the pixels. `design_system` reads, scans, and changes the project's design system (see **The design system**). The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. Renders run 2 at once, and more wait their turn; each has 90 seconds.
77
- - **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, breakpoints, and dark mode, from CSS custom properties and rules in CSS, SCSS, Less, and page style blocks, Sass and Less variables with literal values, Tailwind's `@theme` and a `tailwind.config` theme read as a literal, and DTCG, Style Dictionary, and Tokens Studio JSON files; a browser renders the project's pages to fill in what the files leave out), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
77
+ - **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, breakpoints, and dark mode, from CSS custom properties and rules in CSS, SCSS, Less, and page style blocks, Sass and Less variables with literal values, Tailwind's `@theme` and a `tailwind.config` theme read as a literal, and DTCG, Style Dictionary, and Tokens Studio JSON files; a browser renders the project's pages to fill in what the files leave out), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `resync` (bring a saved system up to date with code that changed: it adds the tokens the code now defines and the system lacks, keeps every token people wrote or changed, and lists the values that differ and the tokens that are no longer in the code (as not seen in this scan when the scan read only part of the project); without `apply` it only reports), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A resync records where its tokens came from in `$extensions["com.pi-pocket"].source` on `tokens.json`, so a system carries its own provenance. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
78
78
  - **The System view.** The first row of the design picker (or `/design-open system`, or the launcher's "Open the design system") shows the system: **Colors** (role cards with contrast badges first, a live sample card, and the palette as ramp strips in a folded group), **Type**, **Spacing**, **Radii**, **Shadows** (each with its value), **Motion** (durations and easings that play), **Components** (every state, in a frame that runs nothing and loads nothing), and **Guidelines**. A section's count is its role tokens; the palette and component tokens show their own counts inside it. Modes show one at a time or side by side, and a mode's value says whether it is its own or inherited from the default. People who steer change a color, a size, a time, a weight, a font, an easing, or a shadow's layers in place, or link a token to another; the open design shows each change live when it uses the system's variables. The editor lists every contrast pair of a color (an exempt pair shows as exempt, not as a failure). **Undo** and **Redo** step through the changes, **Discard** gives them up, and **Save** writes the files and the generated CSS with no run of Pi (it refuses a change that the checks refuse, or one made on a system that changed meanwhile). The menu publishes the documentation page as a design, exports the generated files as a zip, and adds or removes a mode. People who only view see everything and change nothing. **Focus mode** hides the conversation for wide work. On a phone, the canvas fits the screen's width, and until a size is chosen it takes the size of its panel. The Design module loads only a small shell at app start; the workspace and the System view load when first opened.
79
79
  - **Checks.** A design's **Check** tab and `design_preview` render the page on the server and judge only what the author's CSS sets, never the browser's defaults. They report values that are not the system's (colors, fonts, and sizes, each with the exact CSS edit and the nearest token of the matching role), contrast (WCAG 2.2 AA, judged only where the background is certain), non-text contrast of focus rings and icon buttons (3:1), tap targets (an error under 24 px, a warning under 44 px), sideways overflow, image alt text, heading order, a missing `lang`, form controls with no label (a placeholder is not a label), links, buttons, and widgets with no accessible name, no `main` landmark, fonts that did not load, a missing viewport tag, missing `data-pid`s, elements with no visible focus style, long motion with no `prefers-reduced-motion` rule, and author-set input text under 16 px on a phone. A check runs in any mode of the system. The tab follows the mode and size on the canvas, puts a pin on each element, and **Send to Pi** puts one message with every finding in the message box. **Fix N exact matches** rewrites literals that equal a token exactly to `var(--token)` and saves a new version with no run of Pi. On a phone, the tab starts as a bar with the counts, so the page keeps most of the screen.
80
80
  - **The documentation page.** The System view's menu (and `design_system`) makes a documentation page of the system as a design: navigation, a filter of names and values, and links to every section; color roles with their values, contrast, and copy buttons for the CSS variable and the Tailwind class; the contrast pairs in every mode (exempt pairs labelled); palettes, type specimens, spacing, radii, shadows, and motion demos; component state grids with their code; guidelines; every token with a column for each mode; and a list of the generated files with how to use them. Component states are drawn in shadow roots after an allowlist sanitizer, under a nonce-only script policy, so they paint in screenshots and PDFs and run nothing. It runs in the artifact sandbox with no network, so it can be shared with a link or exported like any design.