feat: support multi-pr review runs

Author: neversettle17-101

backend/internal/httpd/apispec/openapi.yaml

@@ -1243,13 +1243,13 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ReviewRunResponse'
+                $ref: '#/components/schemas/TriggerReviewResponse'
           description: OK
         "201":
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ReviewRunResponse'
+                $ref: '#/components/schemas/TriggerReviewResponse'
           description: Created
         "404":
           content:
@@ -1632,6 +1632,10 @@ components:
       type: object
     ListReviewsResponse:
       properties:
+        items:
+          items:
+            $ref: '#/components/schemas/ReviewPlanItem'
+          type: array
         reviewerHandleId:
           type: string
         reviews:
@@ -1641,6 +1645,7 @@ components:
       required:
       - reviewerHandleId
       - reviews
+      - items
       type: object
     ListSessionPRsResponse:
       properties:
@@ -1931,6 +1936,30 @@ components:
       - sessionId
       - session
       type: object
+    ReviewPlanItem:
+      properties:
+        latestRun:
+          $ref: '#/components/schemas/ReviewRun'
+        prNumber:
+          type: integer
+        prUrl:
+          type: string
+        status:
+          enum:
+          - needs_review
+          - running
+          - up_to_date
+          - changes_requested
+          - ineligible
+          type: string
+        targetSha:
+          type: string
+      required:
+      - prUrl
+      - prNumber
+      - targetSha
+      - status
+      type: object
     ReviewRun:
       properties:
         body:
@@ -2403,6 +2432,31 @@ components:
       - body
       - githubReviewId
       type: object
+    TriggerReviewResponse:
+      properties:
+        createdReviews:
+          items:
+            $ref: '#/components/schemas/ReviewRun'
+          type: array
+        items:
+          items:
+            $ref: '#/components/schemas/ReviewPlanItem'
+          type: array
+        review:
+          $ref: '#/components/schemas/ReviewRun'
+        reviewerHandleId:
+          type: string
+        reviews:
+          items:
+            $ref: '#/components/schemas/ReviewRun'
+          type: array
+      required:
+      - review
+      - reviewerHandleId
+      - reviews
+      - items
+      - createdReviews
+      type: object
     WorkspaceRepo:
       properties:
         name:

backend/internal/httpd/apispec/specgen/build.go

@@ -181,9 +181,10 @@ var schemaNames = map[string]string{
 	"ControllersResolveCommentsRequest":  "ResolveCommentsRequest",
 	"ControllersResolveCommentsResponse": "ResolveCommentsResponse",
 	// httpd/controllers — review wire envelopes
-	"ControllersListReviewsResponse": "ListReviewsResponse",
-	"ControllersReviewRunResponse":   "ReviewRunResponse",
-	"ControllersSubmitReviewInput":   "SubmitReviewInput",
+	"ControllersListReviewsResponse":   "ListReviewsResponse",
+	"ControllersReviewRunResponse":     "ReviewRunResponse",
+	"ControllersTriggerReviewResponse": "TriggerReviewResponse",
+	"ControllersSubmitReviewInput":     "SubmitReviewInput",
 	// domain review entities
 	"DomainReviewRun": "ReviewRun",
 	// service/project entities + DTOs
@@ -345,8 +346,8 @@ func reviewOperations() []operation {
 			summary:    "Trigger a code review of a worker's PR",
 			pathParams: []any{controllers.SessionIDParam{}},
 			resps: []respUnit{
-				{http.StatusOK, controllers.ReviewRunResponse{}},
-				{http.StatusCreated, controllers.ReviewRunResponse{}},
+				{http.StatusOK, controllers.TriggerReviewResponse{}},
+				{http.StatusCreated, controllers.TriggerReviewResponse{}},
 				{http.StatusUnprocessableEntity, envelope.APIError{}},
 				{http.StatusNotFound, envelope.APIError{}},
 				{http.StatusNotImplemented, envelope.APIError{}},

backend/internal/httpd/controllers/reviews.go

@@ -10,24 +10,37 @@ import (
 	"github.com/aoagents/agent-orchestrator/backend/internal/domain"
 	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/apispec"
 	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/envelope"
+	reviewcore "github.com/aoagents/agent-orchestrator/backend/internal/review"
 	reviewsvc "github.com/aoagents/agent-orchestrator/backend/internal/service/review"
 )
 
 // ListReviewsResponse is the body of GET /api/v1/sessions/{sessionId}/reviews.
 // reviewerHandleId is the live reviewer pane's runtime handle, for the UI to
 // attach its terminal over /mux (empty when no reviewer has run).
 type ListReviewsResponse struct {
-	ReviewerHandleID string             `json:"reviewerHandleId"`
-	Reviews          []domain.ReviewRun `json:"reviews"`
+	ReviewerHandleID string                `json:"reviewerHandleId"`
+	Reviews          []domain.ReviewRun    `json:"reviews"`
+	Items            []reviewcore.PlanItem `json:"items"`
 }
 
-// ReviewRunResponse is the body of trigger (200/201) and submit (200). It
-// carries the run plus the reviewer pane handle so the UI can attach a terminal.
+// ReviewRunResponse is the body of submit (200). It carries the run plus the
+// reviewer pane handle so the UI can attach a terminal.
 type ReviewRunResponse struct {
 	Review           domain.ReviewRun `json:"review"`
 	ReviewerHandleID string           `json:"reviewerHandleId"`
 }
 
+// TriggerReviewResponse is the body of trigger (200/201). review and
+// reviewerHandleId are legacy compatibility fields; items and createdReviews
+// carry the PR-scoped batch result.
+type TriggerReviewResponse struct {
+	Review           domain.ReviewRun      `json:"review"`
+	ReviewerHandleID string                `json:"reviewerHandleId"`
+	Reviews          []domain.ReviewRun    `json:"reviews"`
+	Items            []reviewcore.PlanItem `json:"items"`
+	CreatedReviews   []domain.ReviewRun    `json:"createdReviews"`
+}
+
 // SubmitReviewInput is the body of POST /api/v1/sessions/{sessionId}/reviews/submit.
 type SubmitReviewInput struct {
 	RunID          string `json:"runId" description:"Review run id being completed."`
@@ -62,7 +75,11 @@ func (c *ReviewsController) list(w http.ResponseWriter, r *http.Request) {
 	if runs == nil {
 		runs = []domain.ReviewRun{}
 	}
-	envelope.WriteJSON(w, http.StatusOK, ListReviewsResponse{ReviewerHandleID: res.ReviewerHandleID, Reviews: runs})
+	items := res.Items
+	if items == nil {
+		items = []reviewcore.PlanItem{}
+	}
+	envelope.WriteJSON(w, http.StatusOK, ListReviewsResponse{ReviewerHandleID: res.ReviewerHandleID, Reviews: runs, Items: items})
 }
 
 func (c *ReviewsController) trigger(w http.ResponseWriter, r *http.Request) {
@@ -81,7 +98,21 @@ func (c *ReviewsController) trigger(w http.ResponseWriter, r *http.Request) {
 	if res.Created {
 		status = http.StatusCreated
 	}
-	envelope.WriteJSON(w, status, ReviewRunResponse{Review: res.Run, ReviewerHandleID: res.ReviewerHandleID})
+	reviews := res.CreatedRuns
+	if reviews == nil {
+		reviews = []domain.ReviewRun{}
+	}
+	items := res.Items
+	if items == nil {
+		items = []reviewcore.PlanItem{}
+	}
+	envelope.WriteJSON(w, status, TriggerReviewResponse{
+		Review:           res.Run,
+		ReviewerHandleID: res.ReviewerHandleID,
+		Reviews:          reviews,
+		Items:            items,
+		CreatedReviews:   reviews,
+	})
 }
 
 func (c *ReviewsController) submit(w http.ResponseWriter, r *http.Request) {

backend/internal/httpd/controllers/reviews_test.go

@@ -20,12 +20,17 @@ import (
 
 type fakeReviewService struct {
 	triggerErr error
+	trigger    reviewcore.TriggerResult
+	list       reviewcore.SessionReviews
 }
 
 func (f *fakeReviewService) Trigger(context.Context, domain.SessionID) (reviewcore.TriggerResult, error) {
 	if f.triggerErr != nil {
 		return reviewcore.TriggerResult{}, f.triggerErr
 	}
+	if f.trigger.ReviewerHandleID != "" || f.trigger.Run.ID != "" || f.trigger.Items != nil || f.trigger.CreatedRuns != nil {
+		return f.trigger, nil
+	}
 	return reviewcore.TriggerResult{Run: domain.ReviewRun{ID: "run-1"}, Created: true}, nil
 }
 
@@ -34,7 +39,7 @@ func (f *fakeReviewService) Submit(context.Context, domain.SessionID, string, do
 }
 
 func (f *fakeReviewService) List(context.Context, domain.SessionID) (reviewcore.SessionReviews, error) {
-	return reviewcore.SessionReviews{}, nil
+	return f.list, nil
 }
 
 func newReviewTestServer(t *testing.T, svc reviewsvc.Manager) *httptest.Server {
@@ -59,3 +64,46 @@ func TestReviewsTrigger_MissingReviewerBinaryReturns422WithCause(t *testing.T) {
 		t.Fatalf("message = %q, want reviewer binary cause", got.Message)
 	}
 }
+
+func TestReviewsListIncludesItems(t *testing.T) {
+	srv := newReviewTestServer(t, &fakeReviewService{list: reviewcore.SessionReviews{
+		ReviewerHandleID: "review-mer-1",
+		Runs:             []domain.ReviewRun{{ID: "run-1", PRURL: "https://github.com/o/r/pull/1", TargetSHA: "sha1"}},
+		Items:            []reviewcore.PlanItem{{PRURL: "https://github.com/o/r/pull/1", PRNumber: 1, TargetSHA: "sha1", Status: reviewcore.ItemUpToDate}},
+	}})
+
+	body, status, headers := doRequest(t, srv, "GET", "/api/v1/sessions/mer-1/reviews", "")
+	assertJSON(t, headers)
+	if status != http.StatusOK {
+		t.Fatalf("status = %d body=%s", status, body)
+	}
+	if !strings.Contains(string(body), `"items"`) || !strings.Contains(string(body), `"up_to_date"`) || !strings.Contains(string(body), `"reviewerHandleId":"review-mer-1"`) {
+		t.Fatalf("body missing review items/handle: %s", body)
+	}
+}
+
+func TestReviewsTriggerIncludesBatchFields(t *testing.T) {
+	run1 := domain.ReviewRun{ID: "run-1", PRURL: "https://github.com/o/r/pull/1", TargetSHA: "sha1"}
+	run2 := domain.ReviewRun{ID: "run-2", PRURL: "https://github.com/o/r/pull/2", TargetSHA: "sha2"}
+	srv := newReviewTestServer(t, &fakeReviewService{trigger: reviewcore.TriggerResult{
+		Run:              run1,
+		ReviewerHandleID: "review-mer-1",
+		Created:          true,
+		CreatedRuns:      []domain.ReviewRun{run1, run2},
+		Items: []reviewcore.PlanItem{
+			{PRURL: run1.PRURL, PRNumber: 1, TargetSHA: run1.TargetSHA, Status: reviewcore.ItemRunning, LatestRun: &run1},
+			{PRURL: run2.PRURL, PRNumber: 2, TargetSHA: run2.TargetSHA, Status: reviewcore.ItemRunning, LatestRun: &run2},
+		},
+	}})
+
+	body, status, headers := doRequest(t, srv, "POST", "/api/v1/sessions/mer-1/reviews/trigger", "")
+	assertJSON(t, headers)
+	if status != http.StatusCreated {
+		t.Fatalf("status = %d body=%s", status, body)
+	}
+	for _, want := range []string{`"createdReviews"`, `"reviews"`, `"items"`, `"run-1"`, `"run-2"`, `"reviewerHandleId":"review-mer-1"`} {
+		if !strings.Contains(string(body), want) {
+			t.Fatalf("body missing %s: %s", want, body)
+		}
+	}
+}

backend/internal/lifecycle/manager_test.go

@@ -543,8 +543,8 @@ func TestApplyReviewResultSendsAndDedupsThroughPRSignature(t *testing.T) {
 		t.Fatalf("outcome/messages = %q/%v, want sent once", outcome, msg.msgs)
 	}
 	got := msg.msgs[0]
-	if !strings.Contains(got, "[AO reviewer]") || !strings.Contains(got, "fix the bug") || !strings.Contains(got, "98[2J765") {
-		t.Fatalf("AO review nudge missing label/body/review id: %q", got)
+	if !strings.Contains(got, "[AO reviewer]") || !strings.Contains(got, result.PRURL) || !strings.Contains(got, "fix the bug") || !strings.Contains(got, "98[2J765") {
+		t.Fatalf("AO review nudge missing label/pr url/body/review id: %q", got)
 	}
 	if strings.Contains(got, "\x1b") {
 		t.Fatalf("AO review nudge should sanitize control bytes: %q", got)

backend/internal/lifecycle/reactions.go

@@ -154,7 +154,7 @@ func (m *Manager) ApplyReviewResult(ctx context.Context, workerID domain.Session
 	if m.messenger == nil {
 		return ReviewDeliveryNoop, nil
 	}
-	msg := "[AO reviewer] AO's internal code reviewer requested changes on your PR. Review the feedback below and address it."
+	msg := "[AO reviewer] AO's internal code reviewer requested changes on your PR " + domain.SanitizeControlChars(r.PRURL) + ". Review the feedback below and address it."
 	if r.GithubReviewID != "" {
 		safeReviewID := domain.SanitizeControlChars(r.GithubReviewID)
 		msg += fmt.Sprintf(" This feedback is GitHub review %s. Once you have addressed it, reply on that review referencing id %s with how you addressed it, then resolve the review comment threads you addressed.", safeReviewID, safeReviewID)

backend/internal/review/planner.go

@@ -0,0 +1,93 @@
+package review
+
+import (
+	"sort"
+
+	"github.com/aoagents/agent-orchestrator/backend/internal/domain"
+)
+
+// ItemStatus is the per-PR review planning state.
+type ItemStatus string
+
+const (
+	// ItemNeedsReview means an eligible PR has no current AO approval or running pass.
+	ItemNeedsReview ItemStatus = "needs_review"
+	// ItemRunning means a review run is already active for the PR's current head.
+	ItemRunning ItemStatus = "running"
+	// ItemUpToDate means AO approved the PR's current head.
+	ItemUpToDate ItemStatus = "up_to_date"
+	// ItemChangesRequested means AO requested changes on the PR's current head.
+	ItemChangesRequested ItemStatus = "changes_requested"
+	// ItemIneligible means the PR is draft, closed, merged, or missing required facts.
+	ItemIneligible ItemStatus = "ineligible"
+)
+
+// PlanItem is one PR-scoped review decision for a worker session.
+type PlanItem struct {
+	PRURL     string            `json:"prUrl"`
+	PRNumber  int               `json:"prNumber"`
+	TargetSHA string            `json:"targetSha"`
+	Status    ItemStatus        `json:"status" enum:"needs_review,running,up_to_date,changes_requested,ineligible"`
+	LatestRun *domain.ReviewRun `json:"latestRun,omitempty"`
+}
+
+// Plan computes per-PR review work from the currently observed PRs and existing
+// review runs. It is pure so the trigger path and API list path share exactly
+// the same eligibility/status rules.
+func Plan(prs []domain.PullRequest, runs []domain.ReviewRun) []PlanItem {
+	latest := latestRunsByPRAndSHA(runs)
+	items := make([]PlanItem, 0, len(prs))
+	for _, pr := range prs {
+		item := PlanItem{
+			PRURL:     pr.URL,
+			PRNumber:  pr.Number,
+			TargetSHA: pr.HeadSHA,
+			Status:    ItemNeedsReview,
+		}
+		if pr.URL == "" || pr.HeadSHA == "" || pr.Draft || pr.Merged || pr.Closed {
+			item.Status = ItemIneligible
+			if run, ok := latest[item.PRURL+"\x00"+item.TargetSHA]; ok {
+				item.LatestRun = &run
+			}
+			items = append(items, item)
+			continue
+		}
+		if run, ok := latest[item.PRURL+"\x00"+item.TargetSHA]; ok {
+			item.LatestRun = &run
+			switch {
+			case run.Status == domain.ReviewRunRunning:
+				item.Status = ItemRunning
+			case run.Verdict == domain.VerdictApproved:
+				item.Status = ItemUpToDate
+			case run.Verdict == domain.VerdictChangesRequested:
+				item.Status = ItemChangesRequested
+			case run.Status == domain.ReviewRunFailed:
+				item.Status = ItemNeedsReview
+			default:
+				item.Status = ItemNeedsReview
+			}
+		}
+		items = append(items, item)
+	}
+	sort.SliceStable(items, func(i, j int) bool {
+		if items[i].PRNumber != items[j].PRNumber {
+			return items[i].PRNumber < items[j].PRNumber
+		}
+		return items[i].PRURL < items[j].PRURL
+	})
+	return items
+}
+
+func latestRunsByPRAndSHA(runs []domain.ReviewRun) map[string]domain.ReviewRun {
+	latest := make(map[string]domain.ReviewRun)
+	for _, run := range runs {
+		if run.PRURL == "" || run.TargetSHA == "" {
+			continue
+		}
+		key := run.PRURL + "\x00" + run.TargetSHA
+		if existing, ok := latest[key]; !ok || run.CreatedAt.After(existing.CreatedAt) {
+			latest[key] = run
+		}
+	}
+	return latest
+}