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,15 +1632,20 @@ components:
       type: object
     ListReviewsResponse:
       properties:
+        reviewRuns:
+          items:
+            $ref: '#/components/schemas/ReviewRun'
+          type: array
         reviewerHandleId:
           type: string
         reviews:
           items:
-            $ref: '#/components/schemas/ReviewRun'
+            $ref: '#/components/schemas/PRReviewItem'
           type: array
       required:
       - reviewerHandleId
       - reviews
+      - reviewRuns
       type: object
     ListSessionPRsResponse:
       properties:
@@ -1772,6 +1777,30 @@ components:
       - id
       - projectId
       type: object
+    PRReviewItem:
+      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
     Project:
       properties:
         agent:
@@ -2403,6 +2432,23 @@ components:
       - body
       - githubReviewId
       type: object
+    TriggerReviewResponse:
+      properties:
+        createdRuns:
+          items:
+            $ref: '#/components/schemas/ReviewRun'
+          type: array
+        reviewerHandleId:
+          type: string
+        reviews:
+          items:
+            $ref: '#/components/schemas/PRReviewItem'
+          type: array
+      required:
+      - reviewerHandleId
+      - reviews
+      - createdRuns
+      type: object
     WorkspaceRepo:
       properties:
         name:

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

@@ -181,11 +181,13 @@ 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",
+	"DomainReviewRun":    "ReviewRun",
+	"ReviewPRReviewItem": "PRReviewItem",
 	// service/project entities + DTOs
 	"ProjectProject":        "Project",
 	"ProjectSummary":        "ProjectSummary",
@@ -345,8 +347,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,35 @@ 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          []reviewcore.PRReviewItem `json:"reviews"`
+	ReviewRuns       []domain.ReviewRun        `json:"reviewRuns"`
 }
 
-// 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). reviews carries the
+// PR-scoped review state; createdRuns carries the new review_run rows started
+// by this trigger.
+type TriggerReviewResponse struct {
+	ReviewerHandleID string                    `json:"reviewerHandleId"`
+	Reviews          []reviewcore.PRReviewItem `json:"reviews"`
+	CreatedRuns      []domain.ReviewRun        `json:"createdRuns"`
+}
+
 // 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 +73,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.PRReviewItem{}
+	}
+	envelope.WriteJSON(w, http.StatusOK, ListReviewsResponse{ReviewerHandleID: res.ReviewerHandleID, Reviews: items, ReviewRuns: runs})
 }
 
 func (c *ReviewsController) trigger(w http.ResponseWriter, r *http.Request) {
@@ -81,7 +96,19 @@ 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})
+	createdRuns := res.CreatedRuns
+	if createdRuns == nil {
+		createdRuns = []domain.ReviewRun{}
+	}
+	reviews := res.Items
+	if reviews == nil {
+		reviews = []reviewcore.PRReviewItem{}
+	}
+	envelope.WriteJSON(w, status, TriggerReviewResponse{
+		ReviewerHandleID: res.ReviewerHandleID,
+		Reviews:          reviews,
+		CreatedRuns:      createdRuns,
+	})
 }
 
 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,54 @@ 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.PRReviewItem{{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), `"reviews"`) || !strings.Contains(string(body), `"reviewRuns"`) || !strings.Contains(string(body), `"up_to_date"`) || !strings.Contains(string(body), `"reviewerHandleId":"review-mer-1"`) {
+		t.Fatalf("body missing review items/handle: %s", body)
+	}
+	if strings.Contains(string(body), `"items"`) || strings.Contains(string(body), `"reviewItems"`) {
+		t.Fatalf("body contains deprecated review item aliases: %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.PRReviewItem{
+			{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{`"reviews"`, `"createdRuns"`, `"running"`, `"run-1"`, `"run-2"`, `"reviewerHandleId":"review-mer-1"`} {
+		if !strings.Contains(string(body), want) {
+			t.Fatalf("body missing %s: %s", want, body)
+		}
+	}
+	for _, unwanted := range []string{`"reviewItems"`, `"items"`, `"createdReviews"`, `"review":`} {
+		if strings.Contains(string(body), unwanted) {
+			t.Fatalf("body contains deprecated field %s: %s", unwanted, body)
+		}
+	}
+}

backend/internal/lifecycle/manager_test.go

@@ -543,8 +543,10 @@ 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)
+	for _, want := range []string{"[AO reviewer]", "PR: " + result.PRURL, "Verdict: changes_requested", "Review body:\nfix the bug", "GitHub review: 98[2J765"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("AO review nudge missing %q: %q", want, got)
+		}
 	}
 	if strings.Contains(got, "\x1b") {
 		t.Fatalf("AO review nudge should sanitize control bytes: %q", got)

backend/internal/lifecycle/reactions.go

@@ -154,13 +154,14 @@ 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 := fmt.Sprintf("[AO reviewer] AO's internal code reviewer submitted a review.\n\nPR: %s\nVerdict: %s", domain.SanitizeControlChars(r.PRURL), domain.SanitizeControlChars(string(r.Verdict)))
 	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)
+		msg += fmt.Sprintf("\nGitHub review: %s", safeReviewID)
+		msg += fmt.Sprintf("\n\nOnce you have addressed it, reply on GitHub review %s with how you addressed it, then resolve the review comment threads you addressed.", safeReviewID)
 	}
 	if r.Body != "" {
-		msg += "\n\n" + domain.SanitizeControlChars(r.Body)
+		msg += "\n\nReview body:\n" + domain.SanitizeControlChars(r.Body)
 	}
 	key := "review:" + r.PRURL + ":ao:" + r.RunID
 	sig := strings.Join([]string{r.TargetSHA, r.RunID, r.GithubReviewID, r.Body}, "\x00")

backend/internal/ports/reviewer.go

@@ -37,6 +37,12 @@ type ReviewInvocation struct {
 	PRURL string
 	// TargetSHA is the PR head commit under review.
 	TargetSHA string
+	// ReviewQueue lists all review tasks created by the same trigger. Reviewers
+	// still complete one RunID at a time, but this gives a shared reviewer pane
+	// enough context to process a multi-PR queue in order.
+	ReviewQueue []ReviewTask
+	// ReviewIndex is this invocation's zero-based position in ReviewQueue.
+	ReviewIndex int
 	// WorkspacePath is the worker's checkout the reviewer reads.
 	WorkspacePath string
 	// Prompt and SystemPrompt are the review instructions AO authored centrally,
@@ -48,6 +54,13 @@ type ReviewInvocation struct {
 	SystemPrompt string
 }
 
+// ReviewTask is one PR/run in a multi-PR review trigger queue.
+type ReviewTask struct {
+	RunID     string
+	PRURL     string
+	TargetSHA string
+}
+
 // ReviewCommandSpec is how to launch a reviewer: the argv and any extra env the
 // adapter needs. AO supplies the workspace and review-tracking env around it.
 type ReviewCommandSpec struct {

backend/internal/review/launcher.go

@@ -31,6 +31,8 @@ type LaunchSpec struct {
 	WorkspacePath string
 	PRURL         string
 	TargetSHA     string
+	ReviewQueue   []ports.ReviewTask
+	ReviewIndex   int
 }
 
 // reviewerRuntime is the runtime surface the launcher needs: create a pane,
@@ -73,6 +75,8 @@ func (l *agentLauncher) invocation(spec LaunchSpec) ports.ReviewInvocation {
 		WorkerSessionID: spec.WorkerID,
 		PRURL:           spec.PRURL,
 		TargetSHA:       spec.TargetSHA,
+		ReviewQueue:     spec.ReviewQueue,
+		ReviewIndex:     spec.ReviewIndex,
 		WorkspacePath:   spec.WorkspacePath,
 		Prompt:          prompt,
 		SystemPrompt:    systemPrompt,