890d267c71
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.
114 lines
5.3 KiB
Markdown
114 lines
5.3 KiB
Markdown
# Notification authoring
|
|
|
|
Use the server's existing system phone connection. Never read, copy or request
|
|
tokens/passwords, edit server settings, or call curl to publish while authoring.
|
|
Validation is not delivery. Do not send a test notification or run the workflow
|
|
without explicit approval.
|
|
|
|
## Default: hooks, not extra stages
|
|
|
|
A fenced `notify` block belongs inside an existing stage. `on` accepts `success`,
|
|
`failure`, or `success,failure` — not `error`. A failure means an execution error,
|
|
the `error` outcome, or a route to `#failure`; other completed outcomes are success.
|
|
Hooks send stage events, not a separate run-finished event. They leave the graph,
|
|
handoffs, tools, model and run verdict unchanged. Delivery failures are audited
|
|
separately and do not turn a successful stage into failure.
|
|
|
|
For the common sequential workflow whose failure/blocked edges terminate:
|
|
|
|
- Add **failure-only** hooks to intermediate stages.
|
|
- Add **success and failure** hooks to the final stage(s).
|
|
- Do not add intermediate success hooks: that would send extra progress alerts.
|
|
|
|
For `research → report`, with blocked/error edges to `#failure`, add this to
|
|
`research` (leave its success edge to `report` unchanged):
|
|
|
|
```notify
|
|
on=failure
|
|
```
|
|
|
|
And this to `report`:
|
|
|
|
```notify
|
|
on=success,failure
|
|
```
|
|
|
|
This produces one event on normal terminal paths: research failure, report failure,
|
|
or report success. No new output fields, prompts, native stages or model calls are
|
|
needed. Preserve the definition's existing model IDs and version guards.
|
|
|
|
**Limits:** hooks run after stage completion and before final run status is saved.
|
|
They are not a guaranteed finalizer for cancellation, process crashes, persistence
|
|
failures or runtime step/visit limits. If an intermediate error is routed to recovery
|
|
instead of `#failure`, its failure hook fires before that recovery completes. Loops
|
|
can send repeated events. Inspect routing; explain these limits rather than promise
|
|
exactly one final notification for every possible termination. Do not reroute
|
|
failures through a successful publisher and accidentally turn failure into success.
|
|
|
|
## Attachments only when requested
|
|
|
|
Omit `artifacts` for an event-only alert. `artifacts=markdown` attaches a nonempty
|
|
string in `output.markdown`; a field named `report` is not automatically attached.
|
|
Only add/rename output fields and corresponding prompts if a report attachment is
|
|
requested, preserving downstream handoffs. If no attachment is produced (including
|
|
on execution error), an event-only notification is still attempted.
|
|
|
|
`artifacts=files` attaches the workspace-relative paths in `output.artifacts`;
|
|
`artifacts=markdown,files` selects both. Each file gets its own notification, so
|
|
attachments may mean more than one message. Files must be regular, nonsymlinked,
|
|
at most 1 MiB, with at most 10 listed. Absolute/traversal/hidden paths, `secrets/`,
|
|
database/key paths and `node_modules/` are rejected. This is not content scanning.
|
|
Do not promise phone reception from structural validation.
|
|
|
|
## Optional explicit delivery stage
|
|
|
|
Use native delivery only when the user needs delivery as an explicit routed stage
|
|
(e.g. delivery failure must fail the run), not for an ordinary completion alert.
|
|
The preceding stage must output nonempty UTF-8 strings `title`, `summary`, and
|
|
`markdown`. Title/summary are single-line, at most 256/2048 bytes; Markdown is at
|
|
most 1 MiB. The native stage does not accept model prompts or tools and does not
|
|
need an output block:
|
|
|
|
````markdown
|
|
# stage publish
|
|
|
|
```configs
|
|
type=ntfy
|
|
destination=system
|
|
```
|
|
|
|
```edges
|
|
success -> #success
|
|
error -> #failure
|
|
```
|
|
````
|
|
|
|
`destination=system` uses the server's existing system connection. Native delivery
|
|
adds retained delivery metadata on success and follows its error edge on failure.
|
|
Neither hooks nor native delivery automatically retry ambiguous publishes; a new
|
|
run or repeated visit can send again. An upstream execution error does not reliably
|
|
produce the required three strings, so adding this stage alone cannot cover it.
|
|
|
|
## Automatic run-attention notifications
|
|
|
|
Independently of any `notify` block, the server publishes one run-level attention
|
|
notification to the same already-configured `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 — a queued, running, succeeded, canceled or interrupted
|
|
run sends nothing. You do not author these; they are the operator default, so a run
|
|
you never wired still reaches the operator.
|
|
|
|
The payload names the run and its pipeline and carries a `click` action
|
|
`pipelines://run/<id>` that opens that run in the Android app (the app declares the
|
|
scheme). 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 genuine event means one notification.
|
|
A delivery failure is logged, never fails the run, and is not retried.
|
|
|
|
The 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. It is derived from the run events the server already pushes
|
|
(no extra request), an entry clears when the run is resolved or the operator opens
|
|
it, and it can be deliberately dismissed. It is not a new place to start a run.
|
|
|