120 lines
5.8 KiB
Markdown
120 lines
5.8 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. When the operator configures
|
|
`PIPELINES_WEB_PUBLIC_URL` on the server, run notifications and stage hooks carry
|
|
the authenticated web link `<origin>/runs/<id>`. Native installs default this to
|
|
their advertised web address; custom/VPN domains require the operator's actual
|
|
phone-reachable URL. Never use the API listener or ntfy URL, nor put credentials
|
|
in the click link. Existing Android-only installations without that setting keep
|
|
`pipelines://run/<id>`. Invalid origins omit the link and log a warning. Existing
|
|
delivered alerts are not rewritten. Do not change service settings or send a test
|
|
notification merely to author a workflow. 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.
|