server: skip a stage that declares a skipped edge when no UI surface changed

A stage declaring a `skipped` outcome is short-circuited with no model call
when the run's recorded file changes and artifacts touch no UI surface
(android/, internal/tui/, a presentation extension or an image artifact).
The step is recorded completed/skipped along its declared edge with a
bounded one-line reason, so a backend-only run no longer pays for a
ui_reviewer generation that can only answer ui_applicable=false.
This commit is contained in:
2026-10-16 23:31:16 +01:00
parent 0937327e8c
commit b3188a5c6f
3 changed files with 460 additions and 16 deletions
+71 -16
View File
@@ -439,6 +439,13 @@ type runState struct {
visits map[string]int
memory map[string]memoryValue
input stage.Values
// changedPaths retains a bounded sample of the run's recorded changed paths
// and changedCount the full total, so the skip guard reads only in-memory
// evidence. uiSurface is latched once any recorded change touched a UI
// surface. Both are folded in by recordChanges (ui_surface.go).
changedPaths []string
changedCount int
uiSurface bool
}
func newRunState(key string, input stage.Values) *runState {
@@ -460,6 +467,9 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS
state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence}
}
}
// Seed the UI-surface accumulator from the persisted evidence so a
// resumed run reaches the same skip decision with no extra query.
state.recordChanges(step.FileChanges, step.Artifacts)
}
return state
}
@@ -472,6 +482,32 @@ func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, in
}
}
// finishStage persists one step, refreshes the shared memory for a completed
// step, notifies and classifies the step's target. Both the executed path and
// the skipped path use it, so persistence, notification and terminal routing
// cannot drift between them. A persist or memory-copy failure is returned for
// the caller to fail the run; the caller still owns the model-specific
// verdict, quiescence and cancellation handling around it.
func (r *runner) finishStage(id int64, name, workspace string, selected protocol.Stage, state *runState, step protocol.RunStep) (status, outcome, diagnostic string, terminal bool, err error) {
save, cancel := context.WithTimeout(context.Background(), 10*time.Second)
persistErr := r.store.FinishStep(save, id, step)
cancel()
if persistErr != nil {
return "", "", "", false, persistErr
}
if step.Status == "completed" {
values, copyErr := copyValues(stage.Values(step.Output))
if copyErr != nil {
return "", "", "", false, copyErr
}
state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence}
}
r.notifyStep(id, name, workspace, selected.Notify, step)
state.input = stage.Values(step.Output)
status, outcome, diagnostic, terminal = terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic)
return status, outcome, diagnostic, terminal, nil
}
func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, name, workspace string, request protocol.Message, state *runState) {
finish := func(status, outcome, diagnostic string) {
r.finishRunState(id, status, outcome, diagnostic, state.input)
@@ -557,6 +593,34 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
r.notifyStep(id, name, workspace, selected.Notify, waitStep)
return
}
// A stage that declares a `skipped` route is short-circuited when the run
// has recorded no UI surface: the stage would answer exactly that, so skip
// the model call and its capture work, record the step as completed and
// route along the declared edge. Only a declared route is honoured, and no
// other stage or outcome routing changes.
if _, declaresSkip := def.Edges["skipped"]; declaresSkip && !state.uiSurface {
reason := skipReasonLine(state)
step := protocol.RunStep{
Sequence: sequence,
Stage: key,
Status: "completed",
Outcome: "skipped",
Output: stage.Values{"summary": reason},
Target: def.Edges["skipped"],
Control: &protocol.ControlEvidence{Visit: state.visits[key], MaxVisits: maxVisits, Memory: reads},
}
status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step)
if finishErr != nil {
finish("failed", "error", finishErr.Error())
return
}
if terminal {
finish(status, outcome, diagnostic)
return
}
state.key = step.Target
continue
}
var tools []string
explicitTools := false
var toolErr error
@@ -715,23 +779,14 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
}
reasonCancel()
}
save, cancel := context.WithTimeout(context.Background(), 10*time.Second)
persistErr := r.store.FinishStep(save, id, step)
cancel()
if persistErr != nil {
finish("failed", "error", persistErr.Error())
status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step)
if finishErr != nil {
finish("failed", "error", finishErr.Error())
return
}
if step.Status == "completed" {
values, err := copyValues(stage.Values(step.Output))
if err != nil {
finish("failed", "error", err.Error())
return
}
state.memory[key] = memoryValue{output: values, sequence: sequence}
}
r.notifyStep(id, name, workspace, selected.Notify, step)
state.input = stage.Values(step.Output)
// Advance the in-memory UI-surface evidence only after the step is
// persisted, so the skip guard agrees with what the store holds.
state.recordChanges(step.FileChanges, step.Artifacts)
if useAgent || errors.Is(err, stage.ErrStageCleanup) {
sessions, checkErr := r.store.ActiveAgentSessionsForRun(context.Background(), id)
if checkErr != nil || len(sessions) > 0 {
@@ -743,7 +798,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
finish("canceled", "", ctx.Err().Error())
return
}
if status, outcome, diagnostic, terminal := terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic); terminal {
if terminal {
finish(status, outcome, diagnostic)
return
}
+280
View File
@@ -0,0 +1,280 @@
package server
import (
"context"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/stage"
)
// uiReviewerSource builds a two-stage implement -> ui_reviewer pipeline. When
// withSkip is set, ui_reviewer declares an `approved` and a `skipped` route to
// success; otherwise it only declares the template's `success` route, proving a
// skip is never invented for a stage without that route.
func uiReviewerSource(withSkip bool) string {
source := pipeline.Template([]string{"implement", "ui_reviewer"}, true)
if withSkip {
source = strings.Replace(source, "success -> #success", "approved -> #success\nskipped -> #success", 1)
}
return source
}
// runUISkip submits source, runs it once with an execute stub that records every
// visited stage key and writes the file named for that stage into the workspace,
// then returns the persisted detail, the visited keys and the number of verdict
// (model) calls the runner made.
func runUISkip(t *testing.T, source string, files map[string]string) (*protocol.RunDetail, []string, int) {
t.Helper()
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
store, err := pipeline.Open(filepath.Join(t.TempDir(), "ui.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
if _, err := store.Submit(ctx, "ui", source); err != nil {
t.Fatal(err)
}
items, err := store.List(ctx)
if err != nil || len(items) != 1 {
t.Fatalf("submit/list: %+v %v", items, err)
}
r, err := newRunner(ctx, store)
if err != nil {
t.Fatal(err)
}
defer r.wg.Wait()
dir := t.TempDir()
var mu sync.Mutex
var visited []string
verdictCalls := 0
r.verdict = func(context.Context, map[string]any) string {
mu.Lock()
verdictCalls++
mu.Unlock()
return "stub verdict"
}
r.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) {
mu.Lock()
visited = append(visited, def.Key)
mu.Unlock()
if name := files[def.Key]; name != "" {
full := filepath.Join(dir, filepath.FromSlash(name))
if err := os.MkdirAll(filepath.Dir(full), 0o700); err != nil {
return stage.Result{}, err
}
if err := os.WriteFile(full, []byte(def.Key+"\n"), 0o600); err != nil {
return stage.Result{}, err
}
}
outcome := "success"
if def.Key == "ui_reviewer" {
if _, ok := def.Edges["approved"]; ok {
outcome = "approved"
}
}
return stage.Result{Outcome: outcome, Output: stage.Values{"summary": def.Key + " done"}}, nil
}
run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "ui-skip", Workspace: dir, Input: map[string]any{"prompt": "task"}})
if err != nil {
t.Fatal(err)
}
r.wg.Wait()
detail, err := store.GetRun(ctx, run.ID)
if err != nil {
t.Fatal(err)
}
mu.Lock()
got := append([]string(nil), visited...)
calls := verdictCalls
mu.Unlock()
return detail, got, calls
}
func executed(visited []string, key string) bool {
for _, visitedKey := range visited {
if visitedKey == key {
return true
}
}
return false
}
// TestUISkipShortCircuitsWhenNoSurfaceChanged proves a non-UI change skips the
// ui_reviewer stage with no model call and routes along its declared skip edge.
func TestUISkipShortCircuitsWhenNoSurfaceChanged(t *testing.T) {
detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": "internal/server/fake.go"})
if executed(visited, "ui_reviewer") {
t.Fatalf("ui_reviewer executed a model call; visited=%v", visited)
}
if verdictCalls != 1 {
t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls)
}
if detail.Status != "succeeded" {
t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary)
}
if len(detail.Steps) != 2 {
t.Fatalf("steps = %d, want 2: %+v", len(detail.Steps), detail.Steps)
}
step := detail.Steps[1]
if step.Stage != "ui_reviewer" || step.Status != "completed" || step.Outcome != "skipped" || step.Target != protocol.SuccessEnd {
t.Fatalf("skip step wrong: %+v", step)
}
if step.FileChanges != nil && len(step.FileChanges.Files) != 0 {
t.Fatalf("skip step recorded file changes: %+v", step.FileChanges)
}
reason, _ := step.Output["summary"].(string)
if !strings.Contains(reason, "internal/server/fake.go") {
t.Fatalf("skip reason does not name the checked path: %q", reason)
}
}
// TestUISkipZeroChangesStillSkips proves the guard also short-circuits when the
// run recorded no file changes at all, with a reason that says so.
func TestUISkipZeroChangesStillSkips(t *testing.T) {
detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), nil)
if executed(visited, "ui_reviewer") {
t.Fatalf("ui_reviewer executed with no recorded changes; visited=%v", visited)
}
if verdictCalls != 1 {
t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls)
}
if detail.Status != "succeeded" || len(detail.Steps) != 2 {
t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps))
}
step := detail.Steps[1]
if step.Outcome != "skipped" {
t.Fatalf("step outcome = %q, want skipped: %+v", step.Outcome, step)
}
reason, _ := step.Output["summary"].(string)
if !strings.Contains(reason, "no recorded file changes") {
t.Fatalf("zero-change reason does not state that: %q", reason)
}
}
// TestUISkipRunsStageOnSurfaceChange proves a run that touched a UI surface
// still executes the stage and routes through its normal outcome.
func TestUISkipRunsStageOnSurfaceChange(t *testing.T) {
cases := map[string]string{
"android": "android/app/src/main/kotlin/Main.kt",
"internal tui": "internal/tui/view.go",
"presentation": "web/app.tsx",
}
for name, path := range cases {
t.Run(name, func(t *testing.T) {
detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": path})
if !executed(visited, "ui_reviewer") {
t.Fatalf("ui_reviewer did not execute on %s; visited=%v", path, visited)
}
if verdictCalls != 2 {
t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls)
}
if detail.Status != "succeeded" {
t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary)
}
step := detail.Steps[len(detail.Steps)-1]
if step.Stage != "ui_reviewer" || step.Outcome != "approved" || step.Target != protocol.SuccessEnd {
t.Fatalf("executed step did not route through approved: %+v", step)
}
})
}
}
// TestUISkipNeedsDeclaredEdge proves the guard never invents a skip for a stage
// whose definition declares no `skipped` route: it always executes.
func TestUISkipNeedsDeclaredEdge(t *testing.T) {
detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(false), map[string]string{"implement": "internal/server/fake.go"})
if !executed(visited, "ui_reviewer") {
t.Fatalf("ui_reviewer without a skipped edge did not execute; visited=%v", visited)
}
if verdictCalls != 2 {
t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls)
}
if detail.Status != "succeeded" || len(detail.Steps) != 2 {
t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps))
}
step := detail.Steps[1]
if step.Stage != "ui_reviewer" || step.Outcome != "success" {
t.Fatalf("edge-less stage step wrong: %+v", step)
}
}
func TestUISurfacePathClassification(t *testing.T) {
cases := []struct {
path string
want bool
}{
{"android/app/src/main/kotlin/Main.kt", true},
{"android/README.md", true},
{"internal/tui/view.go", true},
{"internal/tui", true},
{"web/index.html", true},
{"web/app.css", true},
{"web/app.js", true},
{"web/app.ts", true},
{"web/app.jsx", true},
{"web/app.tsx", true},
{"web/Index.HTML", true},
{"internal/server/fake.go", false},
{"androidx/foo.go", false},
{"cmd/pipelines/main.go", false},
{"docs/readme.md", false},
{"README.md", false},
}
for _, tc := range cases {
if got := uiSurfacePath(tc.path); got != tc.want {
t.Errorf("uiSurfacePath(%q) = %v, want %v", tc.path, got, tc.want)
}
}
}
func TestUISurfaceArtifactClassification(t *testing.T) {
cases := []struct {
name string
a protocol.StageArtifact
want bool
}{
{"image content type", protocol.StageArtifact{Name: "shot.bin", ContentType: "image/png"}, true},
{"image extension only", protocol.StageArtifact{Name: "shot.webp"}, true},
{"non-image artifact", protocol.StageArtifact{Name: "report.pdf", ContentType: "application/pdf"}, false},
{"binary artifact", protocol.StageArtifact{Name: "data.bin", ContentType: "application/octet-stream"}, false},
{"no type no image extension", protocol.StageArtifact{Name: "notes.txt"}, false},
}
for _, tc := range cases {
if got := uiSurfaceArtifact(tc.a); got != tc.want {
t.Errorf("%s: uiSurfaceArtifact(%+v) = %v, want %v", tc.name, tc.a, got, tc.want)
}
}
}
// TestUISurfaceRecordChanges proves the accumulator latches a UI surface from an
// image artifact but not from a non-image one, and retains only a bounded sample.
func TestUISurfaceRecordChanges(t *testing.T) {
image := &runState{}
image.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "shot.png", ContentType: "image/png"}})
if !image.uiSurface {
t.Fatal("an image artifact did not mark a UI surface")
}
plain := &runState{}
plain.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "report.pdf", ContentType: "application/pdf"}})
if plain.uiSurface {
t.Fatal("a non-image artifact marked a UI surface")
}
bounded := &runState{}
files := make([]protocol.FileChange, maxRetainedChangedPaths+5)
for i := range files {
files[i] = protocol.FileChange{Path: "f"}
}
bounded.recordChanges(&protocol.StageFileChanges{Files: files}, nil)
if len(bounded.changedPaths) != maxRetainedChangedPaths || bounded.changedCount != len(files) {
t.Fatalf("bounded accumulator = %d paths / count %d, want %d / %d", len(bounded.changedPaths), bounded.changedCount, maxRetainedChangedPaths, len(files))
}
}
+109
View File
@@ -0,0 +1,109 @@
package server
import (
"fmt"
"path"
"path/filepath"
"strings"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// UI-surface classification is the single source of truth for the deterministic
// pre-check that lets a stage declaring a `skipped` route short-circuit when the
// run changed no rendered surface. The path/extension lists live only here; the
// skip guard, its reason and the resumed-run seed all read them.
// maxRetainedChangedPaths bounds how many recorded changed paths a runState
// retains for the skip reason. The full count is kept separately, so the reason
// stays informative without unbounded memory.
const maxRetainedChangedPaths = 32
// uiSurfaceDirs are the workspace prefixes whose changes are a user-facing
// surface. Matching is on a path boundary, so "androidx/" is not "android/".
var uiSurfaceDirs = []string{"android", "internal/tui"}
// presentationExtensions are the rendered presentation file types a change can
// touch without living under a surface directory.
var presentationExtensions = map[string]bool{
".html": true,
".css": true,
".js": true,
".ts": true,
".jsx": true,
".tsx": true,
}
// 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,
}
// uiSurfacePath reports whether a run-relative, forward-slash workspace path
// changed a user-facing surface: a file under android/ or internal/tui/, or a
// file with a presentation extension. It is O(len(path)) with no I/O.
func uiSurfacePath(p string) bool {
clean := strings.TrimPrefix(path.Clean(filepath.ToSlash(p)), "/")
if clean == "" || clean == "." {
return false
}
for _, dir := range uiSurfaceDirs {
if clean == dir || strings.HasPrefix(clean, dir+"/") {
return true
}
}
return presentationExtensions[strings.ToLower(path.Ext(clean))]
}
// 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 completed step's observed changes into the run's
// UI-surface decision. It retains a bounded sample of paths; the count is
// unbounded so the reason can state the true total. It is O(changes) with no I/O.
func (s *runState) recordChanges(changes *protocol.StageFileChanges, artifacts []protocol.StageArtifact) {
if changes != nil {
for _, file := range changes.Files {
s.changedCount++
if len(s.changedPaths) < maxRetainedChangedPaths {
s.changedPaths = append(s.changedPaths, file.Path)
}
if !s.uiSurface && uiSurfacePath(file.Path) {
s.uiSurface = true
}
}
}
for _, artifact := range artifacts {
if !s.uiSurface && uiSurfaceArtifact(artifact) {
s.uiSurface = true
}
}
}
// skipReasonLine states, as one bounded line, why the guard skipped a stage: no
// recorded change touched a UI surface. It names the retained checked paths.
func skipReasonLine(state *runState) string {
if state.changedCount == 0 {
return "no UI surface changed (no recorded file changes)"
}
line := fmt.Sprintf("no UI surface changed in %d recorded file change(s): %s", state.changedCount, strings.Join(state.changedPaths, ", "))
if extra := state.changedCount - len(state.changedPaths); extra > 0 {
line = fmt.Sprintf("%s (+%d more)", line, extra)
}
runes := []rune(line)
if len(runes) > protocol.VerdictReasonCap {
return string(runes[:protocol.VerdictReasonCap])
}
return line
}