relay-flow 0.3.11-alpha → 0.3.13-alpha

package/README.md

@@ -28,13 +28,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.11-alpha
+opencode plugin relay-flow-plugin@0.3.13-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.11-alpha
+pi install npm:relay-flow-plugin@0.3.13-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -164,7 +164,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.11-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.13-alpha"]
 }
 ```
 
@@ -173,7 +173,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.11-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.13-alpha"]
 }
 ```
 
@@ -189,7 +189,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.11-alpha
+pi install npm:relay-flow-plugin@0.3.13-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves

package/cmd/relay-flow/commands_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"database/sql"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -277,6 +278,75 @@ func TestReportAckMatrix(t *testing.T) {
 	}
 }
 
+func TestReportValidationErrorIsStructuredOnStderr(t *testing.T) {
+	const message = "NEXT STEP is end, so FEEDBACK must be exactly None."
+	const valid = `{"runId":"run-1","node":"coding","reportId":"s:m","report":{"status":"success","nextStep":"end","summary":{"completed":"done","commits":"None","notCompleted":"None","issuesDiscovered":"None","verification":"None","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
+	home := t.TempDir()
+	serveAck(t, home, runsvc.ReportAck{}, &runsvc.InvalidReportError{Reason: message})
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	original := os.Stderr
+	os.Stderr = writer
+	code := cli(t, home, valid, "report")
+	os.Stderr = original
+	_ = writer.Close()
+	defer reader.Close()
+	output, err := io.ReadAll(reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var response struct {
+		Error struct {
+			Code    string `json:"code"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(output, &response); err != nil || code != exitFail || response.Error.Code != "invalidReport" || response.Error.Message != message {
+		t.Fatalf("CLI validation response: exit=%d stderr=%q parsed=%+v err=%v", code, output, response, err)
+	}
+}
+
+func TestReportOtherAPIErrorsPreserveCodeForRetryClassification(t *testing.T) {
+	const report = `{"runId":"run-1","node":"coding","reportId":"s:m","report":{"status":"success","nextStep":"end"}}`
+	for _, tc := range []struct {
+		name, code string
+		err        error
+	}{
+		{"invalid request", "invalid", fmt.Errorf("%w: malformed report", server.ErrInvalid)},
+		{"server failure", "internalError", errors.New("temporary backend failure")},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			serveAck(t, home, runsvc.ReportAck{}, tc.err)
+			reader, writer, err := os.Pipe()
+			if err != nil {
+				t.Fatal(err)
+			}
+			original := os.Stderr
+			os.Stderr = writer
+			code := cli(t, home, report, "report")
+			os.Stderr = original
+			_ = writer.Close()
+			defer reader.Close()
+			output, err := io.ReadAll(reader)
+			if err != nil {
+				t.Fatal(err)
+			}
+			var response struct {
+				Error struct {
+					Code    string `json:"code"`
+					Message string `json:"message"`
+				} `json:"error"`
+			}
+			if err := json.Unmarshal(output, &response); err != nil || code != exitFail || response.Error.Code != tc.code || response.Error.Message != tc.err.Error() {
+				t.Fatalf("CLI response: exit=%d stderr=%q parsed=%+v err=%v", code, output, response, err)
+			}
+		})
+	}
+}
+
 func TestReportUnreachableServerExits1(t *testing.T) {
 	valid := `{"runId":"payments/basicFlow/PAY-101","node":"coding","reportId":"s:m","report":{"status":"success","nextStep":"end","summary":{"completed":"x","commits":"abc123","notCompleted":"None","issuesDiscovered":"None","verification":"x","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
 	if code := cli(t, t.TempDir(), valid, "report"); code != 1 {

package/cmd/relay-flow/main.go

@@ -9,6 +9,7 @@ import (
 	"bufio"
 	"context"
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
 	"io"
@@ -1146,7 +1147,14 @@ func cmdReport(c *server.Client, stdin io.Reader) int {
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 	if _, err := c.SubmitReport(ctx, req); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		var apiErr *server.APIError
+		if errors.As(err, &apiErr) {
+			_ = json.NewEncoder(os.Stderr).Encode(map[string]any{
+				"error": map[string]string{"code": apiErr.Code, "message": apiErr.Message},
+			})
+		} else {
+			fmt.Fprintln(os.Stderr, err)
+		}
 		return exitFail
 	}
 	return exitOK

package/internal/execution/goworkflows/engine.go

@@ -394,7 +394,7 @@ func (e *Engine) SubmitReport(ctx context.Context, req run.ReportRequest) (run.R
 	}
 	if err := wf.ValidateReport(req.Node, req.Report); err != nil {
 		slog.Info("report validation failed", append(attrs, "reason", err.Error())...)
-		return run.ReportAck{Accepted: false}, err
+		return run.ReportAck{}, &run.InvalidReportError{Reason: err.Error()}
 	}
 	signal := reportSignal{
 		ReportID: req.ReportID, Node: req.Node,

package/internal/execution/goworkflows/engine_test.go

@@ -3,6 +3,7 @@ package goworkflows_test
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -294,6 +295,40 @@ func TestSerialGraphOneNodeAtATime(t *testing.T) {
 	})
 }
 
+func TestInvalidReportIsPermanentAndDoesNotSignal(t *testing.T) {
+	log := newEventLog()
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos:  repoRegistryWith("payments", newFakeTaskSystem(log)),
+		Runner: newFakeRunner(log), Harness: newFakeHarness(log),
+	})
+	rid, err := startRun(engine, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, err := engine.GetRun(context.Background(), rid)
+		return err == nil && r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	before, _ := engine.GetRun(context.Background(), rid)
+	invalid := successReport("end")
+	invalid.Feedback.RequiredActions = "needs work"
+	ack, err := engine.SubmitReport(context.Background(), reportRequest(rid, "coding", invalid))
+	if !errors.Is(err, run.ErrInvalidReport) || ack.Accepted {
+		t.Fatalf("invalid report: ack=%+v err=%v", ack, err)
+	}
+	if want := `NEXT STEP is end, so FEEDBACK must be exactly None.`; err.Error() != want {
+		t.Fatalf("validation message = %q, want %q", err, want)
+	}
+	after, err := engine.GetRun(context.Background(), rid)
+	if err != nil || after.CurrentNodeVisitID != before.CurrentNodeVisitID {
+		t.Fatalf("invalid report advanced visit: before=%+v after=%+v err=%v", before, after, err)
+	}
+	ack, err = engine.SubmitReport(context.Background(), reportRequest(rid, "coding", successReport("end")))
+	if err != nil || !ack.Accepted {
+		t.Fatalf("corrected report: ack=%+v err=%v", ack, err)
+	}
+}
+
 func TestRevisitCreatesNewVisit(t *testing.T) {
 	log := newEventLog()
 	sys := newFakeTaskSystem(log)

package/internal/execution/temporal/operations.go

@@ -210,7 +210,7 @@ func (e *Engine) SubmitReport(ctx context.Context, req run.ReportRequest) (run.R
 		return run.ReportAck{}, err
 	}
 	if err := wf.ValidateReport(req.Node, req.Report); err != nil {
-		return run.ReportAck{Accepted: false}, err
+		return run.ReportAck{}, &run.InvalidReportError{Reason: err.Error()}
 	}
 	if err := c.SignalWorkflow(ctx, string(req.RunID), "", reportSignalName, reportSignal{
 		ReportID: req.ReportID, Node: req.Node, NodeVisitID: state.CurrentNodeVisitID, Report: req.Report,

package/internal/execution/temporal/operations_test.go

@@ -3,6 +3,7 @@ package temporal
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"testing"
 	"time"
 
@@ -11,10 +12,84 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/task"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 	commonpb "go.temporal.io/api/common/v1"
+	enumspb "go.temporal.io/api/enums/v1"
+	historypb "go.temporal.io/api/history/v1"
 	workflowpb "go.temporal.io/api/workflow/v1"
+	"go.temporal.io/sdk/client"
+	"go.temporal.io/sdk/converter"
 	_ "modernc.org/sqlite"
 )
 
+type reportValidationClient struct {
+	client.Client
+	start    run.Start
+	signaled bool
+}
+
+func (c *reportValidationClient) QueryWorkflow(context.Context, string, string, string, ...interface{}) (converter.EncodedValue, error) {
+	return reportValidationValue{}, nil
+}
+
+type reportValidationValue struct{}
+
+func (reportValidationValue) HasValue() bool { return true }
+func (reportValidationValue) Get(dest interface{}) error {
+	*(dest.(*ReportStateSnapshot)) = ReportStateSnapshot{
+		State: run.StateWaiting, CurrentNode: "coding", CurrentNodeVisitID: "visit-1",
+	}
+	return nil
+}
+
+func (c *reportValidationClient) GetWorkflowHistory(context.Context, string, string, bool, enumspb.HistoryEventFilterType) client.HistoryEventIterator {
+	payload, _ := converter.GetDefaultDataConverter().ToPayloads(c.start)
+	return &reportValidationHistory{event: &historypb.HistoryEvent{
+		EventType: enumspb.EVENT_TYPE_WORKFLOW_EXECUTION_STARTED,
+		Attributes: &historypb.HistoryEvent_WorkflowExecutionStartedEventAttributes{
+			WorkflowExecutionStartedEventAttributes: &historypb.WorkflowExecutionStartedEventAttributes{Input: payload},
+		},
+	}}
+}
+
+func (c *reportValidationClient) SignalWorkflow(context.Context, string, string, string, interface{}) error {
+	c.signaled = true
+	return nil
+}
+
+type reportValidationHistory struct {
+	event *historypb.HistoryEvent
+	read  bool
+}
+
+func (h *reportValidationHistory) HasNext() bool { return !h.read }
+func (h *reportValidationHistory) Next() (*historypb.HistoryEvent, error) {
+	h.read = true
+	return h.event, nil
+}
+
+func TestTemporalSubmitReportRejectsInvalidReportBeforeSignal(t *testing.T) {
+	client := &reportValidationClient{start: run.Start{Workflow: workflow.Workflow{
+		Name: "test", Nodes: map[string]workflow.Node{
+			"coding": {Type: workflow.NodeAgent, OnSuccess: []workflow.Route{{Target: "end"}}},
+			"end":    {},
+		},
+	}}}
+	engine := &Engine{client: client}
+	report := workflow.Report{
+		Status: workflow.OutcomeSuccess, NextStep: "end",
+		Summary:  workflow.Summary{Completed: "done", Commits: "None", NotCompleted: "None", IssuesDiscovered: "None", Verification: "None", Notes: "None"},
+		Feedback: workflow.Feedback{ReasonForNextStep: "None", RequiredActions: "needs work", RelevantContext: "None", ExpectedResult: "None"},
+	}
+	ack, err := engine.SubmitReport(context.Background(), run.ReportRequest{
+		RunID: "run-1", Node: "coding", ReportID: "message-1", Report: report,
+	})
+	if !errors.Is(err, run.ErrInvalidReport) || ack.Accepted || client.signaled {
+		t.Fatalf("invalid Temporal report: ack=%+v err=%v signaled=%v", ack, err, client.signaled)
+	}
+	if want := `NEXT STEP is end, so FEEDBACK must be exactly None.`; err.Error() != want {
+		t.Fatalf("validation message = %q, want %q", err, want)
+	}
+}
+
 func TestApplyTemporalProjectionStateRebuildsCanceledTimingIdempotently(t *testing.T) {
 	started := time.Now().UTC().Add(-time.Minute)
 	finished := started.Add(30 * time.Second)

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.3.11-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.13-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")

package/internal/harness/opencode/repo_setup.go

@@ -10,7 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-const relayFlowPlugin = "relay-flow-plugin@0.3.11-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.3.13-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/run/run.go

@@ -120,6 +120,16 @@ type ReportAck struct {
 	Duplicate bool `json:"duplicate"`
 }
 
+// ErrInvalidReport identifies permanent semantic report-validation failures.
+var ErrInvalidReport = errors.New("invalid report")
+
+// InvalidReportError keeps the validation message intact while allowing
+// callers to classify it with errors.Is(err, ErrInvalidReport).
+type InvalidReportError struct{ Reason string }
+
+func (e *InvalidReportError) Error() string        { return e.Reason }
+func (e *InvalidReportError) Is(target error) bool { return target == ErrInvalidReport }
+
 // ErrRestartConflict means the ticket cannot accept an explicit restart in
 // its current durable state. Server handlers map it to HTTP 409.
 var ErrRestartConflict = errors.New("restart conflict")

package/internal/server/api_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -150,6 +151,36 @@ func TestReportEndpointAcceptsJSON(t *testing.T) {
 	}
 }
 
+func TestReportValidationErrorPreservesCodeAndMessageThroughClient(t *testing.T) {
+	const message = "NEXT STEP is end, so FEEDBACK must be exactly None."
+	fake := &fakeServices{reportErr: &run.InvalidReportError{Reason: message}}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	body := []byte(`{"runId":"run-1","node":"coding","reportId":"message-1","report":{"status":"success","nextStep":"end"}}`)
+	status, env := do(t, c, http.MethodPost, "http://relay/reports", body)
+	if status != http.StatusBadRequest || env.Error == nil || env.Error.Code != "invalidReport" || env.Error.Message != message {
+		t.Fatalf("invalid report response: status=%d env=%+v", status, env)
+	}
+
+	dir := t.TempDir()
+	_, cleanupSocket := startHandlerOnSocket(t, dir, fake)
+	defer cleanupSocket()
+	client := server.NewClient(filepath.Join(dir, "server.sock"))
+	_, err := client.SubmitReport(context.Background(), run.ReportRequest{
+		RunID: "run-1", Node: "coding", ReportID: "message-1",
+		Report: workflow.Report{Status: workflow.OutcomeSuccess, NextStep: "end"},
+	})
+	var apiErr *server.APIError
+	if !errors.As(err, &apiErr) || apiErr.Code != "invalidReport" || apiErr.Message != message || apiErr.StatusCode != http.StatusBadRequest {
+		t.Fatalf("Go client lost structured validation error: %v", err)
+	}
+	fake.reportErr = errors.New("temporary backend failure")
+	status, env = do(t, c, http.MethodPost, "http://relay/reports", body)
+	if status != http.StatusInternalServerError || env.Error == nil || env.Error.Code != "internalError" {
+		t.Fatalf("temporary failure misclassified: status=%d env=%+v", status, env)
+	}
+}
+
 func TestProcessedReportIDBypassesReportBodyValidation(t *testing.T) {
 	runID := "payments/basicFlow/PAY-101"
 	reportID := "session-1:message-1"

package/internal/server/client.go

@@ -38,6 +38,16 @@ func (c *Client) httpClient() *http.Client {
 	}
 }
 
+// APIError retains the server's machine-readable code and agent-readable
+// message separately so callers need not parse formatted error text.
+type APIError struct {
+	Code       string
+	Message    string
+	StatusCode int
+}
+
+func (e *APIError) Error() string { return fmt.Sprintf("server %s: %s", e.Code, e.Message) }
+
 // call performs one HTTP request against the socket server and decodes
 // the standard envelope. Non-2xx responses return an error carrying the
 // server-provided code and message.
@@ -77,7 +87,7 @@ func (c *Client) call(ctx context.Context, method, path string, body []byte, out
 	}
 	if !env.OK {
 		if env.Error != nil {
-			return fmt.Errorf("server %s: %s", env.Error.Code, env.Error.Message)
+			return &APIError{Code: env.Error.Code, Message: env.Error.Message, StatusCode: resp.StatusCode}
 		}
 		return fmt.Errorf("server returned not-ok (HTTP %d)", resp.StatusCode)
 	}

package/internal/server/fixture_test.go

@@ -36,6 +36,7 @@ type fakeServices struct {
 	runtimeAck         run.NodeRuntimeRegistrationAck
 	processedReports   map[string]bool
 	submittedReports   int
+	reportErr          error
 	restartRun         run.Run
 	restartErr         error
 	restarts           []string
@@ -125,6 +126,9 @@ func (f *fakeServices) SubmitReport(ctx context.Context, _ run.ReportRequest) (r
 		case <-ctx.Done():
 		}
 	}
+	if f.reportErr != nil {
+		return run.ReportAck{}, f.reportErr
+	}
 	return run.ReportAck{Accepted: true}, nil
 }
 

package/internal/server/server.go

@@ -130,6 +130,8 @@ func writeEnv(w http.ResponseWriter, status int, env envelope) {
 // anything else is an unexpected 500.
 func mapErr(w http.ResponseWriter, err error) {
 	switch {
+	case errors.Is(err, run.ErrInvalidReport):
+		writeErr(w, http.StatusBadRequest, "invalidReport", err.Error())
 	case errors.Is(err, run.ErrRestartConflict):
 		writeErr(w, http.StatusConflict, "conflict", err.Error())
 	case errors.Is(err, run.ErrNotFound):

package/internal/workflow/report.go

@@ -50,9 +50,6 @@ func (w *Workflow) ValidateReport(node string, report Report) error {
 	if report.Status != OutcomeSuccess && report.Status != OutcomeFailure {
 		return fmt.Errorf("report status %q must be %q or %q", report.Status, OutcomeSuccess, OutcomeFailure)
 	}
-	if report.Status == OutcomeFailure && report.NextStep == EndNode {
-		return fmt.Errorf("failure reports cannot select %q", EndNode)
-	}
 	for _, field := range []struct{ name, value string }{
 		{"summary.completed", report.Summary.Completed},
 		{"summary.commits", report.Summary.Commits},
@@ -74,6 +71,9 @@ func (w *Workflow) ValidateReport(node string, report Report) error {
 	if err != nil {
 		return err
 	}
+	if report.Status == OutcomeFailure && report.NextStep == EndNode {
+		return fmt.Errorf("STATUS is failure, so NEXT STEP cannot be end; valid targets: %s", strings.Join(sortedTargets(routes), ", "))
+	}
 	legal := false
 	for _, r := range routes {
 		if r.Target == report.NextStep {
@@ -88,7 +88,7 @@ func (w *Workflow) ValidateReport(node string, report Report) error {
 	if report.NextStep == EndNode {
 		f := report.Feedback
 		if f.ReasonForNextStep != None || f.RequiredActions != None || f.RelevantContext != None || f.ExpectedResult != None {
-			return fmt.Errorf("report selects %q: every feedback field must be %q because end has no mailbox", EndNode, None)
+			return fmt.Errorf("NEXT STEP is end, so FEEDBACK must be exactly None.")
 		}
 	}
 	return nil

package/internal/workflow/report_test.go

@@ -208,8 +208,8 @@ func TestValidateReportNextStepMustMatchStatusRoute(t *testing.T) {
 			Summary:  fullSummary(),
 			Feedback: fullFeedback(),
 		}
-		if err := wf.ValidateReport("coding", r); err == nil {
-			t.Fatal("failure report selecting a success-only target accepted")
+		if err := wf.ValidateReport("coding", r); err == nil || !strings.Contains(err.Error(), "valid targets: coding") {
+			t.Fatalf("failure report selecting a success-only target: %v, want configured failure route", err)
 		}
 	})
 
@@ -265,8 +265,8 @@ func TestValidateReportEndRequiresNoneFeedback(t *testing.T) {
 			Summary:  fullSummary(),
 			Feedback: fullFeedback(),
 		}
-		if err := wf.ValidateReport("coding", r); err == nil {
-			t.Fatal("end report carrying feedback accepted; end has no mailbox")
+		if err := wf.ValidateReport("coding", r); err == nil || err.Error() != "NEXT STEP is end, so FEEDBACK must be exactly None." {
+			t.Fatalf("end report error = %v, want actionable four-field correction", err)
 		}
 	})
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.3.11-alpha",
+  "version": "0.3.13-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",