Add Workflow tab and run-progress API for workflow runs

api/openapi.yaml

@@ -277,6 +277,22 @@ paths:
               schema: { $ref: "#/components/schemas/TaskWorkflow" }
         "404": { $ref: "#/components/responses/Error" }
 
+  /api/tasks/{taskId}/workflow/run:
+    parameters:
+      - { name: taskId, in: path, required: true, schema: { type: string } }
+    get:
+      operationId: getWorkflowRun
+      description: >
+        The progress of the workflow run the task belongs to: the definition the task froze, and for each stage its
+        state and every task that attempted it, with the attempts whose outputs each one started from.
+      responses:
+        "200":
+          description: The run's progress.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WorkflowRun" }
+        "404": { $ref: "#/components/responses/Error" }
+
   /api/tasks/{taskId}/unmerged:
     parameters:
       - { name: taskId, in: path, required: true, schema: { type: string } }
@@ -1107,6 +1123,77 @@ components:
         name: { type: string }
         definition: { type: string, description: The WorkflowDefinition as YAML. }
 
+    WorkflowRun:
+      type: object
+      required: [name, run, title, brief, definition, finished, stages]
+      properties:
+        name: { type: string }
+        run: { type: string }
+        title: { type: string }
+        brief: { type: string }
+        definition: { $ref: "#/components/schemas/WorkflowDefinition" }
+        finished: { type: boolean, description: "Whether the final stage finished, which ends the run." }
+        stages:
+          type: array
+          description: In the definition's order.
+          items: { $ref: "#/components/schemas/WorkflowRunStage" }
+
+    WorkflowRunStage:
+      type: object
+      required: [name, after, state, waiting_on, attempts]
+      properties:
+        name: { type: string }
+        after:
+          type: array
+          description: The stages it comes after, with the definition's defaults applied.
+          items: { type: string }
+        state:
+          type: string
+          enum: [waiting, running, idle, finished, merged, discarded, cleaned_up]
+          x-enum-varnames: [StageStateWaiting, StageStateRunning, StageStateIdle, StageStateFinished, StageStateMerged, StageStateDiscarded, StageStateCleanedUp]
+          description: >
+            waiting: no task yet. Otherwise the state of its latest finished attempt, or of its latest attempt when
+            none has finished.
+        waiting_on:
+          type: array
+          description: The after stages with no finished attempt yet.
+          items: { type: string }
+        attempts:
+          type: array
+          description: The tasks that ran the stage (the first, and forks of it), oldest first.
+          items: { $ref: "#/components/schemas/StageAttempt" }
+
+    StageAttempt:
+      type: object
+      required: [task_id, title, state, discarding, inputs]
+      properties:
+        task_id: { type: string }
+        title: { type: string }
+        state:
+          type: string
+          enum: [running, idle, finished, merged, discarded, cleaned_up]
+          x-enum-varnames: [AttemptStateRunning, AttemptStateIdle, AttemptStateFinished, AttemptStateMerged, AttemptStateDiscarded, AttemptStateCleanedUp]
+          description: >
+            running: its agent is mid-turn. idle: active, and finish_stage hasn't taken. finished: active, its output
+            recorded. merged. discarded: discarded before finishing. cleaned_up: discarded after finishing, as byre
+            does to the run's other tasks when the final stage finishes.
+        discarding: { type: boolean, description: "Whether a Discard was started and the task isn't closed yet." }
+        forked_from: { type: string, description: "The task this attempt was forked from; absent for the stage's first attempt." }
+        output: { type: string, description: "The finish_stage output the stages after it get; absent until it finishes." }
+        commit: { type: string, description: "With output: the commit the stage finished at." }
+        discarded_by: { type: string, description: "discarded and cleaned_up: who discarded it; byre for the cleanup." }
+        inputs:
+          type: array
+          description: "The attempts whose outputs it started from, one per after stage; a fork has its source's."
+          items: { $ref: "#/components/schemas/StageInput" }
+
+    StageInput:
+      type: object
+      required: [stage, task_id]
+      properties:
+        stage: { type: string }
+        task_id: { type: string }
+
     TaskChanges:
       type: object
       required: [base, tree, files]
@@ -1424,8 +1511,8 @@ components:
 
     TaskTab:
       type: string
-      enum: [transcript, changes, files, terminal, inbox, reviews, project]
-      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabTerminal, TabInbox, TabReviews, TabProject]
+      enum: [transcript, changes, files, terminal, inbox, reviews, workflow, project]
+      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabTerminal, TabInbox, TabReviews, TabWorkflow, TabProject]
 
     TerminalSize:
       type: object