run attention: publish to ntfy and surface what needs the operator

Nothing told the operator that a run was waiting for a person or had failed; they
found out by going looking. A run that needs attention now reaches the ntfy they
already run, and the app answers "what needs me now" in one live, ordered surface.

Server (smallest change, reusing the existing publisher):
- internal/server/notify.go adds notifyRun, called from finishRunState (failed)
  and when a run parks on a human (runner.go runLoop). It publishes to the same
  already-configured `system` destination through the unchanged stage.PublishNtfy,
  so there is no second publisher, topic or service and the token handling is the
  stage's own. runAttentionEvent maps only waiting and failed; queued, running,
  succeeded, canceled and interrupted publish nothing.
- No storms: runner.attentionSent records sequence:event per run before publishing,
  so a run that stays waiting is never republished on a re-request or restart, and
  a stage notify policy that already covers the same event marks it first so the
  run-level default is suppressed. The set is dropped when the run is terminal. A
  delivery failure is logged, never fails the run, and is not retried.
- The payload names the run and pipeline and carries a click action
  pipelines://run/<id> (validated: absolute URL, no userinfo, no fragment, no
  credentials). PublishNtfy gained the optional click parameter; existing callers
  pass "".

App:
- AndroidManifest/MainActivity declare the pipelines://run/<id> deep link
  (singleTop); runIdFromDeepLink parses it and PipelinesApp opens that run once,
  clearing the link. It opens a run; it starts nothing.
- ui/Attention.kt is the pure model (status -> Decision/Failed/Finished or
  nothing, ordered by kind then newest-first) and ui/components/AttentionSurface.kt
  is the floating indicator plus bottom sheet. It is derived from the same run
  events the server already pushes, so an entry appears with no refresh and clears
  when resolved; a finished run clears once looked at, and any entry can be
  dismissed, persisted in SettingsRepository. The existing destinations, pill and
  bottom strip are untouched and no competing navigation surface is added.

Checked before committing:
- Packaged authoring skill references: internal/author/skill/references/
  notifications.md documents the automatic run-attention notifications and the
  app surface. The only packaged "template" carrying notify is that reference; no
  pipeline definition template exists to update and install.go's managed file list
  is unchanged (notifications.md already existed).
- Repository guidelines: docs/ntfy.md gains an "Automatic run-attention
  notifications" section and no longer claims "No block means no notifications";
  the top-level README phone-notifications note now says a waiting/failed run
  notifies automatically; android/README.md gains the dated feature section and
  supersedes the previous section's note that the attention surface was absent.
- docker.md, install docs and the CLI/TUI docs describe mechanisms this change
  does not alter; left as they are.

Tests: go test ./internal/server/... ./internal/stage/... ./internal/author/...
all ok; notify_test.go covers the event mapping and the real HTTP delivery
(destination, topic, click, no duplicate). Android :app:testDebugUnitTest ->
BUILD SUCCESSFUL, 58 suites / 531 tests / 0 failures (new AttentionTest, 13 cases,
covering ordering, appearing from a push, clearing on resolution, dismissal, the
empty case, persistence and the deep link). Device screenshots and the phone's own
notification are visual review's per the brief's device policy.

Scope: android/ plus the smallest server change; no new dependency, no run started
from the app, no installer or Docker change.
This commit is contained in:
2026-10-17 16:11:57 +01:00
parent f782c51c18
commit 890d267c71
17 changed files with 1215 additions and 25 deletions
+21 -2
View File
@@ -45,8 +45,9 @@ artifacts=markdown,files
do not choose topics or addresses. Configure `PIPELINES_NTFY_URL` (publishing
topic URL), `PIPELINES_NTFY_PUBLIC_URL` (phone-facing server base URL), and
`PIPELINES_NTFY_TOKEN` or `PIPELINES_NTFY_TOKEN_FILE` once on the server.
The topic is `pipelines` in the provided setup. No block means no notifications.
Legacy `destination` lines remain parseable for immutable-history compatibility
The topic is `pipelines` in the provided setup. No block means no per-stage
notifications; a run that needs a person is still announced automatically (see
below). Legacy `destination` lines remain parseable for immutable-history compatibility
but no longer select a connection for notification hooks. Explicit native
`type=ntfy` stages retain their separate destination configuration.
- `artifacts=markdown` sends the string in `output.markdown` as `digest.md`.
@@ -68,6 +69,24 @@ artifacts=markdown,files
notifications are not replayed during recovery. Tool access follows the stage's
declared tools; notification settings do not grant additional tools.
## Automatic run-attention notifications
Independently of any `notify` block, the server publishes one run-level
notification to the `system` destination when a run needs a person: when it enters
`waiting` (a human stage asked for a decision) and when it fails. Nothing else
notifies — queued, running, succeeded, canceled and interrupted runs are silent.
The payload names the run and its pipeline and carries a `click` action
`pipelines://run/<id>` that opens that run in the Android app.
A genuine event notifies once: a run that stays `waiting` is not republished on a
read or restart, and a stage `notify` policy that already covers the same event
(`on=waiting`, or a failure hook) suppresses the run-level default, so one event
means one notification. A failed delivery is logged, never fails the run, and is
not retried. The Android app shows the same information in one attention surface
ordered by importance — a run waiting for a decision, then a failed run, then a
run that finished since the operator last looked — derived from the run events the
server already pushes, so it needs no refresh and starts nothing.
## Explicit delivery stage (optional)
The preceding stage must output three nonempty UTF-8 strings: `title`, `summary`,