openapi: "3.1.0"
info:
  title: Arc Run API
  version: "0.1.0"
  description: HTTP API for managing Arc workflow run executions.

tags:
  - name: Discovery
    description: API discovery and health
  - name: Runs
    description: Run management operations
  - name: Human-in-the-Loop
    description: Questions, answers, and steering for runs
  - name: Run Outputs
    description: Files and verifications produced by runs
  - name: Run Internals
    description: Internal run details (stages, turns, context, configuration)
  - name: Workflows
    description: Workflow definitions and execution
  - name: Verifications
    description: Verification categories and controls
  - name: Usage
    description: Token and cost usage
  - name: Insights
    description: SQL query editor and history
  - name: Sessions
    description: Interactive chat sessions
  - name: Retros
    description: Run retrospectives
  - name: Projects
    description: Project and branch management
  - name: Settings
    description: Platform configuration

paths:
  # ── Discovery ────────────────────────────────────────────────────────

  /:
    get:
      operationId: getRoot
      tags: [Discovery]
      summary: API Discovery
      description: Returns discovery URLs for the API.
      responses:
        "200":
          description: Discovery URLs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RootResponse"

  /health:
    get:
      operationId: getHealth
      tags: [Discovery]
      summary: Health Check
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /openapi.json:
    get:
      operationId: getOpenApiSpec
      tags: [Discovery]
      summary: OpenAPI Specification
      description: Returns the OpenAPI spec as JSON.
      responses:
        "200":
          description: OpenAPI specification
          content:
            application/json:
              schema:
                type: object

  /user:
    get:
      operationId: getUser
      tags: [Discovery]
      summary: Current User
      description: Returns info about the authenticated user.
      responses:
        "200":
          description: User info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Runs ──────────────────────────────────────────────────────────────

  /runs:
    get:
      operationId: listRuns
      tags: [Runs]
      summary: List Runs
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of runs for the board view
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedRunList"
    post:
      operationId: startRun
      tags: [Runs]
      summary: Start Run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRunRequest"
      responses:
        "201":
          description: Run created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StartRunResponse"
        "400":
          description: Invalid DOT source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}:
    get:
      operationId: retrieveRun
      tags: [Runs]
      summary: Retrieve Run
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunStatusResponse"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/cancel:
    post:
      operationId: cancelRun
      tags: [Runs]
      summary: Cancel Run
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancelled:
                    type: boolean
                required:
                  - cancelled
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Run is not running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/graph:
    get:
      operationId: retrieveRunSvg
      tags: [Runs]
      summary: Render SVG
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: SVG image of the workflow graph
          content:
            image/svg+xml:
              schema:
                type: string
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Graphviz not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/checkpoint:
    get:
      operationId: retrieveRunCheckpoint
      tags: [Run Internals]
      summary: Retrieve Run Checkpoint
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Checkpoint data (null if not yet available)
          content:
            application/json:
              schema: {}
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/context:
    get:
      operationId: retrieveRunContext
      tags: [Run Internals]
      summary: Retrieve Run Context
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Context key-value map
          content:
            application/json:
              schema:
                type: object
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/events:
    get:
      operationId: streamRunEvents
      tags: [Runs]
      summary: Stream Run Events
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Server-sent event stream
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: Event stream closed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/questions:
    get:
      operationId: listRunQuestions
      tags: [Human-in-the-Loop]
      summary: List Run Questions
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Array of pending questions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedApiQuestionList"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/questions/{qid}/answer:
    post:
      operationId: submitRunAnswer
      tags: [Human-in-the-Loop]
      summary: Submit Run Answer
      parameters:
        - $ref: "#/components/parameters/RunId"
        - name: qid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitAnswerRequest"
      responses:
        "200":
          description: Answer accepted or rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmitAnswerResponse"
        "400":
          description: Invalid option key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/retro:
    get:
      operationId: retrieveRetro
      tags: [Retros]
      summary: Retrieve Retro
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Retro data (null if not yet available)
          content:
            application/json:
              schema: {}
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/stages:
    get:
      operationId: listRunStages
      tags: [Run Internals]
      summary: List Run Stages
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Array of run stages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedRunStageList"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/stages/{stageId}/turns:
    get:
      operationId: listStageTurns
      tags: [Run Internals]
      summary: List Stage Turns
      parameters:
        - $ref: "#/components/parameters/RunId"
        - name: stageId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of conversation turns
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedStageTurnList"
        "404":
          description: Run or stage not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/compare:
    get:
      operationId: listRunCompare
      tags: [Run Outputs]
      summary: List Run Compare
      parameters:
        - $ref: "#/components/parameters/RunId"
        - name: checkpoint
          in: query
          schema:
            type: string
            default: "all"
      responses:
        "200":
          description: File changes with checkpoint metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunCompare"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/usage:
    get:
      operationId: retrieveRunUsage
      tags: [Run Outputs]
      summary: Retrieve Run Usage
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Usage data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunUsage"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/verifications:
    get:
      operationId: listRunVerifications
      tags: [Run Outputs]
      summary: List Run Verifications
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Array of verification categories with controls
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedRunVerificationList"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/configuration:
    get:
      operationId: retrieveRunConfiguration
      tags: [Run Internals]
      summary: Retrieve Run Configuration
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Configuration content
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/steer:
    post:
      operationId: steerRun
      tags: [Human-in-the-Loop]
      summary: Steer Run
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SteerRequest"
      responses:
        "200":
          description: Steering accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                required:
                  - accepted
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/preview:
    post:
      operationId: generatePreviewUrl
      tags: [Human-in-the-Loop]
      summary: Preview URL
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewUrlRequest"
      responses:
        "200":
          description: Preview URL generated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewUrlResponse"
        "404":
          description: Run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Workflows ─────────────────────────────────────────────────────────

  /workflows:
    get:
      operationId: listWorkflows
      tags: [Workflows]
      summary: List Workflows
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of workflows
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedWorkflowList"

  /workflows/{name}:
    get:
      operationId: retrieveWorkflow
      tags: [Workflows]
      summary: Retrieve Workflow
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Workflow detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowDetail"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /workflows/{name}/runs:
    get:
      operationId: listWorkflowRuns
      tags: [Workflows]
      summary: List Workflow Runs
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedRunList"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      operationId: startWorkflowRun
      tags: [Workflows]
      summary: Start Workflow Run
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Run created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StartRunResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Verifications ─────────────────────────────────────────────────────

  /verifications:
    get:
      operationId: listVerifications
      tags: [Verifications]
      summary: List Verifications
      responses:
        "200":
          description: Array of verification categories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedVerificationCategoryList"

  /verifications/{slug}:
    get:
      operationId: retrieveVerification
      tags: [Verifications]
      summary: Retrieve Verification
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Verification control detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerificationDetailResponse"
        "404":
          description: Control not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Retros ────────────────────────────────────────────────────────────

  /retros:
    get:
      operationId: listRetros
      tags: [Retros]
      summary: List Retros
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of retros
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedRetroList"

  # ── Sessions ──────────────────────────────────────────────────────────

  /sessions:
    get:
      operationId: listSessions
      tags: [Sessions]
      summary: List Sessions
      description: Returns sessions grouped by recency (e.g. "Today", "Yesterday"). Each group contains a flat list of session summaries.
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of session groups
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSessionGroupList"
    post:
      operationId: createSession
      tags: [Sessions]
      summary: Create Session
      description: Start a new interactive chat session. The initial user prompt is required; a model may optionally be specified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSessionRequest"
      responses:
        "201":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSessionResponse"

  /sessions/{id}:
    get:
      operationId: retrieveSession
      tags: [Sessions]
      summary: Retrieve Session
      description: Returns the full session detail including all conversation turns.
      parameters:
        - name: id
          in: path
          required: true
          description: Unique session identifier.
          schema:
            type: string
          example: s1
      responses:
        "200":
          description: Session detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionDetail"
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sessions/{id}/messages:
    post:
      operationId: sendSessionMessage
      tags: [Sessions]
      summary: Send Session Message
      description: Append a user message to an existing session. The server will process it and produce assistant and tool turns asynchronously via the event stream.
      parameters:
        - name: id
          in: path
          required: true
          description: Unique session identifier.
          schema:
            type: string
          example: s1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendMessageRequest"
      responses:
        "200":
          description: Message accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                    description: Whether the message was accepted for processing.
                    example: true
                required:
                  - accepted
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /sessions/{id}/events:
    get:
      operationId: streamSessionEvents
      tags: [Sessions]
      summary: Stream Session Events
      description: Opens a server-sent event (SSE) stream for real-time session updates. Events include new assistant turns, tool invocations, and completion signals.
      parameters:
        - name: id
          in: path
          required: true
          description: Unique session identifier.
          schema:
            type: string
          example: s1
      responses:
        "200":
          description: Server-sent event stream
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Insights ──────────────────────────────────────────────────────────

  /insights/queries:
    get:
      operationId: listSavedQueries
      tags: [Insights]
      summary: List Saved Queries
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of saved queries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSavedQueryList"
    post:
      operationId: createSavedQuery
      tags: [Insights]
      summary: Create Saved Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SaveQueryRequest"
      responses:
        "201":
          description: Query saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SavedQuery"

  /insights/queries/{id}:
    put:
      operationId: updateSavedQuery
      tags: [Insights]
      summary: Update Saved Query
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SaveQueryRequest"
      responses:
        "200":
          description: Query updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SavedQuery"
        "404":
          description: Query not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      operationId: deleteSavedQuery
      tags: [Insights]
      summary: Delete Saved Query
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Query deleted
        "404":
          description: Query not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /insights/execute:
    post:
      operationId: executeQuery
      tags: [Insights]
      summary: Execute Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecuteQueryRequest"
      responses:
        "200":
          description: Query results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecuteQueryResponse"

  /insights/history:
    get:
      operationId: listQueryHistory
      tags: [Insights]
      summary: List Query History
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of history entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedHistoryEntryList"

  # ── Usage ────────────────────────────────────────────────────────────

  /usage:
    get:
      operationId: getAggregateUsage
      tags: [Usage]
      summary: Aggregate Usage
      description: Returns aggregate token/cost usage across all completed runs since server start.
      responses:
        "200":
          description: Aggregate usage data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AggregateUsage"

  # ── Settings ──────────────────────────────────────────────────────────

  /settings:
    get:
      operationId: retrieveServerSettings
      tags: [Settings]
      summary: Retrieve Server Settings
      responses:
        "200":
          description: Array of setting groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SettingGroup"

  # ── Projects ──────────────────────────────────────────────────────────

  /projects:
    get:
      operationId: listProjects
      tags: [Projects]
      summary: List Projects
      parameters:
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of projects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedProjectList"

  /projects/{id}/branches:
    get:
      operationId: listBranches
      tags: [Projects]
      summary: List Branches
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
      responses:
        "200":
          description: Paginated list of branches
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedBranchList"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  parameters:
    RunId:
      name: id
      in: path
      required: true
      schema:
        type: string

    PageLimit:
      name: page[limit]
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    PageOffset:
      name: page[offset]
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0

  schemas:
    PaginationMeta:
      type: object
      required:
        - has_more
      properties:
        has_more:
          type: boolean

    PaginatedRunList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RunListItem"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedWorkflowList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowListItem"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedRetroList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RetroListItem"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedSessionGroupList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SessionGroup"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedProjectList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Project"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedBranchList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Branch"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedSavedQueryList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SavedQuery"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedHistoryEntryList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/HistoryEntry"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedStageTurnList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/StageTurn"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedApiQuestionList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ApiQuestion"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedRunStageList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RunStage"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedRunVerificationList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RunVerification"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    PaginatedVerificationCategoryList:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VerificationCategory"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    # ── Existing Run Schemas ────────────────────────────────────────────

    RunStatus:
      type: string
      enum:
        - queued
        - starting
        - running
        - completed
        - failed
        - cancelled

    StartRunRequest:
      type: object
      required:
        - dot_source
      properties:
        dot_source:
          type: string

    StartRunResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string

    RunStatusResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/RunStatus"
        error:
          type: string
        queue_position:
          type: integer

    ApiQuestionOption:
      type: object
      required:
        - key
        - label
      properties:
        key:
          type: string
        label:
          type: string

    ApiQuestion:
      type: object
      required:
        - id
        - text
        - question_type
        - options
        - allow_freeform
      properties:
        id:
          type: string
        text:
          type: string
        question_type:
          $ref: "#/components/schemas/QuestionType"
        options:
          type: array
          items:
            $ref: "#/components/schemas/ApiQuestionOption"
        allow_freeform:
          type: boolean

    QuestionType:
      type: string
      enum:
        - yes_no
        - multiple_choice
        - multi_select
        - freeform
        - confirmation

    SubmitAnswerRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
        selected_option_key:
          type: string

    SubmitAnswerResponse:
      type: object
      required:
        - accepted
      properties:
        accepted:
          type: boolean

    ErrorResponseEntry:
      type: object
      required:
        - status
        - title
        - detail
      properties:
        status:
          type: string
        title:
          type: string
        detail:
          type: string

    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ErrorResponseEntry"

    # ── New Run Schemas ─────────────────────────────────────────────────

    RunListItemStatus:
      type: string
      enum:
        - working
        - pending
        - review
        - merge

    CheckRunStatus:
      type: string
      enum:
        - success
        - failure
        - skipped
        - pending
        - queued

    CheckRun:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
        status:
          $ref: "#/components/schemas/CheckRunStatus"
        duration_secs:
          type: number

    RunListItem:
      type: object
      required:
        - id
        - repo
        - title
        - workflow
        - status
      properties:
        id:
          type: string
        repo:
          type: string
        title:
          type: string
        workflow:
          type: string
        status:
          $ref: "#/components/schemas/RunListItemStatus"
        number:
          type: integer
        additions:
          type: integer
        deletions:
          type: integer
        checks:
          type: array
          items:
            $ref: "#/components/schemas/CheckRun"
        elapsed_secs:
          type: number
        elapsed_warning:
          type: boolean
        resources:
          type: string
        comments:
          type: integer
        question:
          type: string
        sandbox_id:
          type: string

    StageStatus:
      type: string
      enum:
        - completed
        - running
        - pending
        - failed

    RunStage:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: "#/components/schemas/StageStatus"
        duration_secs:
          type: number
        dot_id:
          type: string

    ToolUse:
      description: A single tool invocation with its arguments and result.
      type: object
      required:
        - tool_name
        - args
        - result
      properties:
        tool_name:
          type: string
          description: Name of the tool that was invoked.
          example: read_file
        args:
          type: string
          description: JSON-encoded arguments passed to the tool.
          example: '{ "path": "src/routes/auth.ts" }'
        result:
          type: string
          description: Output returned by the tool.
          example: 'import { Router } from "express";'

    StageTurn:
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - system
            - assistant
            - tool
        content:
          type: string
        tools:
          type: array
          items:
            $ref: "#/components/schemas/ToolUse"

    FileCheckpoint:
      type: object
      required:
        - id
        - label
      properties:
        id:
          type: string
        label:
          type: string

    DiffFile:
      type: object
      required:
        - name
        - contents
      properties:
        name:
          type: string
        contents:
          type: string

    FileDiff:
      type: object
      required:
        - old_file
        - new_file
      properties:
        old_file:
          $ref: "#/components/schemas/DiffFile"
        new_file:
          $ref: "#/components/schemas/DiffFile"

    DiffStats:
      type: object
      required:
        - additions
        - deletions
      properties:
        additions:
          type: integer
        deletions:
          type: integer

    RunCompare:
      type: object
      required:
        - checkpoints
        - files
        - stats
      properties:
        checkpoints:
          type: array
          items:
            $ref: "#/components/schemas/FileCheckpoint"
        files:
          type: array
          items:
            $ref: "#/components/schemas/FileDiff"
        stats:
          $ref: "#/components/schemas/DiffStats"

    UsageStage:
      type: object
      required:
        - stage
        - model
        - input_tokens
        - output_tokens
        - runtime_secs
        - cost
      properties:
        stage:
          type: string
        model:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        runtime_secs:
          type: number
        cost:
          type: number

    UsageTotals:
      type: object
      required:
        - runtime_secs
        - input_tokens
        - output_tokens
        - cost
      properties:
        runtime_secs:
          type: number
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        cost:
          type: number

    UsageByModel:
      type: object
      required:
        - model
        - stages
        - input_tokens
        - output_tokens
        - cost
      properties:
        model:
          type: string
        stages:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        cost:
          type: number

    RunUsage:
      type: object
      required:
        - stages
        - totals
        - by_model
      properties:
        stages:
          type: array
          items:
            $ref: "#/components/schemas/UsageStage"
        totals:
          $ref: "#/components/schemas/UsageTotals"
        by_model:
          type: array
          items:
            $ref: "#/components/schemas/UsageByModel"

    AggregateUsage:
      type: object
      required:
        - total_runs
        - total_input_tokens
        - total_output_tokens
        - total_cost
        - total_runtime_secs
        - by_model
      properties:
        total_runs:
          type: integer
        total_input_tokens:
          type: integer
        total_output_tokens:
          type: integer
        total_cost:
          type: number
        total_runtime_secs:
          type: number
        by_model:
          type: array
          items:
            $ref: "#/components/schemas/UsageByModel"

    VerificationStatus:
      type: string
      enum:
        - pass
        - fail
        - na

    VerificationType:
      type: string
      enum:
        - ai
        - automated
        - analysis
        - ai-analysis

    RunVerificationControl:
      type: object
      required:
        - name
        - description
        - status
      properties:
        name:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/VerificationType"
        status:
          $ref: "#/components/schemas/VerificationStatus"

    RunVerification:
      type: object
      required:
        - name
        - question
        - status
        - controls
      properties:
        name:
          type: string
        question:
          type: string
        status:
          $ref: "#/components/schemas/VerificationStatus"
        controls:
          type: array
          items:
            $ref: "#/components/schemas/RunVerificationControl"

    SteerRequest:
      type: object
      required:
        - file
        - line
        - guidance
      properties:
        file:
          type: string
        line:
          type: integer
        guidance:
          type: string

    PreviewUrlRequest:
      type: object
      required:
        - port
        - expires_in_secs
      properties:
        port:
          type: integer
        expires_in_secs:
          type: integer

    PreviewUrlResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string

    # ── Workflow Schemas ─────────────────────────────────────────────────

    WorkflowListItem:
      type: object
      required:
        - name
        - slug
        - filename
      properties:
        name:
          type: string
        slug:
          type: string
        filename:
          type: string
        last_run:
          type: string
        schedule:
          type: string
        next_run:
          type: string

    WorkflowDetail:
      type: object
      required:
        - title
        - slug
        - filename
        - description
        - config
        - graph
      properties:
        title:
          type: string
        slug:
          type: string
        filename:
          type: string
        description:
          type: string
        config:
          type: string
        graph:
          type: string

    # ── Verification Schemas ────────────────────────────────────────────

    EvaluationResult:
      type: string
      enum:
        - pass
        - fail
        - skip

    VerificationMode:
      type: string
      enum:
        - active
        - evaluate
        - disabled

    VerificationControl:
      type: object
      required:
        - name
        - slug
        - description
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/VerificationType"
        mode:
          $ref: "#/components/schemas/VerificationMode"
        f1:
          type: number
        pass_at_1:
          type: number
        evaluations:
          type: array
          items:
            $ref: "#/components/schemas/EvaluationResult"

    VerificationCategory:
      type: object
      required:
        - name
        - question
        - controls
      properties:
        name:
          type: string
        question:
          type: string
        controls:
          type: array
          items:
            $ref: "#/components/schemas/VerificationControl"

    ControlInfo:
      type: object
      required:
        - name
        - slug
        - description
        - category
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/VerificationType"
        category:
          type: string

    ControlPerformance:
      type: object
      required:
        - mode
        - evaluations
      properties:
        mode:
          $ref: "#/components/schemas/VerificationMode"
        f1:
          type: number
        pass_at_1:
          type: number
        evaluations:
          type: array
          items:
            $ref: "#/components/schemas/EvaluationResult"

    ControlDetail:
      type: object
      required:
        - description
        - checks
        - pass_example
        - fail_example
      properties:
        description:
          type: string
        checks:
          type: array
          items:
            type: string
        pass_example:
          type: string
        fail_example:
          type: string

    RecentControlResult:
      type: object
      required:
        - run_id
        - run_title
        - workflow
        - result
        - timestamp
      properties:
        run_id:
          type: string
        run_title:
          type: string
        workflow:
          type: string
        result:
          $ref: "#/components/schemas/VerificationStatus"
        timestamp:
          type: string

    SiblingControl:
      type: object
      required:
        - name
        - slug
      properties:
        name:
          type: string
        slug:
          type: string
        type:
          $ref: "#/components/schemas/VerificationType"
        mode:
          $ref: "#/components/schemas/VerificationMode"

    VerificationDetailResponse:
      type: object
      required:
        - control
        - performance
        - control_detail
        - recent_results
        - siblings
      properties:
        control:
          $ref: "#/components/schemas/ControlInfo"
        performance:
          $ref: "#/components/schemas/ControlPerformance"
        control_detail:
          $ref: "#/components/schemas/ControlDetail"
        recent_results:
          type: array
          items:
            $ref: "#/components/schemas/RecentControlResult"
        siblings:
          type: array
          items:
            $ref: "#/components/schemas/SiblingControl"

    # ── Retro Schemas ───────────────────────────────────────────────────

    SmoothnessRating:
      type: string
      enum:
        - effortless
        - smooth
        - bumpy
        - struggled
        - failed

    RetroStats:
      type: object
      required:
        - total_duration_ms
        - total_retries
        - files_touched
        - stages_completed
        - stages_failed
      properties:
        total_duration_ms:
          type: integer
        total_cost:
          type: number
        total_retries:
          type: integer
        files_touched:
          type: array
          items:
            type: string
        stages_completed:
          type: integer
        stages_failed:
          type: integer

    RetroListItem:
      type: object
      required:
        - run_id
        - workflow_name
        - goal
        - timestamp
        - stats
        - friction_point_count
      properties:
        run_id:
          type: string
        workflow_name:
          type: string
        goal:
          type: string
        timestamp:
          type: string
        smoothness:
          $ref: "#/components/schemas/SmoothnessRating"
        stats:
          $ref: "#/components/schemas/RetroStats"
        friction_point_count:
          type: integer

    # ── Session Schemas ─────────────────────────────────────────────────

    SessionListItem:
      description: Summary of a session shown in list views.
      type: object
      required:
        - id
        - title
        - created_at
      properties:
        id:
          type: string
          description: Unique session identifier.
          example: s1
        title:
          type: string
          description: Short title summarizing the session topic.
          example: Add rate limiting to auth endpoints
        created_at:
          type: string
          description: ISO 8601 timestamp when the session was created.
          example: "2026-03-06T14:30:00Z"

    SessionGroup:
      description: A group of sessions sharing a time-based label (e.g. "Today", "Yesterday").
      type: object
      required:
        - label
        - sessions
      properties:
        label:
          type: string
          description: Human-readable group heading.
          example: Today
        sessions:
          type: array
          description: Sessions belonging to this group, ordered by recency.
          items:
            $ref: "#/components/schemas/SessionListItem"

    SessionTurn:
      description: A single turn in a session conversation — a user message, assistant response, or tool invocation block.
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          description: The type of turn.
          enum:
            - user
            - assistant
            - tool
          example: user
        content:
          type: string
          description: Text content of the turn. Present for user and assistant turns, absent for tool turns.
          example: Add rate limiting to the auth endpoints using a sliding window approach with Redis.
        created_at:
          type: string
          description: ISO 8601 timestamp when the turn was created. Typically present for user turns.
          example: "2026-02-28T10:00:00Z"
        tools:
          type: array
          description: Tool invocations for this turn. Present only when kind is "tool".
          items:
            $ref: "#/components/schemas/ToolUse"

    SessionDetail:
      description: Full session record including metadata and the complete conversation history.
      type: object
      required:
        - id
        - title
        - model
        - created_at
        - updated_at
        - turns
      properties:
        id:
          type: string
          description: Unique session identifier.
          example: s1
        title:
          type: string
          description: Short title summarizing the session topic.
          example: Add rate limiting to auth endpoints
        model:
          type: string
          description: The LLM model used for this session.
          example: Opus 4.6
        created_at:
          type: string
          description: ISO 8601 timestamp when the session was created.
          example: "2026-03-06T14:30:00Z"
        updated_at:
          type: string
          description: ISO 8601 timestamp when the session was last updated (e.g. new turn added).
          example: "2026-03-06T15:45:00Z"
        turns:
          type: array
          description: Ordered list of conversation turns.
          items:
            $ref: "#/components/schemas/SessionTurn"

    CreateSessionRequest:
      description: Request body for starting a new session.
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: The initial user message to start the session.
          example: Add rate limiting to the auth endpoints using a sliding window approach with Redis, 10 requests per minute per IP.
        model:
          type: string
          description: LLM model to use. If omitted, the server default is used.
          example: Opus 4.6

    CreateSessionResponse:
      description: Response returned after successfully creating a session.
      type: object
      required:
        - id
        - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the newly created session.
          example: s42
        created_at:
          type: string
          description: ISO 8601 timestamp when the session was created.
          example: "2026-03-06T16:00:00Z"

    SendMessageRequest:
      description: Request body for sending a follow-up message in an existing session.
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: The user message text.
          example: Can you also add a bypass for internal health-check IPs?

    # ── Insights Schemas ────────────────────────────────────────────────

    SavedQuery:
      type: object
      required:
        - id
        - name
        - sql
      properties:
        id:
          type: string
        name:
          type: string
        sql:
          type: string

    SaveQueryRequest:
      type: object
      required:
        - name
        - sql
      properties:
        name:
          type: string
        sql:
          type: string

    ExecuteQueryRequest:
      type: object
      required:
        - sql
      properties:
        sql:
          type: string

    ExecuteQueryResponse:
      type: object
      required:
        - columns
        - rows
        - elapsed
        - row_count
      properties:
        columns:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items: {}
        elapsed:
          type: number
        row_count:
          type: integer

    HistoryEntry:
      type: object
      required:
        - id
        - sql
        - timestamp
        - elapsed
        - row_count
      properties:
        id:
          type: string
        sql:
          type: string
        timestamp:
          type: string
        elapsed:
          type: number
        row_count:
          type: integer

    # ── Settings Schemas ────────────────────────────────────────────────

    SettingFieldType:
      type: string
      enum:
        - text
        - select
        - toggle

    SettingField:
      type: object
      required:
        - key
        - label
        - value
        - type
      properties:
        key:
          type: string
        label:
          type: string
        value:
          type: string
        type:
          $ref: "#/components/schemas/SettingFieldType"
        options:
          type: array
          items:
            type: string
        description:
          type: string

    SettingGroup:
      type: object
      required:
        - id
        - name
        - description
        - fields
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        fields:
          type: array
          items:
            $ref: "#/components/schemas/SettingField"

    # ── Project Schemas ─────────────────────────────────────────────────

    Project:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string

    Branch:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string

    # ── Discovery Schemas ──────────────────────────────────────────────

    RootResponseUrls:
      type: object
      required:
        - openapi_url
        - current_user_url
        - health_url
      properties:
        openapi_url:
          type: string
        current_user_url:
          type: string
        health_url:
          type: string

    RootResponse:
      type: object
      required:
        - urls
      properties:
        urls:
          $ref: "#/components/schemas/RootResponseUrls"

    HealthResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string

    UserResponse:
      type: object
      required:
        - login
      properties:
        login:
          type: string