pi-pocket 0.28.0-beta.1 → 0.28.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/docs/customizing.md +25 -2
- package/docs/design/design-mode.md +1 -1
- package/docs/docker.md +2 -0
- package/docs/extensions/policies/api-stability.md +2 -1
- package/docs/extensions/reference/api-versions.md +1 -0
- package/docs/extensions/reference/names.md +1 -1
- package/docs/extensions/reference/theme-surface.md +5 -0
- package/docs/extensions/reference/web.md +77 -0
- package/docs/features.md +6 -5
- package/docs/map.md +8 -6
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/launcher/access.ts +9 -0
- package/src/launcher/main.ts +85 -19
- package/src/launcher/options.ts +7 -5
- package/src/launcher/serve.ts +93 -36
- package/src/server/app.ts +85 -0
- package/src/server/commands.ts +19 -32
- package/src/server/conversation-usage.ts +235 -0
- package/src/server/extensions/anthropic-subscription.ts +6 -4
- package/src/server/extensions/artifacts.ts +101 -41
- package/src/server/extensions/pip.ts +50 -0
- package/src/server/extensions/plan.ts +1 -2
- package/src/server/guides/artifact-bridge.md +1 -1
- package/src/server/host.ts +20 -0
- package/src/server/http/api.ts +9 -1
- package/src/server/http/conversation-routes.ts +4 -0
- package/src/server/http/extension-routes.ts +3 -0
- package/src/server/model-images.ts +124 -0
- package/src/server/pip-compact.ts +1 -0
- package/src/server/pip.ts +3 -3
- package/src/server/reload.ts +1 -0
- package/src/server/running.ts +307 -2
- package/src/server/schedules.ts +5 -0
- package/src/server/when.ts +25 -11
- package/types/pocket.d.ts +42 -0
- package/web/app-icon.js +1 -0
- package/web/app.js +10 -7
- package/web/composer.js +77 -7
- package/web/launcher.js +9 -3
- package/web/peeks.js +1 -1
- package/web/pip.js +1 -1
- package/web/rich.js +1 -1
- package/web/running-board.js +1197 -0
- package/web/sessions.js +88 -23
- package/web/sheets/all-artifacts.js +104 -0
- package/web/sheets/extensions.js +23 -4
- package/web/sheets/menu.js +2 -1
- package/web/sheets.js +4 -4
- package/web/store.js +17 -2
- package/web/style.css +1221 -102
- package/web/subagents-board.js +1 -1
- package/web/transcript.js +3 -4
- package/web/turns.js +7 -3
- package/web/sheets/running.js +0 -130
package/README.md
CHANGED
|
@@ -82,9 +82,9 @@ 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
|
|
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.
|
|
86
86
|
|
|
87
|
-
Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `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)).
|
|
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
|
|
|
89
89
|
> [!WARNING]
|
|
90
90
|
> Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. [SECURITY.md](SECURITY.md) says what is protected and what is not.
|
package/docs/customizing.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Changing how Pi works, without code
|
|
2
2
|
|
|
3
|
-
Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi. So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
|
|
3
|
+
Most changes that people ask for need no code: "always use pnpm", "review the way we do it here", "never touch the migrations". Pi Pocket reads the same files as Pi, except Pi's extensions ([below](#pis-extensions-and-packages)). So what you write for Pi works here too, and the other way round. Pi's own documentation tells all about each file; the system prompt gives its path.
|
|
4
4
|
|
|
5
5
|
## Instructions for one session
|
|
6
6
|
|
|
@@ -23,6 +23,14 @@ Pi's `configuration.md` gives the full list of names, with `AGENTS.override.md`.
|
|
|
23
23
|
|
|
24
24
|
Keep the files short and true. They go with each request, and a rule that Pi cannot obey is worse than no rule.
|
|
25
25
|
|
|
26
|
+
## PiP's instructions
|
|
27
|
+
|
|
28
|
+
PiP has no project, so it does not read AGENTS.md files. Write the rules for PiP, such as the language of its answers, in `pip.md` in Pi Pocket's data folder: `~/.pi-pocket/pip.md`, unless `--data` or `PI_POCKET_DIR` names another folder (since 0.28.0).
|
|
29
|
+
|
|
30
|
+
- PiP gets the file with each message. When the file changes, the next message has the new text.
|
|
31
|
+
- Only PiP reads it: sessions, subagents, and Pi's terminal app do not.
|
|
32
|
+
- A session that PiP messages still answers PiP in Simplified Technical English. PiP answers you as the file says.
|
|
33
|
+
|
|
26
34
|
## Skills: procedures that Pi follows on request
|
|
27
35
|
|
|
28
36
|
A skill is a folder with a `SKILL.md`: a name and a description at the top, and the steps below. Its name and description go into the system prompt. Pi reads the rest when a task matches it, or when a person sends `/skill:name what to do`.
|
|
@@ -54,7 +62,18 @@ Use a template for a message that people send often. Use a skill for steps that
|
|
|
54
62
|
|
|
55
63
|
## Models and providers
|
|
56
64
|
|
|
57
|
-
People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add a model or a provider that Pi does not know,
|
|
65
|
+
People sign in to providers in Menu → **Providers**, and pick a model for each session with the model chip in the message box. Pi Pocket uses Pi's sign-ins (`~/.pi/agent/auth.json`) and Pi's list of models. To add a model or a provider that Pi does not know, add it to `models.json` as Pi's `models.md` says. A provider that needs code comes as a Pi Pocket drop-in that calls `host.registerModelProvider` ([host.md](extensions/reference/host.md#registermodelprovider)), not as a Pi extension: see [Pi's extensions and packages](#pis-extensions-and-packages).
|
|
66
|
+
|
|
67
|
+
**A Claude subscription.** Sign in to Anthropic with it in Providers. Then turn on **Claude subscription billing** in Menu → Extensions → Installed → **Built in**, so that requests count against the plan. It is off by default, and it asks before it turns on. Without it, Anthropic can bill the requests as extra usage, and refuse them when that is used up.
|
|
68
|
+
|
|
69
|
+
> [!WARNING]
|
|
70
|
+
> **Using a Claude subscription in Pi Pocket is at your own risk.** Anthropic's terms and its help pages disagree on it:
|
|
71
|
+
>
|
|
72
|
+
> - Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) forbid accessing its services "through automated or non-human means, whether through a bot, script, or otherwise", except with an Anthropic API key or where Anthropic explicitly permits it.
|
|
73
|
+
> - Its help pages say that third-party apps can use your subscription limits. Yet its servers often bill such requests as extra usage.
|
|
74
|
+
> - Claude subscription billing makes Pi Pocket's requests look like Claude Code's.
|
|
75
|
+
>
|
|
76
|
+
> Anthropic can change how it counts these requests, refuse them, or act on an account it finds using them. An Anthropic API key, or a model from another provider, has none of these risks.
|
|
58
77
|
|
|
59
78
|
Models are the person's choice, never Pi's:
|
|
60
79
|
|
|
@@ -129,6 +148,10 @@ These are in the app, not in files. Tell the person where they are. Do not chang
|
|
|
129
148
|
|
|
130
149
|
See [features.md](features.md) for each of them.
|
|
131
150
|
|
|
151
|
+
## Pi's extensions and packages
|
|
152
|
+
|
|
153
|
+
Pi Pocket reads Pi's sign-ins, models, settings, skills, prompt templates, and AGENTS.md files, but not Pi's extensions. It does not load `~/.pi/agent/extensions/`, the `extensions` setting, or the packages of the `packages` setting in Pi's `settings.json`. Pi Pocket runs on Pi Durable, and its extensions are of another kind ([extensions.md](extensions.md)). For something that a Pi package gives, look in Menu → Extensions: under **Built in**, and in **Discover**.
|
|
154
|
+
|
|
132
155
|
## When this is not enough
|
|
133
156
|
|
|
134
157
|
To give Pi a new tool, add a rule to its prompt that depends on the session's state, or check its tool calls, write an extension: [extensions.md](extensions.md). An extension can also add a page, a rail button, or a route to the app ([Adding to the app](extensions/app.md)).
|
|
@@ -29,7 +29,7 @@ Rules for every stream:
|
|
|
29
29
|
|
|
30
30
|
A design needs images, fonts, data files, and more than one page. Today an artifact is one UTF-8 file.
|
|
31
31
|
|
|
32
|
-
- The `artifact` and `artifact_inline`
|
|
32
|
+
- The `artifact` tool (and `artifact_inline`, until 0.28.0, when `inline: true` replaced it) gets `assets`: up to 200 entries of `{ name, path }` (copy a file from the session's machine, binary allowed) or `{ name, content }` (UTF-8 text). `name` is a relative path: segments of `[A-Za-z0-9._-]`, joined by `/`, no `.` or `..` segment, no leading `/`, up to 200 characters.
|
|
33
33
|
- A new version keeps the assets of the version before. `removeAssets: string[]` drops some. An entry with an existing name replaces it.
|
|
34
34
|
- Limits: 5 MB for one asset, 20 MB for all the assets of one version, as constants beside `MAX_BYTES`.
|
|
35
35
|
- Storage: assets are stored once for each content hash (sha256) in a new document kind, `pocket.artifact-asset`, keyed by the hash, with the bytes in base64. `ArtifactVersion` gets an optional `assets?: Record<string, { hash: string; size: number; type: string }>`. A replayed call must find what it wrote, as the body does.
|
package/docs/docker.md
CHANGED
|
@@ -61,6 +61,8 @@ Do not use `PI_POCKET_ACCESS=local` with the published port: `local` listens on
|
|
|
61
61
|
|
|
62
62
|
`cloudflare` works in the container: the image already contains `cloudflared`, so the launcher does not need a terminal to download it. The tunnel runs inside the container, and the published port is not used. `tailscale` looks for a Tailscale address in the container, which it usually does not have. Run Tailscale on the host instead: publish the port on `127.0.0.1` as above and point `tailscale serve` at it, or run the container with `network_mode: host`.
|
|
63
63
|
|
|
64
|
+
`tailscale-serve` does not work from the container as shipped: the image has no `tailscale` command, and it would need the host's `tailscaled` socket as well. Keep Tailscale on the host and mount the port by hand, as above; the launcher's own mode is for a native install.
|
|
65
|
+
|
|
64
66
|
## Permissions
|
|
65
67
|
|
|
66
68
|
Compose runs the container as root. With rootless Podman, root inside the container is your own host user, so the bind-mounted folders are writable without extra work. This is why the default is root, despite the Browser panel being a Chromium process.
|
|
@@ -64,6 +64,7 @@ The host's members do not change while modules reload. A new member comes only a
|
|
|
64
64
|
- `presentEntry` (experimental, since 0.28.0), with `PresentEntry`: how an input this module sends shows in the transcript. The model still reads that message in full ([Adding to the app](../app.md)).
|
|
65
65
|
- What a route handler gets (`WebRequest`: `method`, `params`, `query`, `body`, `user`, `signal`; since 0.16.0 also request-lifetime `snapshot`, `context`, `commit`), and what its answer does.
|
|
66
66
|
- A conversation-bound request's `conversation` metadata and human `linkedSessions.start` / `list`, with their authenticated-actor, receipt, and admission checks (since 0.16.0).
|
|
67
|
+
- `ConversationWebRequest.conversationUsage`, with `UsageTotals` and `ConversationUsage` (experimental, since 0.28.0): read-only usage for a visible conversation and its visible descendants.
|
|
67
68
|
- The route paths, the methods, the `access` values (`owner`, `steer`, `view`), and the `X-Pocket` header that every call to a route must have.
|
|
68
69
|
|
|
69
70
|
### 5. A command's `ctx` and result
|
|
@@ -165,7 +166,7 @@ Since 0.26.0, `pocket.pip` (`ask`) is experimental, with `PipApi` and `PipAskRes
|
|
|
165
166
|
|
|
166
167
|
Since 0.27.0, `host.roleOf(personId)` is experimental, and so is the `scroll` field of `host.browser`'s `snapshot()`.
|
|
167
168
|
|
|
168
|
-
Since 0.28.0, `web.presentEntry` and `pocket.entryPresentation` are experimental, with `PresentEntry`. 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.
|
|
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.
|
|
169
170
|
|
|
170
171
|
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`.
|
|
171
172
|
|
|
@@ -88,3 +88,4 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
88
88
|
| A person's role: `host.roleOf` (experimental) | 0.27.0 |
|
|
89
89
|
| The page's scroll position: `scroll` in the `host.browser` snapshot (experimental) | 0.27.0 |
|
|
90
90
|
| Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
|
|
91
|
+
| Read-only conversation and descendant usage: `ConversationWebRequest.conversationUsage` (experimental) | 0.28.0 |
|
|
@@ -7,7 +7,7 @@ The rules for the names that a module gives. These are the names of its file, ex
|
|
|
7
7
|
To install an extension with the name of an installed extension replaces that extension. A tool with the name of another tool replaces it in all sessions. Thus Pi Pocket refuses a drop-in that would take a name that Pi Pocket keeps, or a name that another module has. Menu → Extensions says why.
|
|
8
8
|
|
|
9
9
|
- **Extension names that Pi Pocket keeps:** `coding-tools`, and all names that start with `pocket-`, such as `pocket-core`, `pocket-prompt`, and `pocket-guard`. This is true also when that built-in module is off.
|
|
10
|
-
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact
|
|
10
|
+
- **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact` (and `artifact_inline`, a name still kept: it was a tool until 0.28.0, and old sessions hold its calls), `browser`, `subagent`, `team`, `schedule`, `background`, `codemode`, `tool_search`, `memory`, `ask`, and `ask_someone`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`. Design's tools: `design_preview`, `design_export`, and `design_system`.
|
|
11
11
|
- **Names that another module has:** the first module to install an extension or tool keeps its name.
|
|
12
12
|
|
|
13
13
|
Give each extension and tool a name of your own, with a prefix: `example-clock`, `acme_lookup`. To change how a built-in tool works, do not replace it. Wrap it (`wrapTool` in Pi Durable's README), or check its calls with a hook.
|
|
@@ -204,6 +204,11 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
|
|
|
204
204
|
| `browser-panel` | The Browser panel |
|
|
205
205
|
| `pip` | PiP's panel |
|
|
206
206
|
| `subagents-board` | The subagents board |
|
|
207
|
+
| `running-board` | The Running now board |
|
|
208
|
+
| `running-timeline` | Its Coming up timeline |
|
|
209
|
+
| `running-needs` | Its Needs you list |
|
|
210
|
+
| `running-next` | Its Next up list |
|
|
211
|
+
| `running-schedule` | The schedule selected on it |
|
|
207
212
|
| `extension-page` | An extension's page, with `data-module` naming its module |
|
|
208
213
|
| `extension-panel` | An extension's panel, with `data-module` naming its module (since 0.19.0) |
|
|
209
214
|
| `diff` | A diff, in a tool call, a reply, or the review |
|
|
@@ -307,6 +307,7 @@ interface ConversationWebRequest extends WebRequest {
|
|
|
307
307
|
readonly thinkingLevel: ModelThinkingLevel;
|
|
308
308
|
};
|
|
309
309
|
readonly linkedSessions: HumanLinkedSessions;
|
|
310
|
+
conversationUsage(conversationId?: ConversationId): Promise<ConversationUsage>;
|
|
310
311
|
}
|
|
311
312
|
```
|
|
312
313
|
|
|
@@ -314,6 +315,82 @@ Since 0.16.0 · Stable
|
|
|
314
315
|
|
|
315
316
|
Authoritative source metadata, plus request-lifetime human linked-session capabilities. An omitted `model` means the source has none. Metadata is a snapshot, not a promise that settings cannot change. A start rejects a source model, thinking level, or folder changed while it waits.
|
|
316
317
|
|
|
318
|
+
### `ConversationWebRequest.conversationUsage`
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
conversationUsage(conversationId?: ConversationId): Promise<ConversationUsage>;
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
Since 0.28.0 · Experimental
|
|
325
|
+
|
|
326
|
+
A server-side member of `ConversationWebRequest`, available only inside a `web.conversationRoute` handler. Without an id, it reads the bound source. An id can select another visible conversation, including a subagent. It returns committed usage only, with no entries, text, session ids, or write capability.
|
|
327
|
+
|
|
328
|
+
Use a GET conversation route with `access: "view"` for a status item:
|
|
329
|
+
|
|
330
|
+
```typescript
|
|
331
|
+
web.conversationRoute(
|
|
332
|
+
"GET",
|
|
333
|
+
"usage/:source",
|
|
334
|
+
async (request) => {
|
|
335
|
+
if (typeof request.conversationUsage !== "function") {
|
|
336
|
+
throw web.error(503, "Usage needs Pi Pocket 0.28.0 and a server restart.");
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
return request.conversationUsage();
|
|
340
|
+
},
|
|
341
|
+
{ conversation: "source", access: "view" },
|
|
342
|
+
);
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
The route checks its source and the signed-in person before the handler runs. The member checks them again when called and before returning. A target id requires visibility too. Missing conversations and PiP conversations are refused. Descendant sums and counts include only conversations the person can still see. A retained callback fails after the handler returns or the browser disconnects. There is no actor override. Do not broadcast the result to other people or keep it in a shared document: their visibility can differ.
|
|
346
|
+
|
|
347
|
+
This addition does not change route access: people invited to one session still cannot use extension web routes. Viewers with access to all sessions can read through a GET route; no steering, turn, or spend check applies to this read. A gallery entry that needs this member sets `minPocket` to `0.28.0`.
|
|
348
|
+
|
|
349
|
+
Each call reads usage documents and scans stored entries. It also reads the in-memory conversation tree. Cost grows with the stored history, including tool output, of the selected conversation and its descendants, not just their active context. Poll sparingly, not on each streamed token. The result is not an atomic snapshot: work can commit between the ledger and history reads or between conversations.
|
|
350
|
+
|
|
351
|
+
### `UsageTotals`
|
|
352
|
+
|
|
353
|
+
```ts
|
|
354
|
+
interface UsageTotals {
|
|
355
|
+
readonly requests: number;
|
|
356
|
+
readonly input: number;
|
|
357
|
+
readonly cacheRead: number;
|
|
358
|
+
readonly cacheWrite: number;
|
|
359
|
+
readonly output: number;
|
|
360
|
+
readonly reasoning?: number;
|
|
361
|
+
readonly cost: number;
|
|
362
|
+
readonly lastPrompt: number;
|
|
363
|
+
}
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Since 0.28.0 · Experimental
|
|
367
|
+
|
|
368
|
+
- `requests`: the number of stored assistant responses owned by this conversation, including error or aborted responses. Pi's own retry after an error stores a response of its own, so it counts. Requests with no assistant entry, such as compaction attempts and cache-keeper warm requests, are not counted.
|
|
369
|
+
- `input`: reported uncached input tokens, summed across requests.
|
|
370
|
+
- `cacheRead`: reported input tokens read from a prompt cache.
|
|
371
|
+
- `cacheWrite`: reported input tokens written to a prompt cache, including any 1-hour subset. That subset is not added twice.
|
|
372
|
+
- `output`: reported output tokens, including any separately reported reasoning tokens.
|
|
373
|
+
- `reasoning`: the sum of separately reported reasoning tokens. It is absent when none were reported, and can be 0 when a provider reports 0. Do not add it to `output`.
|
|
374
|
+
- `cost`: estimated US dollars from core's usage ledger, not a provider invoice. It includes model and tool usage, as core's spend does.
|
|
375
|
+
- `lastPrompt`: `input + cacheRead + cacheWrite` of the newest stored assistant response that reports any of them, by entry id: a failed request with no usage leaves the one before. It is 0 without such a response. It measures the last request, not the next request's context after a reset or compaction.
|
|
376
|
+
|
|
377
|
+
Token and cost totals come from core's `pi.usage` ledger. They include compaction and auxiliary requests recorded there, even when those requests have no response entry. Tool-reported usage counts too. A fork starts its own ledger; inherited responses do not count toward `requests` or `lastPrompt`. Old responses still count after a compaction or reset. A number that a provider does not report contributes 0; reasoning stays absent until one provider reports it. A conversation with no usage returns zeros and no reasoning field. Results are independent copies; changing a result changes no stored data. A call reads only the entries that came since the last call for the same conversation, so a module can ask often.
|
|
378
|
+
|
|
379
|
+
### `ConversationUsage`
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
interface ConversationUsage {
|
|
383
|
+
readonly own: UsageTotals;
|
|
384
|
+
readonly children: UsageTotals & { readonly count: number };
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
Since 0.28.0 · Experimental
|
|
389
|
+
|
|
390
|
+
`own` covers only the selected conversation. `children` sums every visible conversation it started, at any depth: subagents, linked sessions, and their descendants. It excludes the selected conversation, its ancestors, siblings, and forks. Archived descendants still count. Each conversation counts once, including one with no usage. `children.count` is their count, and `children.lastPrompt` is the sum of each descendant's `lastPrompt`, not the newest prompt across the family. No descendants gives zeros and count 0.
|
|
391
|
+
|
|
392
|
+
Requested by @Haichiu in #195.
|
|
393
|
+
|
|
317
394
|
### `HumanLinkedSessions`
|
|
318
395
|
|
|
319
396
|
```ts
|
package/docs/features.md
CHANGED
|
@@ -41,7 +41,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
41
41
|
- **Prompt templates.** Pi's prompt templates (`~/.pi/agent/prompts/*.md`, the project's `.pi/prompts/*.md`, and the paths in Pi's settings) show up as slash commands: `/review src/auth.ts` sends the `review` template with its arguments filled in. Pi's skills do too, as `/skill:name what to do`: Pi gets the skill's instructions with the request. The `skills` setting of Pi's `settings.json` works as in Pi: `-path` and `!pattern` leave skills out, `+path` puts one back, and a relative entry starts from Pi's folder (since 0.28.0).
|
|
42
42
|
- **Project trust.** A project's own skills (`.agents/skills`) load only in a project Pi trusts, as in Pi's terminal app. When a session's project has some and nobody has decided, the owner is asked above the message box: **Review** says what trusting it loads, here and in Pi's terminal app, and offers to trust the folder, the folder above it, or not; **Don't trust** answers at once, and **Not now** (×) puts the question off in that tab. `/trust` or Menu → **Project trust** changes the answer later. Answers are saved where Pi's terminal app keeps its own, so a project trusted there is trusted here too. Pi has the skills from its next message. A project's `.pi/skills` load until it is told "Don't trust", then stay out too (Pi's terminal app asks before loading them at all); the sheet lists both kinds and says what each answer does to them. Only the owner is asked.
|
|
43
43
|
- **Changes.** The Files tile's **Changes** tab (or the count of lines added and removed in the top bar, `/changes`, or Menu → **Changes**): every uncommitted change in the session's folder as one review, file by file. Summary counts include new text files before and after staging (an untracked one over 2 MB shows no count); binary files have no line counts. Each file has a header that stays in view while you scroll its lines, with a fold chevron, what kind of change it is (M, A, D, or R in a small tile), its counts, and a **Viewed** checkbox button that folds the file; viewed files stay folded on this device until their diff changes again, and the summary says how many you have seen. Diffs show side by side when there is room and unified when not (Auto, Unified, or Split, as you pick, with long lines wrapped or not), with line numbers on both sides, syntax colors, and the words that changed within a line marked; a changed line is paired with its new version by likeness, not just position. The unchanged lines between changes are a tap away, a few at a time or all at once, read from the file as it is now (and only when it still matches the diff). Tap a line number to open the file there. A tree of the changed files (beside the diffs when wide, behind **Files** when narrow) jumps to one, a filter narrows them, and **π only** keeps the files Pi edited. Diffs load as they near the screen, a few at a time, and the review looks again a moment after Pi moves on. Keys: `j`/`k` the next or previous file, `n`/`p` the next or previous change, `v` viewed, `s` the layout, `w` wrapping. From a file's header, **↺** (tapped twice) puts it back as the last commit has it, or deletes it if it is new; Pi is told, and it waits while Pi works. A file with a merge conflict, or a rename, is left to git. Outside a repository it lists Pi's edits alone. Someone invited to one session sees the changes in its folder only.
|
|
44
|
-
- **Running now.** Menu → **Running now** (also on the sidebar's rail)
|
|
44
|
+
- **Running now.** Menu → **Running now** (also on the sidebar's rail and in the launcher) shows, in the conversation's place as the subagents board does, everything at work and everything scheduled in the sessions you can see. A **Coming up** timeline at the top has a lane per session: its scheduled messages as marks at their times (a diamond for a repeat, a ring for one that goes out once, amber while a spend limit or a lost right to steer holds it), a bar for how long the session has been at work, and a line at now; 24h, 3d, or 7d, it scrolls sideways, hovering a mark says what and when, and hovering (or tapping) a session's bar shows the last message sent to it, which its run works on. Under it, filter pills (All, Running, Scheduled, Needs approval, Held) and a search, then one row per session: the session, with its folder, Busy, calls to approve, and **Stop** on one line under its name; **Now**, what is at work there from Pi Durable's task graph (answers, tool calls, subagents, compactions, background tasks, shell and extension commands, PiP's follows and watches) with how long each has been at it, Stop where it can stop, and the session's model and spend; and **Schedule**, its scheduled messages with the next time, the repeat in words, and how many times each went out. A schedule picked there or on the timeline opens at the side on a wide screen, under the rows on a narrower one, and in a bar at the bottom on a phone: its message, repeat, next time in its own zone, who set it up, its next five times, **Open session**, and **Cancel**; **Needs you** (calls waiting for approval, held schedules) and **Next up** stay beside it. Esc, back, or × closes it; it asks the server again every 2 seconds while it shows.
|
|
45
45
|
- **Watch a pull request.** Menu → **Watch pull request**, `/watch` (or `/watch 123`, `/watch <PR address>`), or Pi's `watch_pr` tool, which it can start after opening a PR (Pi only for its folder's repository, by number; a person for any): until the PR is merged or closed, Pi Pocket looks at it on GitHub every few minutes with the `gh` command signed in on the server, and tells Pi in the session what needs doing, as a message sent through the watch for whoever set it up: checks that failed on its last commit (once all of them finished, with the end of each GitHub Actions log), conflicts with its base branch, and new comments and reviews. Only comments from the repository's owner, and from organization members and collaborators whom GitHub says can write to it, count, and bots' reviews (a member may only read, a collaborator only triage: `gh` asks GitHub, at most every ten minutes for each person, and GitHub tells only an account that can push there, so on a PR where yours cannot, such as a fork's PR to someone else's repository, only the owner's count, and the watch says so); your own account's (which Pi posts as) only when they mention @pi in their own words (not in a quote or code), so Pi never answers itself. Comments keep their lines (a suggested change is code), 30 at most in a message (read newest first, so a burst never hides the new ones); each is told once, and what does not fit in one message comes in the next; nothing goes while Pi is busy there or, with take turns on, while someone else drives (the bar says it waits, and nothing counts as failed); and a watch sends 10 messages at most. While Triggers is off it asks GitHub nothing. A bar above the message box shows the PR, its checks, and how many messages went, with **Stop**. It ends, with a line in the chat and a notification, when the PR is merged or closed, when there is more to tell than it may send, after two weeks with nothing new, or after an hour of looks that failed (the bar says why). Logs reach Pi fenced as data, which nothing in them can end early, and titles, check names, and branches come on one line, quoted, as data too. It needs `gh` installed and signed in (`gh auth login`) on the server, on GitHub Enterprise hosts too: a host other than github.com is used only when `gh` is signed in there (`gh auth login --hostname <host>`; a token only in `GH_ENTERPRISE_TOKEN` does not count), for Pi, PiP, and people alike, and Pi names a PR by address only on github.com or its folder's own host.
|
|
46
46
|
- **Watch a repository.** Tell PiP in plain words, such as "watch acme/api: when CI fails on main, fix it and tell me" or "when I open an issue labelled pi in acme/web, work on it": it sets up a watch that looks at the repository on GitHub every few minutes with `gh` (no public address needed, unlike a webhook), and what is new there (issues and pull requests opened, CI failing on a branch, releases, someone writing @pi, as a word of its own, in a comment or an issue) comes to PiP, or to a session you name, with your instructions; PiP then acts on it: it starts a session in the repository (its checkout here, or a clone it makes in the data folder's `repos/`), sends it the task, follows it, and tells you what came of it. A watch can be narrowed to a label, to issues assigned to you, or to a branch's CI (mentions of @pi are not narrowed). CI is the branch's own runs: pushed to it, scheduled, started by hand or through the API, or started by another workflow, in the repository itself, never a pull request's or an issue's (a renamed repository keeps working). Only repositories `gh`'s account can push to can be watched or worked on, and issues and pull requests count only from the repository's owner, and organization members and collaborators whom GitHub says can write to it (and bots' pull requests), unless you turn on **From anyone** on the watch in Menu → Webhooks and watches (PiP cannot); @pi always only from them. PiP works in a checkout of a session you started, or in a clone it makes, which appears only once complete (a clone a restart cut off leaves a `~part-…` folder, removed at the next clone of that repository); a different folder already where the clone goes is reported, never overwritten. While Triggers is off, watches wait and ask GitHub nothing; while PiP is off, a watch to PiP holds what it found, and its note says so. What came from GitHub is fenced as data, each thing is told once, ten in a message and twelve messages an hour at most (the rest come next), and a look that fails is tried again, less often each time, with the reason shown. Menu → **Webhooks and watches** lists the watches, to remove one; or ask PiP ("what are you watching?", "stop watching acme/api"). PiP can also start a PR watch on a session ("see acme/api#12 through"), and Pi's own `watch_pr` takes a PR in another repository it can push to by its address or `owner/name#12`, telling Pi to work in a checkout of it. Part of the **Triggers** extension.
|
|
47
47
|
- **Webhooks.** Menu → **Webhooks and watches**: an address that other services (GitHub, a deploy, a monitor) post to, each post becoming a message to Pi in a session, or to PiP, as the work of whoever made the hook: their instructions first ("When a deploy fails, find out why and fix it"), then what was posted, trimmed of noise such as API addresses, and fenced as data. PiP gets them as folded cards and decides what to do: start a session, message one, or tell you. A GitHub hook is signed: GitHub gets the address and, separately, a secret (its Payload URL and Secret), and a post gets in only with GitHub's signature made with it, so whoever sees the address (the repository's admins do, in its settings) cannot post as the hook. Unless a GitHub hook is made **From anyone**, what people outside the repository wrote does not reach Pi (the repository's people are its owner, and the organization members and collaborators whom GitHub says can write to it, asked through `gh`, which must be signed in to the host and able to push there, or else only the owner counts; bots count on pull requests and what is said on them, never on issues): a post an outsider started (their issue, comment, pull request, review, or discussion) is dropped with a 202 that says so; in a post the repository's people started, the body of anything an outsider wrote in it (the issue under a member's comment, a review thread's comments) is left out, its title kept; a workflow run goes only when a branch of the repository itself started it (a push, a schedule, a manual or API dispatch, or another workflow), so one a pull request (a fork's too), an issue, or a comment started is dropped, and so is one whose head repository GitHub does not show; workflow jobs, check suites, and check runs do not say where their run came from, so they are dropped too, as are a commit status on no branch of the repository (a fork's commit) and a security advisory someone reported; and pushes, releases, and other posts that name no author go as they came. A hook for another service has the secret in its address instead: anyone who has the address can message Pi as the hook's person. **New secret** shuts out the old one, for an address or a secret that got out. Anything else gets 404. A post GitHub sends again goes to Pi once, GitHub's ping gets an answer and is nothing for Pi, a hook takes 30 posts an hour of up to 5 MB each (the server reads eight at a time, two to one hook, each within 15 seconds; past that, 503 with Retry-After), a hook to PiP answers 503 while PiP is turned off, and a post that cannot go now (someone else drives, a spend limit) gets a 409 that says no more. Services must be able to reach the server: through a tunnel, a public address works for GitHub. People who can steer make hooks for the sessions they can reach; each sees their own, the owner every one. The watch and webhooks are the **Triggers** extension: turned off, watches wait and hooks answer 503.
|
|
@@ -63,7 +63,8 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
63
63
|
- **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.
|
|
64
64
|
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished, 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`.
|
|
65
65
|
- **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.
|
|
66
|
-
- **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.
|
|
66
|
+
- **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.
|
|
67
|
+
- **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`.
|
|
67
68
|
- **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.
|
|
68
69
|
- **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.
|
|
69
70
|
- **Versions.** A timeline of every version, side-by-side compare of two, and **Go back to this one**: it makes a new version that is a copy of the old one, assets included, and does not ask Pi. A repeated tap finds the version it made.
|
|
@@ -87,7 +88,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
87
88
|
- **Waiting out provider limits.** When a provider's limit stops a run (a 429 or an overload, a Claude or ChatGPT usage window, a model's cap), Pi Pocket waits for it to clear and goes on by itself, instead of failing. It waits until the reset time the provider gave (or, with none, tries again at growing intervals), then sends one request to find out; if that gets an answer, the sessions waiting on the same limit go on, one at a time. The live line says what Pi waits for, when it tries next, and when the limit resets, with **Retry now**; **Stop** or **Interrupt** end the wait at once, and a message you send meanwhile waits in the queue as always. The session's square is a hollow square with a dot, also on peek tiles, and a subagent's row says it waits. One push goes out when a wait of ten minutes or more begins (Menu → **Notifications** → **Waiting for a limit**). It survives a restart. The owner sets the longest wait (**Wait for a limit** in the Providers sheet: Off, 1, 6, 12, or 24 hours; default 6): what waits is any reset time within that longest wait, load with no time given (an ordinary 429 or an overload), which is tried again at growing intervals for up to 30 minutes, and, since 0.24.0, a plan's usage limit with no time given (OpenAI subscription sharing, Z.ai, MiniMax, OpenCode Go), which is tried again about every 15 minutes, up to the longest wait, counted from the first failure across restarts. What fails the run at once, with the reset in the message where there is one: a window of days (Claude's 7-day window, a Codex window of over 300 minutes), a reset after the longest wait, a usage limit that names a window of days (daily, weekly, monthly), with or without a reset time, and a sign-in that expired or billing. Retry now sends one try each 30 seconds. It never picks another model. Since 0.21.0.
|
|
88
89
|
- **Prompt cache keeper.** On by default; `PI_POCKET_CACHE_KEEPER=off` turns it off. While a run waits on a tool call, Pi Pocket replays the last request that ended in a tool call, with `maxTokens` 1, at 90% of the cache's lifetime or 10 seconds early, whichever is sooner. It does so only when the expected savings are more than the cost. It keeps the 5-minute cache only: no idle warming, no 1h cache, no request with `cacheRetention` none, and no Anthropic thinking set by a token budget. It stops on a real cached request, when the run ends (PiP's too), on an error, at shutdown, or after 30 minutes. A warm request does not wait for a provider limit. Its usage counts in `pi.usage` and in the spend of the person and session that were paying when it started, and spend limits are checked before each warm. A restart drops the warm timers and does not replay warm requests.
|
|
89
90
|
- **Background subagents.** The `subagent` tool spawns named subagents that work in their own conversations while you keep talking. Since 0.19.0, Pi writes its tasks for subagents in ASD-STE100 (Simplified Technical English) and asks for their reports in it too. Since 0.20.0, Pi's instructions say when to start one (independent parts of the work, a long or noisy job whose result alone matters, a review or second opinion before it calls work done, or when you ask for subagents or parallel work), when to do the work itself (one or two tool calls, work that needs the conversation), and what a brief holds (the goal, paths, what is known, limits, and the report wanted: answer first, then evidence); the result of a start tells Pi to carry on with its own part. Linked sessions (Agent Teams) get the same kind of guidance: they suit long or separate jobs that you may want to follow, and subagents suit short helpers. Open one to watch it or talk to it. Its answer goes back to the main agent at its next pause (after a tool call; when it is idle, after a moment, so answers that finish together go together); answers that arrive meanwhile wait together and go as one message, shown as a card each, so many subagents cost the main agent one extra turn at most, and wait in its queue as one row: one that arrives while that row waits joins it. A subagent that fails says why, and one that is stopped says so, to the main agent too, so it does not wait for an answer; a message sent to it while it worked, which its failed run never took, is withdrawn, and the main agent is told to send it again. A subagent thinks at the session's level unless Pi names another, of any height, such as a cheap model at its highest (a level its model lacks becomes the nearest lower one it has, or its lowest, and the main agent is told), with an optional tool list. Pi picks no model on its own: until the owner allows models for subagents (**Models for subagents** in the Providers sheet), a subagent runs on its session's model, and the subagent tool offers none and refuses one Pi names. Once some are allowed, a subagent runs only on those: with no model named, on the session's model when that is allowed, else Pi must name an allowed one (the refusal lists them, and its instructions show each model's thinking, context window, and price where known, with a line on matching the model to the work); one that is not allowed is refused, as is one whose sign-in expired, with word to tell you rather than pick another. A subagent on a model the owner does not allow (any longer), the session's own included, gets no more work; a level raised by hand in its conversation stays as work is sent. One whose model or provider failed (an expired sign-in, a model that is gone or refused, a quota or rate limit) says so with its model, on its card and in a notice, and the main agent is told to stop and tell you, never to start it again on another model. A subagent's status line shows what the subagent itself cost, with no limit: the limit is its session's (since 0.28.0).
|
|
90
|
-
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Open as a conversation** shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back.
|
|
91
|
+
- **PiP.** The owner's assistant, "Pi in Pocket", over every screen. It stays out of the way until called: Alt+A, the rail's orb, the PiP tile in the places, the launcher, or `/pip` (`/pip what needs me?` asks at once); a small mark shows in the corner only while it works or has something new. It opens as a rounded, shadowed window anchored 16px from the bottom right corner on wide screens (on a short screen it is shorter, never over a session's top bar; on a screen narrower than about 1600 px it covers the right end of a session's message box until it closes) and a sheet from the bottom on phones, over whatever is open, which stays as it was; Esc, back, or a swipe down closes it. PiP looks after the other sessions: it lists and reads them, starts sessions (in a folder, a worktree, with a model) and messages them, stops and archives them, schedules messages there, watches your GitHub repositories and pull requests and acts on what happens there (see Watch a repository), starts sessions in a repository by name (its checkout, or a clone), and follows runs until they end, when a report comes back to it and it says in a line what came of it: pushed as a notification when you are not looking (instead of the session's own "Pi finished", which is held back only while PiP is on, not held back by a spend limit, and following that run, and for a minute after its report), which opens PiP over whatever the app shows. A request to do hands-on work authorizes PiP to start or message the session it needs; you do not have to say “start a session.” PiP delegates to that session's tools instead of refusing because its own tools cannot edit files or run commands. PiP's model and new sessions' default model are separate: if a worker has no model, choose one in that session. Menu → Default model sets the model for future sessions. It is dependable before fast: it acts on a session (messages, stops, archives, follows its run, schedules there, or watches its PR) only after it looked at it in the last 15 minutes (read it, started it, or had a report from it), its tools say how a session stands after they act, and it says what it checked and what it did not; tasks it sends that touch code ask for the checks and tests. It never picks a model: which one is yours to say, as below. A session's last answer comes to PiP, in a report or a read, in parts of up to 12,000 characters; when it is cut, a note after the fence says how many characters are left, and PiP's `session_read` tool takes `answerFrom` (a character) to read the rest of that answer, part by part. What sessions say reaches PiP fenced as data, never as instructions, and what sessions, guests, or GitHub named (titles, waiting calls, scheduled messages, PR titles) comes on one line, quoted, as data too. It makes at most 60 messages, follows, schedules, and watches (its reminders to itself included; a schedule it could not make does not count), and starts at most 20 sessions, an hour (counted since the server started). It can deny a call waiting for approval, never allow one. When one of its own calls waits for approval, the panel says so, and **Review** opens its conversation, where it can be allowed. What it sends shows as sent through PiP for you; it reads files but changes none and runs no commands, handing hands-on work to sessions. Since 0.19.0, it writes what other agents read (its messages to sessions, scheduled messages, and the instructions of its watches) in ASD-STE100 (Simplified Technical English), at about 80% adherence, and asks each session to answer it in the same style; a session answers a message that came through PiP (scheduled ones too) in ASD-STE100 too. PiP's answers to you stay as they were. Your messages are accent bubbles, and one you send while it works shows at once, dimmed, with when PiP reads it (at its next pause, or when it finishes for a queued one) and **Withdraw**, until PiP takes it; completed steps have small green checks, and reports are rounded cards that expand to show more. Its replies link the sessions they name; **Open as a conversation** shows every step, and **Start fresh** gives it a new context. The panel's header measures context against PiP's compaction limit, capped at the model's context window (or just that window with **As sessions do**), and follows changes in Extensions; **Compact** there (or `/compact`, or `/compact` with what to keep in mind, typed to PiP) turns its older messages into a short summary, the newest few kept as they are; and by default it compacts when a session would, at Pi's own thresholds (since 0.22.0; before, above 60k tokens). To keep it smaller, the owner picks 40k, 60k, or 100k in Extensions under PiP (`pipCompactAt` in `~/.pi-pocket/config.json`): then it compacts itself once idle above that, and waits for 8k tokens more before it does again, while a session's thresholds stay as a backstop during a long run. An owner who chose a limit before keeps it. PiP's summary is its own: written from its conversation with what sessions said, webhooks' posts, GitHub's events, and what files and scripts gave back left out, so none of their words come back as PiP's notes; it keeps its person's preferences, what is still open, and what it follows and watches, which live on the server and carry on as they were. A summary that cannot be written leaves the context as it was: Compact's notice says why, and after one of PiP's own that failed it waits 30 minutes, or 8k tokens more, before it tries again. A summary costs a request, counted in PiP's spend. It is a conversation of its own, kept out of the session list and out of everyone else's reach (nobody else can open it or write to it), and durable like the rest: follows outlive a restart. Its cost shows in its person's Spend sheet, and its follows in Running now. Turn it off in Extensions: it stops what it was doing (a compaction too), takes no messages, its own conversation's box included, and meanwhile its follows' reports and its own scheduled messages wait, webhooks to it answer 503, and repository watches to it hold what they found, all going on once it is back. PiP follows its owner's standing instructions in `pip.md` in the data folder, such as the language of its answers (since 0.28.0, [customizing.md](customizing.md#pips-instructions)).
|
|
91
92
|
- **Resize.** At widths of 768px and above, drag PiP's left edge, top edge, or top-left corner to resize it, with the bottom-right corner fixed. The same zones are finger-sized on touch screens. Its size is remembered for each account in this browser and fits back inside the viewport when it shrinks. Phones use a bottom sheet with rounded top corners and a grabber; the model, context meter, and all four header actions stay available.
|
|
92
93
|
- **Choose PiP's model.** Tap the model chip in PiP's header to use the existing model and thinking picker for PiP alone, from Home or over a session. The chip and picker choices are disabled while PiP works. Saving also checks that PiP is idle. This header path does not change the last picked model for new sessions; **Open as a conversation** keeps its existing behavior. With no model, the welcome offers **Choose a model to use these suggestions**, which opens the same picker. Suggestions that send at once wait for a model; those that put text in the box stay usable, and choosing a model keeps the suggestions visible.
|
|
93
94
|
- **Files and images in chat.** Pick files with the attach button, paste files or images from the clipboard, or drop them into PiP's message box. Remove attachments before sending; upload status shows while they are saved. You can send files with text or on their own. They belong to PiP's conversation, not the session behind the panel. Images have previews and open full screen; other files show their names. As in normal chat, supported images go directly to an image-capable model and other files are given as saved paths. PiP does not choose a different model for you. Draft attachments stay when you close and reopen the panel.
|
|
@@ -122,9 +123,9 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
122
123
|
- **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files it writes"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, and that the scan reads text so the code can reach more, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code, or gives one of them, or a `net`, `tls`, or `dgram` connection, an address it builds, also beside hosts it names), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none, or loads code the scan cannot read: `eval`, `new Function`, `getBuiltinModule`, `process.binding` or `dlopen`, `import()` or `require()` of a name it builds, or a `.node` file), and the files it writes (`files it writes`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
|
|
123
124
|
- **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
|
|
124
125
|
- **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (in the provider controls), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
|
|
125
|
-
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them.
|
|
126
|
+
- **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them. An image starts to be made ready for the model as soon as it uploads, so a send seldom waits for it. In a session's message box (not PiP's), attached files stay across a reload, as the draft does, and leave with your sign-out; while a message is on its way, the box dims and holds what it sends, and if the send fails, it is all there to send again.
|
|
126
127
|
- **Code in your messages.** In a message you send, `` `code` `` and a fence of ` ``` ` lines show as code, the way Pi's replies show it, colored when the fence names a language (` ```js `). A span closes with as many backticks as opened it, a fence's lines stand on their own, and a stray or unclosed one stays text. Nothing else is formatted: `*`, `#`, lists, and spacing stay as typed, and @mentions outside code stay buttons. Only the display changes: Pi, exports, and ↑ get the message as written.
|
|
127
|
-
- **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact_inline` call shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
|
|
128
|
+
- **Rich replies.** Code blocks in Pi's replies show their language and a Copy button, with syntax colors for the common languages (no dependencies, so it works offline), and a block of more than 40 lines folds until you ask for the rest. Some show more than code, with the code a tab away: an `html` block (or a reply that is a whole page) is previewed as a page, inline, with its scripts off and nothing loaded from anywhere; **▶ Run** runs its scripts in the artifacts' sandbox, where it can reach the internet but not the app; an `svg` block is drawn as an image (tap it for full screen); and a `diff` or `patch` block opens in the diff viewer. While Pi is still writing, they show as code. Write cards color the file they write, and the file viewer previews `.html` files the same way, with Run. **Cards in the reply.** An `artifact` call with `inline: true` (an `artifact_inline` call, in a session from before 0.28.0) shows as a card in the reply, as the `html` block above with the artifact's name and version in its bar, an **Open** button for the artifact viewer at that version, and the same Preview/Code and Run/Stop; a failed, denied, or stopped call shows as a step with its reason instead. The result records the version its call made, so each card keeps showing its own: an update by Pi adds a new card, and earlier cards, in this session and a fork, do not change. A card's page is read from the artifact's own address, so whoever can see the session sees the card, a viewer and someone invited to this session alone included, and each can Run it. Once run, its page gets what an artifact's does: a follow-up for the message box (a notice for a viewer) and saved state under the artifact's id, shared with the viewer. A preview grows to fit the page, up to 1200 px, and a running page up to 900 px, then scrolls inside. On a phone the bar takes two lines. A viewer already open on an older version stays on it and offers "latest is vN" after an update. Only a call Pi makes itself is a card: one made inside a codemode script is one of its nested calls, and in PiP's panel the call is a line among its steps.
|
|
128
129
|
- **Images inline.** Attached images show as thumbnails (also in the composer before you send). When Pi writes `` with a path on the server (absolute, `~/…`, or relative to the session's folder), the image shows in its reply. Images a tool returns and SVG artifacts show inline too; an image Pi reads with `read` (often one you just sent) shows only when its call is opened, so it is not on screen twice. Tap any image to see it full screen. Only real image files are shown: the server checks a file's bytes, not just its name.
|
|
129
130
|
- **Launcher.** `npm start` asks how your devices should reach Pi Pocket: this device only, the local network, a Cloudflare Tunnel, Tailscale, or Tailscale Serve. It then shows the address and a QR code to sign in your phone, and keeps running with keys to restart the server or change access.
|
|
130
131
|
|
package/docs/map.md
CHANGED
|
@@ -39,7 +39,7 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
39
39
|
| `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
|
|
40
40
|
| `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
|
|
41
41
|
|
|
42
|
-
`extension-request.ts` owns extension routes' request-lifetime document/context capabilities and fresh person/source authorization. `http/extension-routes.ts` binds named source parameters and supplies human linked-session capabilities. `linked-sessions.ts` keeps the short final-admission lease; its child context watches policy publications and checks current config when Durable enters admission. `models.ts` supplies exact local `host.modelInfo` metadata. `versions.ts` supplies `host.pocketVersion` and `hello.server.pocketVersion`, read by browser `pocket.pocketVersion`; `pocket.openConversation` delegates to normal `store.navigate`.
|
|
42
|
+
`extension-request.ts` owns extension routes' request-lifetime document/context capabilities and fresh person/source authorization. `conversation-usage.ts` reads core usage ledgers and response counters for a conversation route, with visible descendant sums and fresh access checks. `http/extension-routes.ts` binds named source parameters and supplies human linked-session capabilities. `linked-sessions.ts` keeps the short final-admission lease; its child context watches policy publications and checks current config when Durable enters admission. `models.ts` supplies exact local `host.modelInfo` metadata. `versions.ts` supplies `host.pocketVersion` and `hello.server.pocketVersion`, read by browser `pocket.pocketVersion`; `pocket.openConversation` delegates to normal `store.navigate`.
|
|
43
43
|
|
|
44
44
|
### People
|
|
45
45
|
|
|
@@ -68,11 +68,12 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
68
68
|
| `prompts.ts` | Pi's prompt templates as slash commands, and `/skill:name` expanded |
|
|
69
69
|
| `pi-sessions.ts` | Pi's sessions from the terminal (`~/.pi/agent/sessions/`), read and never written: listing them, and one as a new session's history, with Pi's own context of it (compactions, context edits); `commands.continuePiSession` makes the session |
|
|
70
70
|
| `skills.ts` | Which skills a session's folder has, from where Pi's CLI looks and in its order, with Pi's project trust; the system prompt and `/skill:name` both use it. Reads and saves the owner's answer to "trust this project?" |
|
|
71
|
+
| `model-images.ts` | Attached images made small enough for the model, started as each upload ends so a message that sends them finds them ready |
|
|
71
72
|
| `models.ts` | The models people can pick (marked for Pi’s enabledModels scope and when their sign-in needs renewing), the one a conversation runs with, finding one by name, and the thinking levels |
|
|
72
73
|
| `model-facts.ts` | One short line per model of the owner's list for subagents (thinking, context window, price, which is the session's own) for the `subagent` and `team` prompt sections |
|
|
73
74
|
| `project-model.ts` | Trusted project model/thinking defaults and fresh global-only settings read for each new session, validation, and safe errors; no resource paths or per-project run policy |
|
|
74
75
|
| `model-names.ts` | Which models a text names, word by word: PiP passes or names a model only when its person named it |
|
|
75
|
-
| `running.ts` | Running now, from Pi Durable's task graph
|
|
76
|
+
| `running.ts` | Running now, from Pi Durable's task graph, and the Running now board's data (`runningBoard`): the sessions at work with their model and spend, every scheduled message with its next times and whether it is held |
|
|
76
77
|
| `pip.ts` | PiP, the owner's assistant: its conversation (made on first open, kept out of the session list), what its tools do as its person, and the follows (a durable task each) that report to it when a session's run ends |
|
|
77
78
|
| `compaction.ts` | When a session's context is compacted: Pi's compaction settings for Pi Durable, with each model's own values (`compaction.modelOverrides`) |
|
|
78
79
|
| `pip-compact.ts` | PiP's context kept small: when it compacts itself, and its own summaries, written with what came from outside left out and counted in its spend |
|
|
@@ -190,7 +191,7 @@ Outside `src/`: `flake.nix` and `nix/` build Pi Pocket with Nix (`nix/package.ni
|
|
|
190
191
|
|
|
191
192
|
## Extensions: `src/server/extensions/`
|
|
192
193
|
|
|
193
|
-
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`
|
|
194
|
+
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`), `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), `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), `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), `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`, `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).
|
|
194
195
|
|
|
195
196
|
## Web: `web/` (Preact and htm, no build)
|
|
196
197
|
|
|
@@ -204,7 +205,7 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
|
|
|
204
205
|
| `gestures.js` | Touch gestures, each following its own finger by its identifier, passive where they can be: sheets dragged down and the drawer dragged left to close (`useDragToClose`); on phones, swipes on the conversation (right back, left Files), in Files (right back), and up from the message box (the places); a swipe in from the left edge goes back in an iPhone's home screen app |
|
|
205
206
|
| `app.js` | Layout (tiled windows, and the subagents board in the conversation's place), top bar (with what changed, from `diff.js`), notices, keyboard shortcuts, routing |
|
|
206
207
|
| `transcript.js` | The conversation as turns: messages, Pi's replies with message times arranged in the reply slot, its thinking and tool calls folded into groups that open into a timeline, extensions' command cards, approvals, the live line (and Pi's thinking above it), breadcrumbs (and `linked-sessions.js`, the links between linked sessions); a message from a linked session shows without its routing words |
|
|
207
|
-
| `turns.js` | How the transcript reads a conversation, without drawing it: answers split into runs of words and groups of calls, and each `artifact_inline`
|
|
208
|
+
| `turns.js` | How the transcript reads a conversation, without drawing it: answers split into runs of words and groups of calls, and each inline call (`artifact` with `inline: true`, or an old `artifact_inline`: `isInlineCall`) as an `inline` item between them (`itemsOf`), a group in a line (`summarize`, with extensions' own tools as `extension-ui.js` gives them: `setCallSummary`), and what a call came to from what its tool printed. No imports, so Node tests it |
|
|
208
209
|
| `calls.js` | A tool call in one line, for the transcript's timeline and peek tiles; extensions' own tools as `extension-ui.js` gives them (`setCallDescriber`) |
|
|
209
210
|
| `slots.js` | Slots: the top bar's buttons, the status line's items, the places, the message box's left buttons, and the actions under answers as named items, the app's own (`defineItem`) and extensions' (`fromExtensions`), in one order: defaults, `before`/`after`, extensions' `pocket.arrange`, then the person's own choices (`prefs().layout`, Appearance → Layout) |
|
|
210
211
|
| `composer.js` | Message box, chips, the queue, plan and goal bars, `@` file suggestions, `!` commands, ↑ and Ctrl+R history, long-paste placeholders, the mic (`voice.js`), a subagent's way back to its session, the status line under it (kept to one row) |
|
|
@@ -222,7 +223,7 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
|
|
|
222
223
|
| `commands.js` | Slash commands (the app's own, and extensions'), and prompt templates |
|
|
223
224
|
| `trust.js` | Project trust: the bar that asks the owner whether to trust a session's project for its own skills and its `.pi/settings.json` model defaults, and the sheet (`/trust`, the menu) that shows and changes the answer |
|
|
224
225
|
| `sheets.js` | Which sheet is open, the component that shows it, and the nested-sheet back action supplied to `Sheet` through `SheetBack` |
|
|
225
|
-
| `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend,
|
|
226
|
+
| `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend, all artifacts (`all-artifacts.js`: every session's artifacts from `GET /api/artifacts`, `PocketApp.artifactOverview`), schedules, webhooks, memory (the lessons Pi keeps, with the menu's hint), worktree, Pi's terminal sessions, appearance, shortcuts, the menu, a session's actions, the extension gallery (`gallery.js`: browsing, an entry, its source, an update, sharing; `galleryAvailable`), with the artifact viewer's **Open in Design** button (`viewers.js`) |
|
|
226
227
|
| `peeks.js` | Peek tiles: their switches (the top bar's and the rail's), which sessions get one and in what order (working, waiting, with subagents at work, finished, or pinned), the column and the strip, each tile's subagents at work (the first few as rows, the rest counted, opening the board at them) and their own peeks, the watch list |
|
|
227
228
|
| `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it; the list also puts looks back (`seenSnapshot`, `restoreSeen`) when it undoes marking sessions read |
|
|
228
229
|
| `clock.js` | The server's clock as a tab knows it, without the DOM: how far it is ahead of this browser's, fitted to what each hello proves, so a hello handled late (a tab woken from the background) moves no time shown |
|
|
@@ -230,6 +231,7 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
|
|
|
230
231
|
| `session-cache.js` | The sessions a browser keeps on the device (IndexedDB) for all its tabs: saved, read, and dropped by size, the one used longest ago first; `store.js` decides what goes in and checks what comes out |
|
|
231
232
|
| `chat.js` | People panel: presence roster, take-turns shortcut, chat bubbles, pins, notes; the chat sheet |
|
|
232
233
|
| `avatar.js` | People's avatars (their picture, else initials) and colors, and folders' colors |
|
|
234
|
+
| `running-board.js` | Running now, in the conversation's place: the server's `running/board` every 2 seconds, the Coming up timeline (a lane per session, schedules as marks, how long each has been at work), the filters, the session matrix (Now and Schedule), Needs you, Next up, the schedule selected, and the phone's layout |
|
|
233
235
|
| `subagents-board.js` | The subagents board: every subagent in every session (the server's `subagents` events, while it shows), soft state-colored cells and rounded session rows, a sub-tile for each at work saying what it does now, the proportional state bar and filter pills, Needs you, the selected detail card (its peek), the arrows, and the phone's layout |
|
|
234
236
|
| `extension-ui.js` | Extensions' browser modules: loading them as `hello` lists them (`server.ui`), `pocket` (the app's API for them), and what they add: rail buttons (`ExtensionRailButtons`), menu rows, launcher actions, pages in the conversation's place (`ExtensionPage`, `state.page`), panels beside it (`ExtensionPanel`, `state.extPanel`, with `ExtensionPanelButtons` in the top bar and `extensionPlaces` in the places), status-line items (`extensionStatusItems`, drawn by `composer.js`), sheets (`ExtensionSheet`), and the session list's chips, words, filters, and actions (`sessionChips`, `sessionWords`, `sessionFilters` and `sessionFilterTest`, `sessionActions`, drawn by `sessions.js`, `sheets/session.js`, and `launcher.js`); one that fails, alone, and how their tools' calls show (`pocket.toolCall`, given to `calls.js` and `turns.js`) |
|
|
235
237
|
| `sessions.js` | The sidebar: the rail (`RailNav`: the tools, you, and, folded, numbered sessions) and the session list beside it (sidebar, drawer, a phone's home screen), a line per session, with extensions' chips under its title; extensions' filters beside the search; selecting rows and archiving them with undo (`setArchived`), and extensions' actions in the bar for them, and a touch screen's long press on a row, which opens `sheets/session.js`; linked sessions under the one that started them, with branch lines (`session-tree.js`, the tree as data); and Priority (`priorityGroups`, `slotOf`, `needOf`): sessions by what they ask of you, with a call open in its row (`NeedAsk`), dismissing failures, and marking sessions read, each with an undo where one is possible; the rail's count of sessions that need you (`needsYouCount`) |
|
|
@@ -248,7 +250,7 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
|
|
|
248
250
|
| `files-panel.js` | The Files tile: whether it is open and on which tab, the folder's tree (folders read as they open), Go to file, the open file beside the tree, and the Changes tab |
|
|
249
251
|
| `diff.js` | The diff viewer: one file's diff (unified or split, line numbers, colors, changed words, hidden lines on request), `DiffBlock` for tool calls and replies, and `DiffReview`, every change file by file with viewed marks |
|
|
250
252
|
| `diff-parse.js` | Diffs as data, without the DOM: unified diffs and Pi's edit format as files, hunks, and lines; rows that pair changed lines by likeness; the words that changed |
|
|
251
|
-
| `rich.js` | Code blocks in replies that show more than code (a page previewed, with Run; an SVG; a diff), given to `Markdown` at load (`setRichBlock`); `InlineArtifact`, the card of an
|
|
253
|
+
| `rich.js` | Code blocks in replies that show more than code (a page previewed, with Run; an SVG; a diff), given to `Markdown` at load (`setRichBlock`); `InlineArtifact`, the card of an inline artifact call (the same block, named by the artifact and its version, with Open, fetching that version's page from `/a/…`); `HtmlPreview`, `Highlighted` |
|
|
252
254
|
| `run-frame.js` | `RunFrame`: a reply's HTML (or an inline card's page, as its artifact) run on a tap, in the server's sandboxed `/a/frame` page, sized to fit it |
|
|
253
255
|
| `highlight.js` | Syntax colors without dependencies: `highlightLines` gives escaped HTML with flat `hl-` spans per line, which `diff.js` marks changed words in |
|
|
254
256
|
|