Review every new snapshot with an agent from the other vendor

api/openapi.yaml

@@ -543,6 +543,22 @@ paths:
                 items: { $ref: "#/components/schemas/Snapshot" }
         "404": { $ref: "#/components/responses/Error" }
 
+  /api/tasks/{taskId}/reviews:
+    parameters:
+      - { name: taskId, in: path, required: true, schema: { type: string } }
+    get:
+      operationId: listReviews
+      description: The task's reviews, one per snapshot, oldest first.
+      responses:
+        "200":
+          description: The reviews.
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/Review" }
+        "404": { $ref: "#/components/responses/Error" }
+
   /api/tasks/{taskId}/snapshots/{n}/fork:
     parameters:
       - { name: taskId, in: path, required: true, schema: { type: string } }
@@ -1025,6 +1041,26 @@ components:
         port: { type: integer, description: "A port in the task's block, served at https://<byre's host>:<port>/." }
         created_at: { type: string, format: date-time }
 
+    Review:
+      type: object
+      description: An agent session on the vendor the task's agent doesn't use, reviewing one snapshot's change.
+      required: [id, task_id, snapshot_n, agent_session_id, vendor, model, state, error, created_at]
+      properties:
+        id: { type: string }
+        task_id: { type: string }
+        snapshot_n: { type: integer }
+        agent_session_id: { type: string, description: The reviewer's session. }
+        vendor: { type: string }
+        model: { type: string }
+        state:
+          type: string
+          enum: [running, done, failed]
+          x-enum-varnames: [ReviewStateRunning, ReviewStateDone, ReviewStateFailed]
+        result: { type: object, description: "done: the reviewer's submit_review arguments: summary (Markdown) and findings, each with severity, category, title, detail, path and line." }
+        error: { type: string, description: "failed: why." }
+        created_at: { type: string, format: date-time }
+        finished_at: { type: string, format: date-time }
+
     AgentSession:
       type: object
       required: [id, task_id, owner, vendor, model, vendor_session_id, state, role, created_by, created_at]
@@ -1039,7 +1075,7 @@ components:
           type: string
           enum: [idle, running, completed]
           x-enum-varnames: [AgentSessionStateIdle, AgentSessionStateRunning, AgentSessionStateCompleted]
-        role: { type: string, enum: [implementer, lead] }
+        role: { type: string, enum: [implementer, lead, reviewer], description: "reviewer: a review's session (see Review); a task's sessions list leaves these out." }
         created_by: { type: string }
         created_at: { type: string, format: date-time }
         forked_from: { type: string, description: "A fork's first start resumes this vendor session, cut at forked_at, under a new vendor_session_id; absent for other sessions." }
@@ -1100,7 +1136,7 @@ components:
 
     InboxItem:
       type: object
-      required: [id, project_id, task_id, agent_session_id, thread_id, kind, priority, blocking, payload, state, created_at, responses]
+      required: [id, project_id, task_id, agent_session_id, thread_id, kind, priority, blocking, payload, state, created_at, responses, reviews]
       properties:
         id: { type: string }
         project_id: { type: string }
@@ -1108,7 +1144,10 @@ components:
         agent_session_id: { type: string }
         thread_id: { type: string }
         kind: { type: string, enum: [question, report, session_error, rate_limited] }
-        priority: { type: string, enum: [blocked, gate, review, fyi] }
+        priority:
+          type: string
+          enum: [blocked, gate, review, fyi]
+          x-enum-varnames: [Blocked, Gate, ReviewPriority, Fyi]
         blocking: { type: boolean }
         payload:
           type: object
@@ -1119,6 +1158,10 @@ components:
             session_error: error.
             rate_limited: vendor, rate_limit (the vendor's rate-limit status), error.
         state: { $ref: "#/components/schemas/InboxState" }
+        reviews:
+          type: array
+          description: "question: the review of the first snapshot the task took after the question was asked (the snapshot at the end of the turn that asked it), once that snapshot exists; empty for other items."
+          items: { $ref: "#/components/schemas/Review" }
         created_at: { type: string, format: date-time }
         resolved_by: { type: string }
         resolved_at: { type: string, format: date-time }
@@ -1206,8 +1249,8 @@ components:
 
     TaskTab:
       type: string
-      enum: [transcript, changes, files, terminal, preview, inbox, project]
-      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabTerminal, TabPreview, TabInbox, TabProject]
+      enum: [transcript, changes, files, terminal, preview, inbox, reviews, project]
+      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabTerminal, TabPreview, TabInbox, TabReviews, TabProject]
 
     TerminalSize:
       type: object