pi-pocket 0.30.0-beta.2 → 0.30.0-beta.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/docs/architecture.md +5 -1
- package/docs/desktop-app.md +3 -3
- package/docs/examples/time-gap.ts +40 -0
- package/docs/extensions/modules.md +1 -1
- package/docs/extensions/policies/api-stability.md +3 -2
- package/docs/extensions/reference/api-versions.md +1 -0
- package/docs/extensions/reference/host.md +44 -1
- package/docs/extensions/reference/types.md +2 -2
- package/docs/extensions/services-settings.md +1 -0
- package/docs/extensions/turn-notes.md +82 -0
- package/docs/extensions.md +1 -0
- package/docs/features.md +2 -1
- package/docs/macos.md +10 -8
- package/docs/map.md +7 -3
- package/docs/windows.md +21 -15
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/server/app-events.ts +5 -2
- package/src/server/app.ts +92 -8
- package/src/server/artifact-state.ts +6 -4
- package/src/server/artifacts.ts +192 -0
- package/src/server/commands.ts +40 -11
- package/src/server/docs.ts +70 -6
- package/src/server/dropin-config.ts +144 -0
- package/src/server/entry-format.ts +8 -0
- package/src/server/extension-document-imports.ts +39 -3
- package/src/server/extensions/artifacts.ts +22 -1
- package/src/server/extensions/design/system-routes.ts +3 -1
- package/src/server/extensions/session-cleanup/index.js +376 -0
- package/src/server/extensions/session-cleanup/style.css +92 -0
- package/src/server/extensions/session-cleanup.ts +71 -0
- package/src/server/host.ts +12 -0
- package/src/server/http/conversation-routes.ts +11 -0
- package/src/server/linked-sessions.ts +7 -2
- package/src/server/projection.ts +15 -0
- package/src/server/reload.ts +27 -17
- package/src/server/room.ts +8 -3
- package/src/server/session-cleanup.ts +592 -0
- package/src/server/share.ts +10 -0
- package/src/server/turn-notes.ts +254 -0
- package/src/server/workspace.ts +4 -6
- package/types/pocket.d.ts +69 -0
- package/web/rich.js +34 -2
- package/web/sheets/viewers.js +88 -24
- package/web/store.js +3 -0
- package/web/style.css +49 -0
- package/web/transcript.js +23 -0
- package/web/ui.js +1 -0
package/AGENTS.md
CHANGED
|
@@ -7,7 +7,7 @@ Pi Pocket is often edited from inside itself, while it runs. [docs/map.md](docs/
|
|
|
7
7
|
- `web/**` changes reload every open browser right away. Keep the app loadable after each save: a syntax error blanks the screen for everyone, including you. Check with `node --check web/<file>.js` after editing.
|
|
8
8
|
- `src/server/extensions/*.ts` changes are reinstalled into the running server. A file that fails to load keeps its previous version and reports the error. Each module default-exports `(host, web) => Extension | Extension[] | void`, possibly async (`web` adds routes and a browser module to the app: [docs/extensions/app.md](docs/extensions/app.md)). Start each module with a `/** … */` comment: its first sentence is the description in the app's Extensions sheet, where the owner can turn modules off (a module that is off is not loaded, even when edited).
|
|
9
9
|
- Other `src/server/**` changes need a restart (menu → Restart server). Running work resumes after it, but a tool call cut off mid-run that is not replay-safe comes back as interrupted. Do not restart while your own tool call is running; finish the edit, run `npm run check` and `npm test`, then ask the user to restart.
|
|
10
|
-
- The owner's drop-in extensions in `~/.pi-pocket/extensions/` load the same way, after the built-in ones, and stay off until the owner turns them on.
|
|
10
|
+
- The owner's drop-in extensions in `~/.pi-pocket/extensions/` load the same way, after the built-in ones, and stay off until the owner turns them on. They import Pi Pocket's packages by name with no link (the resolve hook in `src/server/extension-document-imports.ts`); a `node_modules` link and a `tsconfig.json` there serve editors.
|
|
11
11
|
- Document kinds in `src/server/docs.ts` are stored data. Do not rename them, or change their scope, history, or fork settings: Pi Durable checks those against what is stored.
|
|
12
12
|
- The server is plain TypeScript run by Node's type stripping: only erasable syntax (no enums, no parameter properties, no namespaces). Imports use `.ts` extensions.
|
|
13
13
|
- Code style is Prettier (`.prettierrc.json`: 4 spaces, 100 columns) plus ESLint's layout rules (`eslint.config.js`): braces on every `if` and loop, and a blank line after declarations, around blocks, and before `return` and `throw`. Run `npm run format` after editing. Prettier leaves the markup in `html` templates alone, so lay it out by hand the same way: 4 spaces per level, and a tag that runs past 100 columns gets one attribute per line and its children on their own lines. In htm a line break is not a space: break only where there is no space, or between tags, never inside running text.
|
package/docs/architecture.md
CHANGED
|
@@ -53,6 +53,8 @@ Extensions never see `PocketApp`. They get `PocketHost` (`host.ts`), whose funct
|
|
|
53
53
|
|
|
54
54
|
`host.pendingApprovals` (`pending-approvals.ts`) observes the internal approval service in `host.ts`. It filters waits for the source session's requester and everyone who can see the source. It does not pass on commands, arguments, reasons, or answers. The guard hook keeps a wait's first creation time in its Durable call memo, so a resumed run can show the same wait. Approval decisions still use the app's existing paths.
|
|
55
55
|
|
|
56
|
+
`host.annotateTurns` (`turn-notes.ts`) relies on Pi Durable's admission: an input to an idle conversation with an empty `pi.inbox` is placed in the admitting commit, so `Commands.submit` admits it with `submit(tx, draft)` and appends each `pocket.turn-note` entry after it in that commit. A queued input is placed later by Durable's boundary, which no Pocket code joins, so it gets no note. Pi Durable would need an input draft that carries its own entries (placed at the same boundary, dropped on withdraw) for queued turns.
|
|
57
|
+
|
|
56
58
|
## Workspace execution providers
|
|
57
59
|
|
|
58
60
|
`PocketApp` selects the execution environment by the session's working folder. Local folders keep the existing Node environment; URI workspaces use the last registered provider for their scheme. Removal restores the previous registration, and a missing provider fails closed. Resolution checks the provider identity and cancellation after awaited work. Only the owner can use a workspace URI. The provider's module, a drop-in outside the core package, owns host-key trust, connections, remote project context, and cleanup. Files/Git actions and managed worktrees remain local-only.
|
|
@@ -145,7 +147,7 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
|
|
|
145
147
|
Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project, for everywhere, or for one session. A project is keyed by the real path of its git common folder (`git rev-parse --git-common-dir`), so a repository and all its worktrees share lessons; outside a repository, by the folder itself. `Memory` (`memory.ts`) works out a folder's project (kept a minute per folder) and keeps the rules:
|
|
146
148
|
|
|
147
149
|
- The memory extension's section renders, before each request, the lessons in force for the conversation's folder: its project's, everywhere's, and its session's own, not pending, oldest first. It reads committed state only, so it renders the same text until a lesson changes. PiP has no project: it gets everywhere's and its own.
|
|
148
|
-
- **Session lessons** (since 0.29.0) are stored as a project whose key no folder has: `project` is `pocket-session:<root id>` (`sessionKey`, `sessionOf`, `scopeOf`), and `projectName` is `session “<title>”`. A project key is always an absolute path or a `scheme://` workspace address, so it never matches one. A server from before them (0.29.0-beta.3 and older) reads such a lesson as some other project's: it puts it in no prompt and no session's sheet, never everywhere, and lists one that waits in the owner's pending queue under that name (checked by opening a data folder written by this code with beta 3's). The key is the session's root (`rootOf`), so its subagents share them; a linked session is a root of its own. Because the lessons are in the prompt's section, not the transcript, they last through compaction and restarts. Each session keeps `MAX_SESSION_LESSONS` (20) approved ones in a room of its own, and a person's waiting session lessons count against `MAX_PENDING` in that session only, and against `MAX_PENDING_SESSIONS` (40) in all sessions. A fork (`commands.ts` `#fork`, in the fork's own commit) copies the parent's session lessons in force as its own, with new ids and no call key; pending ones and proposals stay with the parent.
|
|
150
|
+
- **Session lessons** (since 0.29.0) are stored as a project whose key no folder has: `project` is `pocket-session:<root id>` (`sessionKey`, `sessionOf`, `scopeOf`), and `projectName` is `session “<title>”`. A project key is always an absolute path or a `scheme://` workspace address, so it never matches one. A server from before them (0.29.0-beta.3 and older) reads such a lesson as some other project's: it puts it in no prompt and no session's sheet, never everywhere, and lists one that waits in the owner's pending queue under that name (checked by opening a data folder written by this code with beta 3's). The key is the session's root (`rootOf`), so its subagents share them; a linked session is a root of its own. Because the lessons are in the prompt's section, not the transcript, they last through compaction and restarts. Each session keeps `MAX_SESSION_LESSONS` (20) approved ones in a room of its own, and a person's waiting session lessons count against `MAX_PENDING` in that session only, and against `MAX_PENDING_SESSIONS` (40) in all sessions. A fork (`commands.ts` `#fork`, in the fork's own commit) copies the parent's session lessons in force as its own, with new ids and no call key; pending ones and proposals stay with the parent. An archived session keeps its lessons, which apply nowhere else; Remove and clean up (`session-cleanup.ts`, since 0.30.0) removes them with the session. The memory extension offers `scope: "session"` only when the running `Memory` lists it in `scopes`, so a newer extension on an older server refuses it rather than saving a lesson for everywhere.
|
|
149
151
|
- Pi proposes, the owner approves. Every lesson Pi saves, and every one a person who is not the owner saves, is pending, and no prompt has it until the owner approves it: what Pi read anywhere in its context could have talked it into one. Pi's (or a guest's) new text for a lesson in force, and Pi's forgetting one, are a `proposal` on the lesson, which stays as it was until the owner approves or discards it. The tool's result names the lesson (`details.lesson`), so the transcript offers Approve and Discard under the call. An approval names what it saw (`POST …/memory/:id/approve` with `{ text }` or `{ forget: true }`); when what waits differs, `change` answers 409, so text or a proposal swapped after the owner looked is not approved with it. Pi proposing the text in force withdraws its own waiting proposal. Pending lessons do not count toward a project's, everywhere's, or a session's cap; approving one does. Only the owner, or whoever saved a lesson, changes or removes it, Pi included (as the person it works for).
|
|
150
152
|
- Pi's adds carry the tool call's key, so a replayed call finds its lesson. A subagent's lesson comes from its session (`rootOf`).
|
|
151
153
|
- Every write adds an activity line to the session's chat in the same commit. `#committed` tells `Memory` when the document changed; it sends tabs a `memory` event, and the Memory sheet and menu fetch the lessons again (`GET /api/c/:id/memory`).
|
|
@@ -262,6 +264,8 @@ Each browser tab is a `Client` (`room.ts`), fed by an event stream or by long po
|
|
|
262
264
|
|
|
263
265
|
On the server, `WebRequest.sessions()` (`http/extension-routes.ts`) is `app.sessions(user)` for the person as they are when the handler asks, cut to `{ id, title, cwd, archived, updatedAt }`: modules check session ids with core's own rule of who sees what. Session tags (`extensions/session-tags.ts`) adds nothing on a server older than 0.20.0 (`host.pocketVersion`): such a server, running when its checkout moves to this file, would turn it on, with none of what it needs. It keeps its tags in its own document, gives each person only those of the sessions they see, and changes them in one commit, all or nothing.
|
|
264
266
|
|
|
267
|
+
**Removing a session** (`session-cleanup.ts`, since 0.30.0; the Session cleanup module is the owner's way to it) never touches Pi Durable's tables: Pi Durable has no way to purge a conversation yet, so the transcript stays in storage. One commit takes the archived session out of the catalogue (`pocket.sessions`), writes its entry in `pocket.deleted` (the session and its subagents' conversation ids, its worktree, and the uploads a live fork still reads), and takes out the webhooks and repository watches that target it, its artifact shares, the public links of modules about it, and its session lessons. Forks go before their parents in one request, and the entry keeps `forkedFrom`, so a live fork still reads uploads through a removed session in between (`app.forkedFrom`, used by `workspace.ts`). A run that started while the plan was made keeps the session. A removed lead takes no linked session's report, as an archived one. Then `#finish` ends its work (a run, schedules, background tasks, the PR watch, the browser page) and removes Pocket's own files: the worktree (never with uncommitted changes; its branch stays), `uploads/<id>`, and `background/<id>`. It marks the entry `done`; every start runs `resume`, which goes on with an entry that has none, so a crash between the commit and the files leaves nothing half done. `canSee` is false for every conversation of a removed session (its subagents' too), for everyone, so no route, tab, delivery, or message reaches it again; tabs that show it get `missing`. Extensions hear `session.removed`. When Pi Durable can purge a conversation, `pocket.deleted` is the list to purge. A session with Pi at work, or whose worktree has uncommitted changes or Pi works in it, stays. Cleaning up (`cleanUp`) removes only the worktrees of archived sessions, with the session's own Remove worktree.
|
|
268
|
+
|
|
265
269
|
Public links (`public-links.ts`, since 0.22.0) are the one way a module answers people with no sign-in. Core keeps the links in `pocket.public-links`, each with its module's name, so `web.links` reaches only its own module's, and `http/link-routes.ts` answers `/l/<token>` only while that module is on (`ExtensionWebs.publicPage`). Core, not the module, closes a link at its time and counts its uses: a use is claimed in a commit before the handler runs, so two posts at once cannot both get in, and given back when the page refuses the post. Every page goes out with a sandbox policy and no script, so it has an opaque origin and the app's cookie gives it nothing. Ask someone (`extensions/ask-someone.ts`) is built on it, with nothing of Pi Pocket's but types, as a drop-in would be.
|
|
266
270
|
|
|
267
271
|
People's values (since 0.22.0) go around Pi, never through it. `host.ask` is an approval with a `form` (`Approvals`, so it waits, notifies, and shows as one): the request that tabs see holds the fields, and the values come only in the answer to the asker, after `answerApproval` checked each field and that the person answering is the one Pi works for (`cannotAllow`). `host.commandEnv` and `host.hide` act in `wrapEnv` (`hidden.ts`), the execution environment the harness builds for each conversation, so bash, `!` commands, codemode, and checks all get the variables and lose the values the same way; an `afterTool` hook of `pocket-core` takes hidden values out of every tool's result before it is stored. `host.browser` (`extension-points.ts`) wraps a `BrowserPage` in a handle with no `evaluate`, and only while the Browser module is on.
|
package/docs/desktop-app.md
CHANGED
|
@@ -17,7 +17,7 @@ The console launcher stays, as **Pi Pocket (console)**: it has the access menu (
|
|
|
17
17
|
|
|
18
18
|
1. **One app per user.** A second start (the Start menu again, Spotlight, the Dock) asks the first one to show its window, then exits. Windows uses a named mutex and event in the session's `Local\` namespace; macOS a distributed notification. `--quit` asks the running one to quit, as its **Quit** does; the installers use it.
|
|
19
19
|
2. **A server that runs already is used.** Each launcher writes `launcher-running.json` in the data folder when its server is ready, and removes it when it quits ([`src/launcher/desktop.ts`](../src/launcher/desktop.ts)): its process, the server's local address, and whether a desktop app started it. The app uses that server when the process is there and `GET /api/pocket/info` answers. **Quit** then leaves it running: another launcher, such as Pi Pocket (console), started it.
|
|
20
|
-
3. **Otherwise the app starts a launcher
|
|
20
|
+
3. **Otherwise the app checks the package, then starts a launcher.** It reads the version in the `package.json` of the `pi-pocket` package in `app\` (Windows) or `app/` (macOS). When there is none, it is older than the app's own version, or (on Windows) `app\setup-finished.txt` is missing, which Setup writes after it copied the package, it shows a message that says what is wrong and to run Setup or the package again, writes it to the log, and starts nothing: a launcher older than the app does not know `--desktop`, and would fail with only "Unknown argument" in the log. A newer package is an in-app update, and starts. The installers put their own package in place, so only an install that did not finish leaves an older one. Then the app starts `pi-pocket --desktop`, with the install's own Node.js. `--desktop` means: this device only (unless `--access` says otherwise), no access menu, no keys, no sign-in link and no QR code in its output, and the choice is not saved as the console's last one. It stops when its standard input closes. The app holds that input: **Quit** closes it, and so does the end of the app, also when it crashes.
|
|
21
21
|
4. **The window signs in.** See below.
|
|
22
22
|
|
|
23
23
|
On Windows the launcher and everything it starts (the server, the commands of the agents, the Edge window) are in a job object that ends with the app, so nothing runs on after it, even when the app is killed. Edge's window closes on **Quit**, with the server it shows. Without Edge, the default browser opens the one-time link; it is not in the job, and stays.
|
|
@@ -41,7 +41,7 @@ On Windows the one-time link is on Edge's command line, and only there: it is sp
|
|
|
41
41
|
|
|
42
42
|
## What the apps rely on
|
|
43
43
|
|
|
44
|
-
A newer installer replaces the app; Menu → **Update Pi Pocket**
|
|
44
|
+
A newer installer replaces the app and its package; Menu → **Update Pi Pocket** replaces only the package. So an installed app runs against newer `pi-pocket` packages, never older ones (it refuses them), and these stay as they are: `--desktop`, `launcher-running.json` (its fields only grow), `/api/pocket/info`, `/api/sign-in-link`, `/login?once=`, and `/api/restart`.
|
|
45
45
|
|
|
46
46
|
## What the window does not do yet
|
|
47
47
|
|
|
@@ -51,4 +51,4 @@ A newer installer replaces the app; Menu → **Update Pi Pocket** does not. So a
|
|
|
51
51
|
|
|
52
52
|
## How it is tested
|
|
53
53
|
|
|
54
|
-
[`test/launcher-desktop.test.ts`](../test/launcher-desktop.test.ts) runs `--desktop`: `launcher-running.json`, the one-time link, no token in the output, and the stop when its input closes. On each pull request, [`windows.yml`](../.github/workflows/windows.yml) and [`macos.yml`](../.github/workflows/macos.yml) install the app, open it as the Start menu or Finder does, and check: no console or Terminal window, the server on this computer only, a window that signed in (on Windows, Edge spent the one-time link; on macOS, the window's own `/api/me` answers 200), no token in the log or on a command line, one instance only, and **Quit** that stops the launcher, the server, and the window. They also take a screenshot of the window. Nobody has tried them yet on a real PC or Mac, only on GitHub's runners.
|
|
54
|
+
[`test/launcher-desktop.test.ts`](../test/launcher-desktop.test.ts) runs `--desktop`: `launcher-running.json`, the one-time link, no token in the output, and the stop when its input closes. On each pull request, [`windows.yml`](../.github/workflows/windows.yml) and [`macos.yml`](../.github/workflows/macos.yml) install the app, open it as the Start menu or Finder does, and check: no console or Terminal window, the server on this computer only, a window that signed in (on Windows, Edge spent the one-time link; on macOS, the window's own `/api/me` answers 200), no token in the log or on a command line, one instance only, and **Quit** that stops the launcher, the server, and the window. They also take a screenshot of the window. Then they write an older version into the package's `package.json`, and check that the app shows its message, writes it to the log, and starts no launcher. Nobody has tried them yet on a real PC or Mac, only on GitHub's runners.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Time gap: tells Pi how long a session was quiet when a person writes after a long silence.
|
|
3
|
+
*/
|
|
4
|
+
import type { Host, Turn, Web } from "../../types/pocket.d.ts";
|
|
5
|
+
|
|
6
|
+
const HOUR = 3_600_000;
|
|
7
|
+
|
|
8
|
+
/** "About 2 days" or "About 5 hours", or undefined for a gap shorter than 3 hours. */
|
|
9
|
+
function gap(turn: Turn): string | undefined {
|
|
10
|
+
if (turn.previousActivityAt === undefined) {
|
|
11
|
+
return undefined;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
const hours = (turn.at - turn.previousActivityAt) / HOUR;
|
|
15
|
+
|
|
16
|
+
if (hours < 3) {
|
|
17
|
+
return undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
const days = Math.round(hours / 24);
|
|
21
|
+
|
|
22
|
+
return hours < 36 ? `About ${Math.round(hours)} hours` : `About ${days} days`;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export default function createTimeGap(host: Host, web: Web) {
|
|
26
|
+
// A server older than 0.30.0 has no turn notes: do nothing there.
|
|
27
|
+
if (typeof host.annotateTurns !== "function") {
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
web.onDispose(
|
|
32
|
+
host.annotateTurns("time-gap", (turn) => {
|
|
33
|
+
const passed = gap(turn);
|
|
34
|
+
|
|
35
|
+
return passed === undefined
|
|
36
|
+
? undefined
|
|
37
|
+
: `<system-reminder>\n${passed} have passed since the previous message.\n</system-reminder>`;
|
|
38
|
+
}),
|
|
39
|
+
);
|
|
40
|
+
}
|
|
@@ -5,7 +5,7 @@ A module is one file that Pi Pocket loads. This page tells what the file must be
|
|
|
5
5
|
## The file
|
|
6
6
|
|
|
7
7
|
- **TypeScript that Node runs as it is.** Use only erasable syntax: no `enum`, no `namespace`, and no constructor parameter properties. A local import ends in `.ts`.
|
|
8
|
-
- **Packages by name.** Import `@earendil-works/pi-durable`, `@earendil-works/pi-ai`, `@earendil-works/pi-mcp` (Pi's MCP client), and the other packages of Pi Pocket by name.
|
|
8
|
+
- **Packages by name.** Import `@earendil-works/pi-durable`, `@earendil-works/pi-ai`, `@earendil-works/pi-mcp` (Pi's MCP client), and the other packages of Pi Pocket by name. Pi Pocket resolves a package that a drop-in does not have of its own from its own packages, so a drop-in gets the same modules that the server runs. This needs no link: it also works where the system refuses links. A package in the drop-in's own `node_modules` folder comes first. Where links work, the drop-in folder also has a `node_modules` link to Pi Pocket's packages, for tools that read the folder.
|
|
9
9
|
- **A name of its own.** The file name must be different from the name of each built-in module. For example, Pi Pocket does not load a drop-in named `browser.ts`. Give each extension and tool in it a name with a prefix of your own, for example `my-words` and `my_word_count`. Pi Pocket does not load a module that takes a name that Pi Pocket keeps (such as `pocket-…`, or a built-in tool's), or a name that another module has. See [Names](reference/names.md).
|
|
10
10
|
- **A description.** Start the file with a `/** … */` comment. Its first sentence says what the module does. The Extensions sheet shows it.
|
|
11
11
|
|
|
@@ -18,7 +18,7 @@ Each item below is public as the reference and the guides describe it: its names
|
|
|
18
18
|
|
|
19
19
|
### 1. The module
|
|
20
20
|
|
|
21
|
-
- A `.ts` file in the drop-in folder (`extensions/` in the data folder),
|
|
21
|
+
- A `.ts` file in the drop-in folder (`extensions/` in the data folder), which imports Pi Pocket's packages by name.
|
|
22
22
|
- The default export `(host, web)`. It can be `async`. It returns one extension, a list, or nothing. Pi Pocket installs all of it or none of it.
|
|
23
23
|
- `export const pocketApi`.
|
|
24
24
|
- The first sentence of the module's `/** … */` comment, which is its description.
|
|
@@ -54,6 +54,7 @@ These members are public:
|
|
|
54
54
|
- `fetchPublic(url, init)` (experimental, since 0.20.0)
|
|
55
55
|
- `ask(request, context)`, `hide(value)`, `commandEnv(provider)`, `browser(conversationId, options)` (experimental, since 0.22.0: [People's values and the browser](../people-values.md))
|
|
56
56
|
- [`pendingApprovals`](../reference/host.md#pendingapprovals): read-only approval snapshots and events (experimental, since 0.30.0)
|
|
57
|
+
- [`annotateTurns(name, annotate)`](../reference/host.md#annotateturns), `Turn`, and `TurnAnnotator`: notes for the model after a person's message (experimental, since 0.30.0: [Turn notes](../turn-notes.md))
|
|
57
58
|
- `on(event, listener)` and the events of `AppEvents` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md))
|
|
58
59
|
|
|
59
60
|
These members are on `host` for Pi Pocket's own built-in extensions: `guard`, `approvals`, `schedules`, `goals`, `browsers`, `memory`, `watches`, `repoWatches`, `gallery`, `updates`, `pip`, `pipCompaction`, `toolNames`, `stopToolCall`, `waitsForLimit`, and `alertOwner`, and `linkedSessions.activity`, `linkedSessions.stopCall`, and `linkedSessions.onLedRun`. They are **internal**. A drop-in can read them, but their shapes can change in any release. One of them becomes public only through a request for an extension point ([core-or-extension.md](core-or-extension.md#ask-for-a-new-extension-point)).
|
|
@@ -127,7 +128,7 @@ The host's members do not change while modules reload. A new member comes only a
|
|
|
127
128
|
|
|
128
129
|
## Packages from Earendil
|
|
129
130
|
|
|
130
|
-
Extensions import `@earendil-works/pi-durable`, `@earendil-works/pi-ai`, and the other packages that Pi Pocket has. Earendil makes them, not Pi Pocket. Pi Durable is experimental, and its API can change between its releases. Pi Pocket pins their versions in `package.json`, and a drop-in gets the same versions
|
|
131
|
+
Extensions import `@earendil-works/pi-durable`, `@earendil-works/pi-ai`, and the other packages that Pi Pocket has. Earendil makes them, not Pi Pocket. Pi Durable is experimental, and its API can change between its releases. Pi Pocket pins their versions in `package.json`, and a drop-in gets the same versions: Pi Pocket resolves them from its own packages.
|
|
131
132
|
|
|
132
133
|
- **A1. The release notes name each update of a pinned package** in "For extension authors".\
|
|
133
134
|
_Reason:_ an author can then find the cause when a module breaks after an update.
|
|
@@ -104,3 +104,4 @@ Each member in the reference has its own Since line. These parts came together:
|
|
|
104
104
|
| `options.artifact` and `options.version` in `pocket.openConversation`: open an artifact of that session (experimental) | 0.29.0 |
|
|
105
105
|
| `subagents: "always"` on a tool: the tool comes with every subagent that has a tool list (experimental) | 0.29.0 |
|
|
106
106
|
| `host.pendingApprovals`: read-only approval snapshots and events (experimental) | 0.30.0 |
|
|
107
|
+
| `host.annotateTurns`: notes for the model after a person's message (experimental) | 0.30.0 |
|
|
@@ -394,6 +394,18 @@ Since 0.22.0 · Experimental
|
|
|
394
394
|
|
|
395
395
|
A session's browser page: the one that Pi's `browser` tool and the people in the session use. With `open: true`, it opens the page when it is not open. It is `undefined` while the Browser module is off, and without `open`, when no page is open. See [`BrowserPageHandle`](#browserpagehandle).
|
|
396
396
|
|
|
397
|
+
## Turn notes
|
|
398
|
+
|
|
399
|
+
### `annotateTurns`
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
annotateTurns(name: string, annotate: TurnAnnotator): () => void;
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Since 0.30.0 · Experimental
|
|
406
|
+
|
|
407
|
+
Adds a note for the model right after a person's message, as a separate entry of the transcript. `annotate` gets the [`Turn`](#turn) and returns the note's text, or `undefined` for none. Pi Pocket stores the note in the same commit as the message, and never computes it again. The model reads `Note from extension <name>:` and a line break before the text. Only a message placed at once gets notes: Pi does not work in the session, and nothing is queued. A queued message, an Interrupt, a scheduled message, and PiP's own conversation get none. The annotators of all modules have 2 seconds together; one that is late, throws, or returns more than 4,000 characters adds nothing, and the session shows a warning. `name` is 1 to 60 letters, digits, `.`, `_`, `:`, or `-`, and the transcript shows it with each note. Pass the returned function to `web.onDispose`. See [Turn notes](../turn-notes.md).
|
|
408
|
+
|
|
397
409
|
## Notices and text
|
|
398
410
|
|
|
399
411
|
### `notice`
|
|
@@ -698,6 +710,7 @@ interface AppEvents {
|
|
|
698
710
|
};
|
|
699
711
|
"session.renamed": { conversationId: number; title: string };
|
|
700
712
|
"session.archived": { conversationId: number; archived: boolean };
|
|
713
|
+
"session.removed": { conversationId: number };
|
|
701
714
|
"message.sent": {
|
|
702
715
|
conversationId: number;
|
|
703
716
|
by: string;
|
|
@@ -721,6 +734,7 @@ What each event's listener gets.
|
|
|
721
734
|
|
|
722
735
|
- `session.created`: a session in the list was made, by a person, a fork (`forkedFrom`), a linked start (`linkedFrom`), or a resend. `createdBy` is a person's id. Subagents are not sessions in the list, and send none.
|
|
723
736
|
- `session.renamed`, `session.archived`: its new title, or whether it is archived now.
|
|
737
|
+
- `session.removed` (since 0.30.0): the owner removed an archived session from the app (Session cleanup). Its id is not shown again: drop what your module keeps for it.
|
|
724
738
|
- `message.sent`: a person's message to Pi, a steer or a queued one too. `by` is their id. `text` is the words as stored, with values that extensions hide already hidden and attachments left out. `via` names what sent it for them, such as PiP or a schedule.
|
|
725
739
|
- `run.started`, `run.ended`: Pi started or stopped working in a conversation. `conversationId` is that conversation, a session's or a subagent's; `session` is the session it belongs to. Since 0.28.0, `run.ended` also says how the run stopped: `outcome` is `done` when it finished, `failed` when it gave up, or `aborted` when it was stopped. `failure` is why it gave up, the same short line the session list shows, and only when `outcome` is `failed`. A session's failure stands until a later run starts.
|
|
726
740
|
|
|
@@ -732,7 +746,7 @@ type AppEventName = keyof AppEvents;
|
|
|
732
746
|
|
|
733
747
|
Since 0.22.0 · Experimental
|
|
734
748
|
|
|
735
|
-
The name of an event: `"session.created"`, `"session.renamed"`, `"session.archived"`, `"message.sent"`, `"run.started"`, or `"run.ended"`.
|
|
749
|
+
The name of an event: `"session.created"`, `"session.renamed"`, `"session.archived"`, `"session.removed"`, `"message.sent"`, `"run.started"`, or `"run.ended"`.
|
|
736
750
|
|
|
737
751
|
## Types for asking, hiding, and the browser
|
|
738
752
|
|
|
@@ -850,6 +864,34 @@ Since 0.22.0 · Experimental
|
|
|
850
864
|
|
|
851
865
|
Gives the variables to add to one command. A name is letters, digits, and `_`, not starting with a digit; a value has no NUL. A variable that breaks these is left out. The variables of all providers for one command are 256 KB at most.
|
|
852
866
|
|
|
867
|
+
### `Turn`
|
|
868
|
+
|
|
869
|
+
```ts
|
|
870
|
+
interface Turn {
|
|
871
|
+
readonly conversationId: number;
|
|
872
|
+
readonly by: string;
|
|
873
|
+
readonly via?: string;
|
|
874
|
+
readonly text: string;
|
|
875
|
+
readonly at: number;
|
|
876
|
+
readonly previousActivityAt?: number;
|
|
877
|
+
readonly signal: AbortSignal;
|
|
878
|
+
}
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
Since 0.30.0 · Experimental
|
|
882
|
+
|
|
883
|
+
One person's message, before Pi answers it: its session, the person's id, what sent it for them (`via`, when it is not their own typing), their words as stored (hidden values hidden, attachments left out), and when it came. `previousActivityAt` is the newest time of a message, an answer, or a tool result among the session's last 32 entries, also from before a reset. It is `undefined` when there is none. `signal` aborts when the time for annotators ends.
|
|
884
|
+
|
|
885
|
+
### `TurnAnnotator`
|
|
886
|
+
|
|
887
|
+
```ts
|
|
888
|
+
type TurnAnnotator = (turn: Turn) => string | undefined | Promise<string | undefined>;
|
|
889
|
+
```
|
|
890
|
+
|
|
891
|
+
Since 0.30.0 · Experimental
|
|
892
|
+
|
|
893
|
+
Gives the text of a note for one turn, at most 4,000 characters, or `undefined` for no note. Pi Pocket trims the text; an empty text is no note.
|
|
894
|
+
|
|
853
895
|
### `BrowserTarget`
|
|
854
896
|
|
|
855
897
|
```ts
|
|
@@ -946,6 +988,7 @@ The host has more members, for Pi Pocket's built-in modules only. They are not i
|
|
|
946
988
|
- `pip`: what the tools of PiP, the owner's assistant, do.
|
|
947
989
|
- `pipCompaction`: PiP's own summaries when its context is compacted.
|
|
948
990
|
- `gallery`: the extension gallery, for its own routes.
|
|
991
|
+
- `sessionCleanup` (since 0.30.0): archived sessions' plans, worktrees cleaned up, and sessions removed from the app, for the Session cleanup module.
|
|
949
992
|
- `toolNames`: the names of the tools that the modules that are on give now (built-in and drop-in), for codemode's Only mode.
|
|
950
993
|
- `stopToolCall`, `waitsForLimit`, `alertOwner` (since 0.29.0): for the stall watches of Subagents and Agent Teams. They stop one running call, say whether a run waits for a provider's limit, and tell the owner (a notice and a push).
|
|
951
994
|
- `linkedSessions.activity`, `linkedSessions.stopCall`, `linkedSessions.onLedRun` (since 0.29.0): for the stall watch of Agent Teams. They give the led sessions at work, stop a stuck call of a led session, and call back when a led session starts a run.
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
Use one of these:
|
|
8
8
|
|
|
9
|
-
1. **`_pocket.d.ts` in the drop-in folder.** Pi Pocket makes this link to its types file each time that it starts
|
|
9
|
+
1. **`_pocket.d.ts` in the drop-in folder.** Pi Pocket makes this link to its types file each time that it starts. Its leading `_` keeps it from loading as a module. The same import then works on all machines. If you point the link at another readable file, such as your own checkout's types, Pi Pocket leaves it as it is. A file of your own with this name also stays.
|
|
10
10
|
2. **The path in Pi Pocket's folder:** `/path/to/pi-pocket/types/pocket.d.ts`.
|
|
11
11
|
3. **The copy on the documentation site:** `https://tannermidd.github.io/pi-pocket/docs/pocket.d.ts`. It is for the latest release.
|
|
12
12
|
|
|
@@ -37,7 +37,7 @@ export default function setup(pocket) {
|
|
|
37
37
|
|
|
38
38
|
From a browser module in a folder, the path is `../_pocket.d.ts`.
|
|
39
39
|
|
|
40
|
-
The types file imports types from Pi Durable, Pi AI, and Preact by package name. The drop-in folder's `node_modules` link gives
|
|
40
|
+
The types file imports types from Pi Durable, Pi AI, and Preact by package name. The drop-in folder's `tsconfig.json` gives them, also where the system refuses links: Pi Pocket writes it at each start, and its `paths` lead each of Pi Pocket's packages to its types. Its first line says that Pi Pocket made it, and Pi Pocket refreshes it when its folders change. Do not edit it. To use your own settings, replace it with a file of your own, without that first line: Pi Pocket then leaves it as it is. Where links work, the drop-in folder's `node_modules` link to Pi Pocket's packages gives the types to tools that do not read `tsconfig.json`.
|
|
41
41
|
|
|
42
42
|
`tsc` skips `<name>.js` when there is a `<name>.ts`. To check both with `tsc`, put the browser module in the folder `<name>/`. An editor checks each file that you open.
|
|
43
43
|
|
|
@@ -17,6 +17,7 @@ if (typeof host.on !== "function" || typeof web.provide !== "function") {
|
|
|
17
17
|
| `session.created` | A session is made: by a person, a fork, a linked start, or a resend. |
|
|
18
18
|
| `session.renamed` | A session gets a new title. |
|
|
19
19
|
| `session.archived` | A session is archived, or brought back. |
|
|
20
|
+
| `session.removed` | The owner removed an archived session from the app (since 0.30.0). |
|
|
20
21
|
| `message.sent` | A person sends Pi a message, a steer or a queued one too. |
|
|
21
22
|
| `run.started` | Pi starts to work in a session or a subagent. |
|
|
22
23
|
| `run.ended` | Pi stops: the run finished (`done`), gave up (`failed`), or was stopped (`aborted`). |
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Turn notes
|
|
2
|
+
|
|
3
|
+
An extension can add a short note for the model to a person's message. For example, a note can say how much time has passed since the last activity in the session. Use `host.annotateTurns`. Its shape is in [the host reference](reference/host.md#annotateturns).
|
|
4
|
+
|
|
5
|
+
**Experimental, since 0.30.0.** It can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)). A module for an older server checks that `host.annotateTurns` is there, and a gallery entry that needs it sets `minPocket` to `0.30.0`.
|
|
6
|
+
|
|
7
|
+
## What a note is
|
|
8
|
+
|
|
9
|
+
- A note is a separate entry in the transcript, right after the person's message. The person's message, its attachments, and its sender do not change.
|
|
10
|
+
- Pi Pocket stores the note in the same commit as the message. A restart cannot lose it or write it two times. A retry of a message that is already stored does not ask the annotators again. Two tries of one message at the same moment can both ask them, but only one note is stored.
|
|
11
|
+
- The model reads the note as a user message, on this turn and on all later turns, until compaction or a reset removes it. Compaction treats it like any other entry.
|
|
12
|
+
- The model reads the note's source first: `Note from extension <name>:` on its own line, then the text. `<name>` is the name the module gave to `annotateTurns`, and a note cannot change it. So a note that tries to look like a person or another source still shows where it came from. Pi Pocket writes this label into the stored entry one time, when it stores the note.
|
|
13
|
+
- A note never starts a run. The person's message starts the run, as usual.
|
|
14
|
+
- Pi Pocket writes the text one time and does not compute it again. Nothing older in the transcript changes, so the provider's prompt cache stays valid for each earlier request.
|
|
15
|
+
- The transcript shows the note as "Note for Pi from `name`", with its first 3 lines of text. A tap shows all of it. It never shows as a person's words.
|
|
16
|
+
|
|
17
|
+
## Which messages get notes
|
|
18
|
+
|
|
19
|
+
Only a message that Pi Pocket can place at once gets notes. That is a message to a session where Pi does not work and nothing is queued.
|
|
20
|
+
|
|
21
|
+
- **A queued message gets no note.** Pi Durable puts a queued message in the context when it is its turn: at the end of the run for a follow-up, or after the tool round for a steer. A note could not go into the context at the same time, so Pi Pocket does not ask the annotators.
|
|
22
|
+
- A message sent with **Interrupt** gets no note, because it stops a run first.
|
|
23
|
+
- Notes come for every message that goes through Pi Pocket's message path: messages that people send in the app, a plan that a person approves, and messages sent for a person by PiP, by a linked session, by `host.sessions.start`, by `host.inbox` (webhooks, the relay), and by PR and repository watches. `turn.via` names what sent a message for a person.
|
|
24
|
+
- Scheduled messages, a message sent again (Resend), reports of background tasks and subagents, and PiP's own conversation get no notes.
|
|
25
|
+
|
|
26
|
+
## The annotator
|
|
27
|
+
|
|
28
|
+
`annotate(turn)` gets the session, the person, the message's text, when it came (`at`), and the newest time of a message, an answer, or a tool result among the session's last 32 entries (`previousActivityAt`). These entries can come from before a reset. It returns the note's text, or `undefined` for no note. It can be `async`.
|
|
29
|
+
|
|
30
|
+
- Keep it fast. The message waits for the annotators, for 2 seconds at most together. An annotator that is late, throws, or returns more than 4,000 characters adds nothing, and the session shows a warning. The message goes on.
|
|
31
|
+
- `turn.signal` aborts when the 2 seconds end.
|
|
32
|
+
- Several modules can add annotators. Their notes come in the order the modules added them.
|
|
33
|
+
- The note's text is model input. Write it for the model, and do not put a value there that people must not see: everyone in the session can read the note.
|
|
34
|
+
|
|
35
|
+
## An example: time gaps
|
|
36
|
+
|
|
37
|
+
This module tells the model when a person writes after a long silence.
|
|
38
|
+
|
|
39
|
+
```typescript title="time-gap.ts"
|
|
40
|
+
/**
|
|
41
|
+
* Time gap: tells Pi how long a session was quiet when a person writes after a long silence.
|
|
42
|
+
*/
|
|
43
|
+
import type { Host, Turn, Web } from "./_pocket.d.ts";
|
|
44
|
+
|
|
45
|
+
const HOUR = 3_600_000;
|
|
46
|
+
|
|
47
|
+
/** "About 2 days" or "About 5 hours", or undefined for a gap shorter than 3 hours. */
|
|
48
|
+
function gap(turn: Turn): string | undefined {
|
|
49
|
+
if (turn.previousActivityAt === undefined) {
|
|
50
|
+
return undefined;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const hours = (turn.at - turn.previousActivityAt) / HOUR;
|
|
54
|
+
|
|
55
|
+
if (hours < 3) {
|
|
56
|
+
return undefined;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const days = Math.round(hours / 24);
|
|
60
|
+
|
|
61
|
+
return hours < 36 ? `About ${Math.round(hours)} hours` : `About ${days} days`;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export default function createTimeGap(host: Host, web: Web) {
|
|
65
|
+
// A server older than 0.30.0 has no turn notes: do nothing there.
|
|
66
|
+
if (typeof host.annotateTurns !== "function") {
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
web.onDispose(
|
|
71
|
+
host.annotateTurns("time-gap", (turn) => {
|
|
72
|
+
const passed = gap(turn);
|
|
73
|
+
|
|
74
|
+
return passed === undefined
|
|
75
|
+
? undefined
|
|
76
|
+
: `<system-reminder>\n${passed} have passed since the previous message.\n</system-reminder>`;
|
|
77
|
+
}),
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The same module is in [examples/time-gap.ts](../examples/time-gap.ts).
|
package/docs/extensions.md
CHANGED
|
@@ -26,6 +26,7 @@ This page is the map. Read all of it, then only the pages that your task needs.
|
|
|
26
26
|
| Start sessions, and send messages between them | [Starting and messaging sessions](extensions/linked-sessions.md) |
|
|
27
27
|
| Start an ordinary session, like New session | [Starting an ordinary session](extensions/sessions.md) |
|
|
28
28
|
| Give a chat message or a feed's item to a session, as data | [Delivering outside data](extensions/inbox.md) |
|
|
29
|
+
| Add a note for the model to a person's message | [Turn notes](extensions/turn-notes.md) |
|
|
29
30
|
| Add a kind of connection to the relay (a chat service, a feed) | [Relay connectors](extensions/relay.md) |
|
|
30
31
|
| Add to the app: routes, a browser module, commands | [Adding to the app](extensions/app.md) |
|
|
31
32
|
| Name how an input this module sends shows in the transcript | [Adding to the app](extensions/app.md), [`web.presentEntry`](extensions/reference/web.md#presententry) |
|
package/docs/features.md
CHANGED
|
@@ -10,6 +10,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
10
10
|
- **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. Appearance → **Switch sessions with → Tabs** (off until you turn it on, in each browser) also puts the first nine of those sessions in a strip of segments above the top bar, each in its folder's color: the open one fills, one that works pulses, one that waits for you shows in the warning color, and a tap opens it (the open session takes the ninth place when it is further down the list). Choosing Tabs folds the sidebar to its rail, and Sidebar unfolds it; Ctrl/⌘+B still folds and unfolds it either way. On a phone the strip is the bars alone, and the top bar names the open session. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
|
|
11
11
|
- **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
|
|
12
12
|
- **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
|
|
13
|
+
- **Session cleanup** (since 0.30.0, the owner's alone). **Remove and clean up** on an archived session (a held row, a right-click, or selected rows) takes it out of the app for everyone and removes Pi Pocket's own files of it: its worktree (its branch stays), its uploads, and its background logs. Its schedules, background tasks, PR watch, webhooks, repository watches, published artifact links, modules' public page links, and session lessons end too. The confirm says what goes and its size first. The transcript stays in Pi Pocket's database until Pi Durable can remove a conversation; Pi Pocket keeps a list of removed sessions for that. A session where Pi works, or whose worktree has uncommitted changes, stays, and says why; a fork's uploads stay while a fork still shows them. Menu or the launcher → **Clean up archived sessions** looks at the archived sessions not used for 7, 30, or 90 days (or any age): **Remove worktrees** removes their worktrees and keeps the sessions, and **Remove N sessions…** removes them, after the same confirm. A removal cut short by a restart goes on at the next start.
|
|
13
14
|
- **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
|
|
14
15
|
- **The menu.** The top bar's **⋯** opens a 360px popover below it on wide screens, and a bottom sheet on phones. Three columns of rounded place tiles open Files, Changes, Browser, Artifacts, Chat, Find, Launcher (on touch screens), Branch, PiP, and Peeks when available; badges show counts or news, and open places are tinted. Session actions, Subagents, and App rows have right-aligned hints and separate groups. App includes **Keyboard shortcuts** (`?`). Arrows, Home/End, and Tab move through the controls; Esc, Back, Close, or a tap outside closes the menu. Back from a sheet it opened returns to the menu.
|
|
15
16
|
- **Keyboard.** Alt+1…9 jumps to a session (hold Alt to see the numbers), Alt+↑/↓ goes to the previous or next one, Alt+N starts a new one (where Ctrl/⌘+1…9 starts it in a favorite folder), Alt+B opens or closes the browser, Alt+E the Files tile, Alt+T turns Show thinking on or off, Alt+V starts or stops dictation, and `?` lists every shortcut. On a computer, a session opens with the caret in its message box, ready to type; on a touch screen it waits for a tap, so the keyboard does not cover the conversation, and on a Mac a session opened with Alt+1…9 or Alt+↑/↓ leaves the box alone, so the next Alt shortcut still works (Option types characters in a box).
|
|
@@ -67,7 +68,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
67
68
|
- **Roles and invites.** An invite can let someone **steer** or make them **view only** (they read, react, and chat, but cannot send to Pi, approve, or upload). It can cover **every session** or **only this session**, and lasts 15 minutes, an hour, a day, or a week (**Expires after**); either way it works once, and a restart keeps it. Changing what the sheet's invite grants, or how long it lasts, ends the one it showed; **New invite** makes another and leaves the one before working. Only the owner can make an owner invite (**Sign in as me (owner)**): it makes no one new, but signs the device in with the owner's token, so it has full control, works once, and always expires in 15 minutes; rotating the owner token (`--rotate-token`) signs out every device signed in that way, and ends owner invites not yet used. Menu → **People** lists everyone, who is online, and when the others were last here. The owner can change what each person may do or remove them. The session list shows who is in each session, and a dot marks new chat messages.
|
|
68
69
|
- **Notifications.** Menu → **Notifications** turns on push notifications for a device: Pi finished (or Pi stopped with an error, with why: a run that failed with no answer of its own, as when its context could not be compacted, says so too, and the open session keeps a "Run failed" line until the next run starts; since 0.28.1), Pi needs approval, someone @mentioned you, or a chat message in a session you take part in. You only get them while you are not looking at that session. An approval can be denied from the notification, and allowed there when the whole call fits on one short line. The home-screen icon counts the sessions that need you. They need an https address: the Cloudflare Tunnel or Tailscale Serve, or another tunnel such as ngrok in front of **This device only** (`--access local`). On iPhone, add Pi Pocket to the home screen first. The server signs pushes with its own keys in `~/.pi-pocket/push.json`. In a host around Pi Pocket (an app such as Pi Pocket GUI), they come as the app's own notifications, with no https address needed, while the app runs ([docs/embedders.md](embedders.md)).
|
|
69
70
|
- **Built-in browser.** Menu → **Browser** (or Alt+B, `/browser localhost:5173`, or the globe in the top bar while a page is open; on a phone, a dot on the places button by the message box says so) opens a real Chromium page that runs on the server: beside the conversation on wide screens, full screen on phones. Type an address (`localhost:5173`, `example.com`), or (the owner) tap a row under **Running on this machine** on the start screen; a green dot in the rounded address field marks an open page. Tap, drag to scroll, and type into the page (the keyboard button sends text from a phone). The size button switches between fitting the panel (the page follows the panel when it changes size), desktop, phone, and tablet sizes, and the console button shows the page's logs and errors, with a warning-colored error count. Pi's `browser` tool uses the same page: it opens addresses (dev servers, HTML files on the machine, any site), reads a snapshot of the page's text and controls, clicks, types, takes screenshots it can see, reads the console, and runs JavaScript in the page, while everyone in the session watches. Each session has one page, in a browser context of its own; links that open a new tab open there instead, and dialogs are accepted. Anyone in the session can watch; using the page takes steering rights (and the wheel, while take turns is on), the addresses people open show in the chat, and only the owner opens files from the address bar. The browser reaches what the server reaches, `localhost` and its network included, and Lancet Guard does not check it (see SECURITY.md). A restart closes the pages, and each opens again at its last address and size. Where the panel covers the conversation, Esc closes it, unless the page has the keys (then Alt+B does). In plan mode Pi may look at pages but not click, type, or run scripts in them. It needs Chromium, Chrome, Brave, or Edge on the server (or `PI_POCKET_BROWSER`); the owner can turn it off in Extensions, which closes the panel too.
|
|
70
|
-
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. `inline: true` (since 0.28.0, one tool; before it a second tool, `artifact_inline`, sent almost the same schema again on every request) is the same store for HTML only (`content` or `edits`, no path, no `type` but `html`): the call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but an `inline: true` call refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `inline` only in sessions whose `artifact` tool has it (PiP's has not), and says that only a direct call shows a card. Sessions from before 0.28.0 keep their `artifact_inline` calls and results as stored, and still show them as cards, also in forks; the model is shown those calls as `artifact` with `inline: true` in its requests, so it does not repeat a tool it is no longer offered. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's.
|
|
71
|
+
- **Artifacts.** The `artifact` tool publishes versioned HTML pages, Markdown documents (shown in the app's theme), or SVG images. Give it `content`, `edits` against the latest version, or a `path` to a UTF-8 text file on the server (up to 2 MB). A path can be absolute, start with `~/`, or be relative to the session's folder. The file is copied into a durable version, not linked: changing or deleting the source does not change the artifact. For a new artifact, `.html`, `.md`/`.markdown`, and `.svg` infer its type; a path update keeps the existing id's type. A page can carry a bundle of files (since 0.26.0). `assets` adds up to 200 entries, each `{ name, path }` (a file on the server, binary allowed, copied and not linked) or `{ name, content }` (UTF-8 text): images, fonts, stylesheets, scripts, data files, or more HTML pages. A name is a relative path of letters, digits, dots, underscores, and hyphens, up to 200 characters, with no `.` or `..` segment. A new version keeps the assets of the one before it; an entry with the same name replaces one, and `removeAssets` drops some. One asset is up to 5 MB, and one version's assets up to 20 MB. A relative URL in the page (`assets/logo.png`, `about.html`) loads from the bundle in the viewer, in an inline card after Run, in the artifact's own tab, and in a published link. Each file is sent with the sandbox's policy, `nosniff`, and a type from its extension (an unknown one is never HTML). Assets are stored once for each content hash. A private page reaches its assets through a signed address that lasts 12 hours, so a page left open longer loads new assets only after a reload. `group` (a lowercase slug) puts artifacts together as variations of one design, and `kind` (`page` or `deck`) says what a design is; Design uses both. Artifacts from before 0.26.0 work as they did. `inline: true` (since 0.28.0, one tool; before it a second tool, `artifact_inline`, sent almost the same schema again on every request) is the same store for HTML only (`content` or `edits`, no path, no `type` but `html`): the call shows as a card in the reply, between Pi's words, instead of a link (see Rich replies). Pi's guide says when to use which: the card for a small interactive piece that belongs to what it is explaining, the viewer for a whole page, a game, a Markdown document, or an SVG image. An id made by either tool takes versions from both, but an `inline: true` call refuses an id that is Markdown or SVG, and the `artifact` tool cannot change the type of an id that has had an inline version (a card names a version, and the page comes by the artifact's type): Pi uses a new id for that. Pi's guide mentions `inline` only in sessions whose `artifact` tool has it (PiP's has not), and says that only a direct call shows a card. Sessions from before 0.28.0 keep their `artifact_inline` calls and results as stored, and still show them as cards, also in forks; the model is shown those calls as `artifact` with `inline: true` in its requests, so it does not repeat a tool it is no longer offered. The Artifacts sheet lists every version in a rounded card grid; opening one shows the sandboxed viewer (or its own tab). The list does not run artifacts as previews. Artifacts cannot reach the app or its cookies. In the viewer, an HTML artifact can ask for two things, which Pi knows how to build: a **follow-up**, a message it puts in your message box (after your draft, starting with which artifact it is from, with any selection as JSON) for you to read and send, never sent by itself, and only after you tap the page (a real tap or key press in the page, up to 5 seconds before: the page cannot fake one, and `window.focus()` does not count; each tap serves one follow-up), at most every 2 seconds (the viewer then closes, so the box shows); and **saved state**, up to 16 KB of JSON that it saves for you alone, so its filters and inputs come back after a reload, a restart, or on another device. Saved state stays out of Pi's context, belongs to the artifact rather than a version, and starts empty in a fork; a page that changes the state's shape names a new schema, and the old state then reads as none. Only people who can write to Pi get a follow-up; a viewer gets a notice. HTML run from a reply (▶ Run) can offer a follow-up too, but keeps no state. Only the artifact's first page is heard: as it starts, it opens a private channel to the app (a script the server puts first in an HTML artifact's page when a frame asks for it, and in the frame page that runs a reply's HTML), and everything goes over that channel, so a page the frame goes on to cannot use it and an answer still on its way never reaches it. `schema` is a string (a number is refused, for a get and a set alike). The bridge is for HTML artifacts, not Markdown or SVG. Neither works in a published link or an artifact's own tab. A session keeps up to 300 saved values; a person removed from the app keeps theirs until the session goes. **Share** in the viewer publishes one artifact to anyone with the link (`/pub/<token>`), with no sign-in: the page is the artifact's own sandboxed one, so it still cannot reach the app, and its address is the whole of the access. A bundle's files are at `/pub/<token>/<name>`, checked on every request: ending or expiring the link closes every file, a link that follows the newest version follows its assets, and a pinned link keeps its own. A published page gets no bridge. A share either stays at the version it was made from or follows the artifact's newest, and either lasts until it is ended or closes after a day, a week, or a month; **End** closes it at once, and the address then answers nothing. Only people who steer and see every session publish or end one, or see its address, never viewers or someone invited to a single session. The sheet lists the session's links still in force, with the address to copy; it starts at the server's public address when a tunnel gives one, else at this browser's. **Delete** (the bin in the viewer, and on each card of the Artifacts sheet, since 0.30.0) takes an artifact with all its versions, after a confirm: its pages, its share links, the state its page saved, and its design comments go in one commit, so a restart finds it all there or all gone, and the storage drops the older revisions that held them. Its asset files go too once no artifact in any session uses them (a sweep after the delete, run again at startup if a restart cut it off). Cards in replies say it was deleted, also after a reload (the session's view carries the last number of each deleted artifact). A share or saved state made while it is deleted is refused, and edits that Pi sent for a deleted version are refused too. What stays is Pi's own messages: the tool calls that made it still hold the text Pi sent, and the confirm says so. Anyone who steers the session may delete, never a viewer; Pi has no tool to delete. One version alone cannot be deleted, as cards in replies and design comments name versions by number. A fork keeps its own copy. Published again under the same id, it starts at the next number, never one a card names.
|
|
71
72
|
- **All artifacts.** The rail's artifact button opens every artifact in every session you can see, grouped by session (archived sessions are left out), newest first. Each row shows its type, size, age, and the number of its current (latest) version, as `v3 / 3` of the versions it has (`v1` when it has one). A tap opens that version in its session. The launcher's **All artifacts** opens it too, which is the way on a phone. The list is `GET /api/artifacts`.
|
|
72
73
|
- **Design.** On by default (Menu → **Extensions** turns it off). A canvas beside the chat for Pi's HTML designs: prototypes, screens, one-pagers, and slide decks. A design is an artifact, so versions, the sandbox, saved state, and share links work as they do for any artifact. Open it from the rail, the places, **Open in Design** in the artifact viewer, or `/design-open` (with an artifact's id to open that one). On a wide screen the panel sits beside the chat; on a phone it covers the chat, and the way back keeps the canvas as it was. Since 0.26.0.
|
|
73
74
|
- **The canvas.** A picker of the session's HTML artifacts (newest first, variations together); the page in the artifact sandbox, at phone (390×844), tablet (820×1180), desktop (1280×800), or a custom size; fit or zoom, and a light, dark, or theme backdrop. A new design that Pi makes opens by itself, unless you are in a mode, have a draft, or it is a variation of the open design.
|
package/docs/macos.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Each release has `Pi-Pocket-<version>.pkg` on its [GitHub release page](https://github.com/TannerMidd/pi-pocket/releases), with a `.sha256` file beside it. It installs Pi Pocket for your macOS account, with no admin password and no Node.js of your own. macOS 13.5 (Ventura) or newer, on Apple silicon or Intel: one package fits both.
|
|
4
4
|
|
|
5
|
-
The package
|
|
5
|
+
The package holds everything: Node.js, the `pi-pocket` package of its release with its dependencies, and the desktop app. The install needs no internet and no npm, so it works behind a company proxy or firewall that blocks npm, and as soon as the release is out, before npm has it.
|
|
6
6
|
|
|
7
7
|
## Gatekeeper
|
|
8
8
|
|
|
@@ -24,12 +24,12 @@ The installer has one place to install: **Install for me only**. Everything goes
|
|
|
24
24
|
| Folder or file | What it is |
|
|
25
25
|
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
26
|
| `node/` | Node.js, from the official `darwin-arm64` and `darwin-x64` tarballs. The build checks each against the SHA256 pinned in [`packaging/macos/build.sh`](../packaging/macos/build.sh), and joins their two `node` files into one universal file; each half is the official file, byte for byte, with its signature. |
|
|
27
|
-
| `app/` | A private npm prefix that holds the `pi-pocket` package. It is yours, so updates from the app work.
|
|
27
|
+
| `app/` | A private npm prefix that holds the `pi-pocket` package. It is yours, so updates from the app work. The package's build made it with npm, as `npm install --global` does. |
|
|
28
28
|
| `pi-pocket` | Starts the launcher with that Node.js and prefix. Arguments go to `pi-pocket` (`pi-pocket --help`). |
|
|
29
29
|
| `Pi Pocket.command` | What Terminal runs for Pi Pocket (console). |
|
|
30
30
|
| `uninstall.sh`, `login-item.sh`, `stop-pi-pocket.sh` | The uninstaller, the switch of the sign-in item, and what stops a running Pi Pocket for the installer and the uninstaller. |
|
|
31
|
-
| `
|
|
32
|
-
| `npm-cache/`, `install.log` | npm's cache, and what
|
|
31
|
+
| `place-app.mjs` | Puts the package's `pi-pocket` (in `app.new/` until then) in place of `app/` during the install, with no network, unless `app/` holds a newer one. |
|
|
32
|
+
| `npm-cache/`, `install.log` | npm's cache, for in-app updates, and what `place-app.mjs` did during the install. |
|
|
33
33
|
|
|
34
34
|
The package always uses its own Node.js, also when you have one (from Homebrew, nvm, or nodejs.org): an update of your Node.js, or its removal, does not break Pi Pocket, and in-app updates always have a prefix that they can write. Your own Node.js and npm are not changed.
|
|
35
35
|
|
|
@@ -52,7 +52,9 @@ Inside sessions, `node` and `npm` are the package's own, and a global npm instal
|
|
|
52
52
|
|
|
53
53
|
## Updates
|
|
54
54
|
|
|
55
|
-
Menu → **Update Pi Pocket** updates the package in `app/`, as for any global npm install, and restarts. The Node.js in `node/` stays the one that the package installed. A newer package brings a newer Node.js
|
|
55
|
+
Menu → **Update Pi Pocket** updates the package in `app/`, as for any global npm install, and restarts; it needs npm's registry. The Node.js in `node/` stays the one that the package installed. A newer package brings a newer Node.js and its own `pi-pocket`; install it over the old one. It stops a running Pi Pocket first (work in progress continues when Pi Pocket starts again), and it keeps a newer `pi-pocket` that the app already updated to.
|
|
56
|
+
|
|
57
|
+
Pi Pocket.app checks the package before it starts it: when `app/` holds an older `pi-pocket` than the app itself (an install that did not finish), it says so in an alert and starts nothing. Install the same package again to put its `pi-pocket` back.
|
|
56
58
|
|
|
57
59
|
## Uninstall
|
|
58
60
|
|
|
@@ -70,13 +72,13 @@ Run it in Terminal, not from a Pi Pocket session: it must stop Pi Pocket, so it
|
|
|
70
72
|
installer -pkg Pi-Pocket-0.29.0.pkg -target CurrentUserHomeDirectory
|
|
71
73
|
```
|
|
72
74
|
|
|
73
|
-
No `sudo`: the package refuses to install as root. For the sign-in item too, pass `-applyChoiceChangesXML` with a file that selects the choice `login`, as [`.github/workflows/macos.yml`](../.github/workflows/macos.yml) does. The install fails when the
|
|
75
|
+
No `sudo`: the package refuses to install as root. For the sign-in item too, pass `-applyChoiceChangesXML` with a file that selects the choice `login`, as [`.github/workflows/macos.yml`](../.github/workflows/macos.yml) does. The install fails when `place-app.mjs` cannot put the package in place; `install.log` says why.
|
|
74
76
|
|
|
75
77
|
## How it is built
|
|
76
78
|
|
|
77
|
-
[`.github/workflows/macos-installer.yml`](../.github/workflows/macos-installer.yml) builds it on GitHub's macOS runner for each published release with `pkgbuild` and `productbuild`, and attaches it to the release. Pi Pocket.app is compiled there with `swiftc` for arm64 and x86_64, joined with `lipo`, and signed ad hoc, unless the `macos-signing` environment also has a "Developer ID Application" certificate (`MACOS_APPLICATION_CERTIFICATE` and `MACOS_APPLICATION_PASSWORD`): then it is signed with it and the hardened runtime. Without that certificate the package is not notarized, as notarization refuses code that is signed ad hoc. It runs beside the npm publish and does not
|
|
79
|
+
[`.github/workflows/macos-installer.yml`](../.github/workflows/macos-installer.yml) builds it on GitHub's macOS runner for each published release with `pkgbuild` and `productbuild`, and attaches it to the release. [`packaging/bundle-app.mjs`](../packaging/bundle-app.mjs) makes the app folder there: with the package's Node.js and its npm, it packs the release tag (with `npm-shrinkwrap.json`, as the npm release has it), installs that package globally into a new prefix without install scripts, and checks the version, the start script, the shrinkwrap, and that no dependency is for one platform only, so the one folder fits both kinds of Mac. With the "Developer ID Application" certificate, the build signs the native modules in it (Mach-O files) with the hardened runtime, as notarization needs. Pi Pocket.app is compiled there with `swiftc` for arm64 and x86_64, joined with `lipo`, and signed ad hoc, unless the `macos-signing` environment also has a "Developer ID Application" certificate (`MACOS_APPLICATION_CERTIFICATE` and `MACOS_APPLICATION_PASSWORD`): then it is signed with it and the hardened runtime. Without that certificate the package is not notarized, as notarization refuses code that is signed ad hoc. It runs beside the npm publish and does not need it. Only a release build is signed, and only when the `macos-signing` environment has the "Developer ID Installer" certificate that the workflow names; with the notary secrets too, it is notarized and stapled. Limit that environment to `v*` tags and give it a reviewer.
|
|
78
80
|
|
|
79
|
-
[`.github/workflows/macos.yml`](../.github/workflows/macos.yml) runs on each pull request, on Apple silicon and on Intel: it builds the package with
|
|
81
|
+
[`.github/workflows/macos.yml`](../.github/workflows/macos.yml) runs on each pull request, on Apple silicon and on Intel: it builds the package with the package of the pull request, blocks npm's registry (its names in `/etc/hosts`, and an `NPM_CONFIG_REGISTRY` that refuses), installs it without `sudo`, starts the console launcher, checks that it answers HTTP and that the sign-in link works, and uninstalls it while it runs. Then it installs it again with the sign-in item and opens Pi Pocket.app: it checks that no Terminal opens, that the window signed in with a one-time link, that a second start opens the first, and that **Quit** stops everything. With an older version in the package's `package.json`, the app must show its alert and start nothing, and an install must put its own `pi-pocket` back; with a newer one, an install must keep it. It starts the sign-in item, installs over the running Pi Pocket (which keeps the sign-in item), and uninstalls it with the data. It also runs `npm run check` and the test suite, without the tests that do not pass on macOS yet. The workflow skips them by name, and `test/pip-board-ui.test.ts` as a whole:
|
|
80
82
|
|
|
81
83
|
- Tests that press Ctrl or Alt for a shortcut. On a Mac the app takes ⌘ and Option instead (`APPLE` in `web/ui.js`), so the shortcut does not come. The PiP board tests stop at their first Alt+A, and each later test in that file needs the page that it left.
|
|
82
84
|
- Time limits and animations: the performance limits of the design lint and the RSS parser, the stall limits of helpers, and the glide of new rows. The macOS runner is slower than these limits allow.
|