Files
pipelines/internal/server/ui_surface.go
T
alan f16d61cdfa Skip fallback needs complete, empty evidence; capture lists over-budget changes
The server skip fallback for stages with a skipped edge now applies only
when every earlier visit recorded a complete file-change capture with no
changed files and no image artifact. Any change (no repo-specific UI path
or extension list), any partial/unavailable/missing capture, a human
decision or a checkpoint-retry prefix runs the model. auto_skip=false opts
a stage out. The fallback verdict names the server fallback.

Capture compares over-budget text by hash and, in Git, lists paths it
could not compare when their git status changes, marked no_patch, so a
large workspace no longer records files: [] for a real edit. Run detail
gains a warnings list for partial/unavailable captures, also printed by
inspect on stderr.
2026-11-04 12:56:40 +00:00

126 lines
4.9 KiB
Go

package server
import (
"fmt"
"path"
"strings"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// The server skip fallback lets a stage that declares a `skipped` route
// short-circuit, without a model call, only when the run's evidence proves there
// is nothing to review: every visit so far recorded a complete file-change
// capture, none of them recorded any change, and no visit captured a rendered
// (image) artifact. Anything else runs the stage's model, which may still choose
// `skipped` itself.
//
// The rule deliberately classifies no path as "not UI". A path/extension list
// encodes one repository's layout (Go TUIs, Flutter .dart, Kotlin, SwiftUI,
// templates, strings files and config can all be rendered surface), and absent
// or partial evidence must never be read as "no edits". A wrong run costs one
// model call; a wrong skip ships an unreviewed UI change.
// maxRetainedChangedPaths bounds how many recorded changed paths a runState
// retains as a sample. The full count is kept separately.
const maxRetainedChangedPaths = 32
// serverSkipReasonPrefix starts every server fallback skip reason, so the
// verdict says plainly that no model ran, and so a resumed run recognises its
// own earlier fallback steps (which have no capture of their own).
const serverSkipReasonPrefix = "Server fallback skip (no model run):"
// autoSkipConfig is the stage config that opts a stage out of the fallback.
const autoSkipConfig = "auto_skip"
// renderedArtifactExtensions are the image types a captured artifact may carry
// when its content type was not recorded or sniffed as an image.
var renderedArtifactExtensions = map[string]bool{
".png": true,
".jpg": true,
".jpeg": true,
".gif": true,
".webp": true,
}
// uiSurfaceArtifact reports whether a captured artifact is a rendered surface:
// an image content type, or an image file extension when no type was recorded.
func uiSurfaceArtifact(a protocol.StageArtifact) bool {
if strings.HasPrefix(strings.ToLower(a.ContentType), "image/") {
return true
}
return renderedArtifactExtensions[strings.ToLower(path.Ext(a.Name))]
}
// recordChanges folds one executed visit's observed changes into the run's
// skip evidence. A nil, partial or unavailable capture marks the run's
// evidence incomplete for the rest of the run. It retains a bounded sample of
// paths; the count is unbounded. It is O(changes) with no I/O.
func (s *runState) recordChanges(changes *protocol.StageFileChanges, artifacts []protocol.StageArtifact) {
if changes == nil || changes.Status != "complete" {
s.captureIncomplete++
}
if changes != nil {
for _, file := range changes.Files {
s.changedCount++
if len(s.changedPaths) < maxRetainedChangedPaths {
s.changedPaths = append(s.changedPaths, file.Path)
}
// The full captured set is a separate, unbounded dedupe of the actual
// evidence, unlike the bounded changedPaths sample above.
if file.Path == "" || s.capturedSeen[file.Path] {
continue
}
if s.capturedSeen == nil {
s.capturedSeen = map[string]bool{}
}
s.capturedSeen[file.Path] = true
s.capturedPaths = append(s.capturedPaths, file.Path)
}
}
for _, artifact := range artifacts {
if !s.uiSurface && uiSurfaceArtifact(artifact) {
s.uiSurface = true
}
}
}
// recordPersistedStep seeds the skip evidence from a stored step when a run is
// resumed or retried. A server fallback skip executed nothing and carries no
// capture, so it neither adds evidence nor makes it incomplete; every other
// stored visit (including a human decision, during which the workspace was not
// observed) is folded in like a live visit.
func (s *runState) recordPersistedStep(step protocol.RunStep) {
if serverSkipStep(step) {
return
}
s.recordChanges(step.FileChanges, step.Artifacts)
}
// serverSkipStep reports whether a stored step is a server fallback skip.
func serverSkipStep(step protocol.RunStep) bool {
return step.Outcome == "skipped" && step.FileChanges == nil && step.Verdict != nil &&
step.Verdict.ReasonSource == protocol.VerdictReasonFallback &&
strings.HasPrefix(step.Verdict.Reason, serverSkipReasonPrefix)
}
// autoSkipEligible reports whether the server may skip a stage declaring a
// `skipped` route: the stage has not opted out, every visit so far recorded a
// complete capture, no change was recorded and no rendered artifact captured.
func autoSkipEligible(configs map[string]string, state *runState) bool {
if configs[autoSkipConfig] == "false" {
return false
}
return state.captureIncomplete == 0 && state.changedCount == 0 && !state.uiSurface
}
// skipReasonLine states, as one bounded line, why the server skipped a stage.
func skipReasonLine() string {
line := fmt.Sprintf("%s every earlier visit's file-change capture was complete and recorded no file changes or screenshots.", serverSkipReasonPrefix)
runes := []rune(line)
if len(runes) > protocol.VerdictReasonCap {
return string(runes[:protocol.VerdictReasonCap])
}
return line
}