3e100f78f3
Rewrite the README around the server, web/Android app and CLI, and replace docs/install.md with the current native install (all-or-nothing Docker web build, flags from setup-native.py, lifecycle commands, data locations, password, upgrading). Add docs/harnesses.md and docs/notifications.md; point ntfy.md at the new overview and fix its topic name.
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# Notifications
|
|
|
|
The server records every notification once and delivers it two ways:
|
|
|
|
1. **In the Pipelines app** (Android, and the web page while it is open), over
|
|
the app's own connection. No ntfy app is needed.
|
|
2. **ntfy** (optional fallback), for devices that still use the ntfy app.
|
|
|
|
The same settings decide what is sent on both paths.
|
|
|
|
## What notifies
|
|
|
|
| Event | When |
|
|
| --- | --- |
|
|
| Run needs your decision | a run reaches a human decision stage (runs not set to Silent) |
|
|
| Run failed / succeeded | runs started with **Notify me** (`--notify on`), or every run when **Notify when any run ends** is on |
|
|
| Stage hook | a stage's own `notify` block fires ([ntfy reference](ntfy.md)) |
|
|
| Chat needs you | a chat asks a question or requests approval |
|
|
| Chat replied | an assistant turn ends (off by default) |
|
|
|
|
Each event notifies once. Opening or dismissing it on one device clears it on
|
|
the others.
|
|
|
|
Chat events are seen while some client has the chat open or the server still
|
|
holds queued messages for it. A turn that finishes with no client attached and
|
|
nothing queued does not produce a "replied" notification.
|
|
|
|
## Settings
|
|
|
|
In the app, **Settings**:
|
|
|
|
**Notifications** asks for the platform's notification permission.
|
|
|
|
**Notifications in Pipelines** (Android only):
|
|
|
|
- **Receive notifications in Pipelines**: starts a background service that
|
|
keeps its own connection to the server and posts notifications. Android shows
|
|
a quiet "Pipelines is connected" notification while it runs. It restarts
|
|
after a reboot or an app update.
|
|
- **Status**: the service's connection state.
|
|
- **Allow notifications**: shown when Android is blocking Pipelines
|
|
notifications.
|
|
- **Allow background delivery**: asks Android to exempt Pipelines from battery
|
|
optimisation so delivery stays instant while the phone is idle. Grant it.
|
|
|
|
**Phone notifications** (stored on the server, shared by every device):
|
|
|
|
| Setting | Default |
|
|
| --- | --- |
|
|
| Notify when any run ends (otherwise only runs started with **Notify me**) | off |
|
|
| Chat needs your answer or approval | on |
|
|
| Chat reply finished | off |
|
|
| Also send to ntfy (for devices that still use the ntfy app) | on |
|
|
|
|
Turning **Also send to ntfy** off stops publishing to ntfy; the app still
|
|
receives everything.
|
|
|
|
Per run, choose **Notify me**, the default (auto), or **Silent** when starting
|
|
it. From the CLI: `pipelines run … --notify on|auto|off`.
|
|
|
|
## The web app
|
|
|
|
The web page shows notifications only while it is open and the browser allows
|
|
them. Closed-browser web push is not implemented.
|
|
|
|
## ntfy (optional)
|
|
|
|
`./install` builds and runs ntfy on port 8090 with a private `pipelines` topic.
|
|
The installer prints the subscription details at the end, and
|
|
`pipelines doctor` repeats them (`Phone server … · topic: pipelines ·
|
|
username: phone-reader`).
|
|
|
|
To subscribe from the ntfy app:
|
|
|
|
1. Add a server: the ntfy address (default `http://<LAN IP>:8090`, or the
|
|
`--ntfy-url` you installed with). Off your home network, use a VPN such as
|
|
Tailscale.
|
|
2. Sign in as `phone-reader`. A freshly created account uses the web sign-in
|
|
password; an account kept from an earlier install keeps its old password.
|
|
3. Subscribe to the topic `pipelines`.
|
|
|
|
A tap opens `pipelines://run/<id>` or `pipelines://chat/<id>` in the Android
|
|
app; the **Open in browser** action opens the same page on
|
|
`PIPELINES_WEB_PUBLIC_URL`.
|
|
|
|
Notifications already shown by the ntfy app cannot be retracted by the server;
|
|
swipe them away there.
|
|
|
|
See [ntfy reference](ntfy.md) for stage `notify` hooks, explicit ntfy stages,
|
|
the app notification protocol and network troubleshooting.
|