c42a19f7d3
Make OpenCode authoring responsive and expand the managed skill references. Add conflict-aware import/export, real-provider reference workflows, and tracked V2 generation for reliable budget accounting.
91 lines
3.9 KiB
Markdown
91 lines
3.9 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.
|