Files
pipelines/internal/server/notify.go
T
alan 890d267c71 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.
2026-10-17 16:11:57 +01:00

296 lines
10 KiB
Go

package server
import (
"context"
"fmt"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/stage"
"io"
"log"
"os"
"path/filepath"
"strings"
"syscall"
"time"
"unicode/utf8"
)
func (r *runner) notifyStep(id int64, name, workspace string, policy *protocol.NotificationPolicy, step protocol.RunStep) {
if policy == nil {
return
}
event := "success"
if step.Status == protocol.StepStatusWaiting || step.Outcome == protocol.StepStatusWaiting {
event = protocol.NotifyWaiting
} else if step.Status != "completed" || step.Outcome == "error" || step.Target == protocol.FailureEnd {
event = "failure"
}
enabled := false
for _, on := range policy.On {
if on == event {
enabled = true
}
}
if !enabled {
return
}
// The stage's own policy already covers this attention event, so the
// run-level default must not repeat it. Recorded before delivery so a failed
// stage notification is reported by its own receipt, not silently duplicated.
r.markAttentionSent(id, step.Sequence, stageAttentionEvent(event))
ctx, cancel := context.WithTimeout(r.ctx, 30*time.Second)
defer cancel()
summary := fmt.Sprintf("%s · run #%d · stage %s · %s (%s)", name, id, step.Stage, event, step.Outcome)
summary = truncateUTF8(summary, 1800)
title := fmt.Sprintf("Pipeline stage %s", event)
receipts := []protocol.NotificationReceipt{}
persist := func() bool {
save, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := r.store.SaveNotifications(save, id, step.Sequence, receipts); err != nil {
log.Printf("notification audit run=%d step=%d: %v", id, step.Sequence, err)
return false
}
return true
}
send := func(filename string, data []byte) {
receipts = append(receipts, protocol.NotificationReceipt{Destination: "system", Status: "sending", Filename: filename})
if !persist() {
return
}
receipt := &receipts[len(receipts)-1]
result, err := stage.PublishNtfy(ctx, "system", title, summary, filename, data, "")
if err != nil {
receipt.Status = "failed"
receipt.Diagnostic = err.Error()
} else {
receipt.Status = "sent"
receipt.MessageID, _ = result["message_id"].(string)
receipt.AttachmentURL, _ = result["attachment_url"].(string)
}
persist()
}
reject := func(filename, diagnostic string) {
receipts = append(receipts, protocol.NotificationReceipt{Destination: "system", Status: "failed", Filename: filename, Diagnostic: diagnostic})
persist()
}
sentArtifact := false
for _, kind := range policy.Artifacts {
switch kind {
case "markdown":
if markdown, ok := step.Output["markdown"].(string); ok && strings.TrimSpace(markdown) != "" {
sentArtifact = true
send("digest.md", []byte(markdown))
}
case "files":
raw, exists := step.Output["artifacts"]
if !exists {
continue
}
var names []string
switch files := raw.(type) {
case []string:
names = files
case []any:
for _, value := range files {
name, ok := value.(string)
if !ok {
reject("", "output.artifacts must be an array of relative file paths")
names = nil
break
}
names = append(names, name)
}
default:
reject("", "output.artifacts must be an array of relative file paths")
}
if len(names) > 10 {
reject("", "at most 10 file artifacts can be notified")
continue
}
seen := map[string]bool{}
for _, name := range names {
if seen[name] {
continue
}
seen[name] = true
data, err := notificationArtifact(workspace, name)
if err != nil {
reject(name, err.Error())
continue
}
sentArtifact = true
send(filepath.Base(name), data)
}
}
}
// No produced artifacts still merits an event, especially on failures.
if !sentArtifact {
send("", nil)
}
}
// runAttentionEvent maps a run status to the operator attention notification it
// deserves. Only a run parked on a person (`waiting`) or a run that failed needs
// the operator; every other status — queued, running, succeeded, canceled,
// interrupted — returns "" so the mapping is the single place that decides
// whether a run produces a notification.
func runAttentionEvent(status string) string {
switch strings.TrimSpace(strings.ToLower(status)) {
case protocol.RunStatusWaiting:
return protocol.NotifyWaiting
case "failed":
return "failed"
}
return ""
}
// stageAttentionEvent maps a stage's notification event to the run-attention
// event it covers, or "" when the stage event is not a run-attention event (a
// success digest, for example). It is the one place the two vocabularies meet.
func stageAttentionEvent(event string) string {
switch event {
case protocol.NotifyWaiting:
return protocol.NotifyWaiting
case "failure":
return "failed"
}
return ""
}
// markAttentionSent records that [event] has already been delivered for step
// [sequence] of run [id] (by a stage policy or by the run-level default), so the
// same genuine event is never notified twice. The step sequence is part of the
// key because one run can wait on a person more than once; each wait is its own
// event.
func (r *runner) markAttentionSent(id int64, sequence int, event string) {
if event == "" {
return
}
r.attentionMu.Lock()
defer r.attentionMu.Unlock()
if r.attentionSent[id] == nil {
r.attentionSent[id] = map[string]bool{}
}
r.attentionSent[id][fmt.Sprintf("%d:%s", sequence, event)] = true
}
// attentionAlready reports whether [event] was already delivered for step
// [sequence] of run [id].
func (r *runner) attentionAlready(id int64, sequence int, event string) bool {
r.attentionMu.Lock()
defer r.attentionMu.Unlock()
return r.attentionSent[id][fmt.Sprintf("%d:%s", sequence, event)]
}
// forgetAttention drops a run's delivered-event set once it is terminal, so the
// registry is bounded by the runs still in flight.
func (r *runner) forgetAttention(id int64) {
r.attentionMu.Lock()
defer r.attentionMu.Unlock()
delete(r.attentionSent, id)
}
// runAttentionClick is the deep link a run notification carries so tapping it
// opens the run in the Android app, whose intent filter registers this scheme
// and host.
func runAttentionClick(id int64) string {
return fmt.Sprintf("pipelines://run/%d", id)
}
// notifyRun publishes one run-level attention notification to the operator's
// already-configured "system" destination. It is the run counterpart of
// notifyStep and reuses the same PublishNtfy machinery, destination and token
// handling, so no second publisher, topic or service is introduced. The run id
// and pipeline name identify the run and the click action opens it in the app.
// A run that needs nobody produces nothing, and a delivery failure is logged and
// never fails the run: this is a best-effort alert, not persisted run evidence.
func (r *runner) notifyRun(id int64, name, status string, sequence int, currentStage, diagnostic string) {
event := runAttentionEvent(status)
if event == "" {
return
}
if r.attentionAlready(id, sequence, event) {
return
}
// Record the delivery attempt before publishing so a repeated transition for
// the same run and event (a re-request, a restart-free re-entry) never
// republishes; delivery itself is never retried.
r.markAttentionSent(id, sequence, event)
title := "Run needs your decision"
summary := fmt.Sprintf("Run #%d · %s · waiting for a human decision", id, name)
if event == "failed" {
title = "Run failed"
summary = fmt.Sprintf("Run #%d · %s · run failed", id, name)
}
if currentStage != "" {
summary += " at stage " + currentStage
}
if diagnostic != "" {
summary += ": " + diagnostic
}
summary = truncateUTF8(summary, 2000)
ctx, cancel := context.WithTimeout(r.ctx, 30*time.Second)
defer cancel()
if _, err := stage.PublishNtfy(ctx, "system", title, summary, "", nil, runAttentionClick(id)); err != nil {
log.Printf("run attention notification run=%d: %v", id, err)
}
}
// truncateUTF8 bounds a notification string without splitting a multi-byte rune.
func truncateUTF8(text string, max int) string {
if len(text) <= max {
return text
}
text = text[:max]
for !utf8.ValidString(text) {
text = text[:len(text)-1]
}
return text
}
func notificationArtifact(workspace, name string) ([]byte, error) {
if name == "" || filepath.IsAbs(name) || filepath.Clean(name) != name || strings.ContainsAny(name, "\\\x00\r\n") {
return nil, fmt.Errorf("artifact must be a clean workspace-relative file path")
}
for _, part := range strings.Split(filepath.ToSlash(name), "/") {
lower := strings.ToLower(part)
if strings.HasPrefix(part, ".") || lower == "secrets" || lower == "node_modules" || strings.HasSuffix(lower, ".pem") || strings.HasSuffix(lower, ".key") || strings.HasSuffix(lower, ".db") || strings.HasSuffix(lower, ".db-wal") || strings.HasSuffix(lower, ".db-shm") || strings.HasSuffix(lower, ".sqlite") || strings.HasSuffix(lower, ".sqlite3") {
return nil, fmt.Errorf("artifact path is protected")
}
}
root, err := filepath.EvalSymlinks(workspace)
if err != nil {
return nil, fmt.Errorf("artifact workspace unavailable")
}
// os.Root prevents symlink traversal outside the workspace; disallow symlinks
// altogether so aliases cannot bypass protected path names within it either.
current := root
for _, part := range strings.Split(name, string(os.PathSeparator)) {
current = filepath.Join(current, part)
info, err := os.Lstat(current)
if err != nil || info.Mode()&os.ModeSymlink != 0 {
return nil, fmt.Errorf("artifact is missing or uses a symlink")
}
}
scoped, err := os.OpenRoot(root)
if err != nil {
return nil, fmt.Errorf("artifact workspace unavailable")
}
defer scoped.Close()
file, err := scoped.OpenFile(name, os.O_RDONLY|syscall.O_NONBLOCK|syscall.O_NOFOLLOW, 0)
if err != nil {
return nil, fmt.Errorf("cannot read artifact")
}
defer file.Close()
info, err := file.Stat()
if err != nil || !info.Mode().IsRegular() || info.Size() > 1<<20 {
return nil, fmt.Errorf("artifact must be a regular file at most 1 MiB")
}
data, err := io.ReadAll(io.LimitReader(file, (1<<20)+1))
if err != nil || len(data) > 1<<20 {
return nil, fmt.Errorf("cannot read artifact within size limit")
}
return data, nil
}