@thinkai/tai-api-contract 2.171.0 → 2.173.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.171.0
+  version: 2.173.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -92,6 +92,12 @@ tags:
       classified test-file inventory (unit, integration, acceptance/BDD, contract, E2E)
       with count-based presence and advisory 70/20/10 shape. Distinct from Agentic
       Foundation readiness `/readiness/test-pyramid*` (signal-inclusive presence).
+  - name: Evals
+    description: >
+      Workspace prompt/model eval suites (`/evals/*`) — authored golden cases with
+      deterministic expected-signal scoring, async runs (never scored on the request
+      path), and an Insights surface for regressions and token efficiency. Distinct
+      from AI Usage & Spend ingest and Agentic Foundation Token Efficiency (rubric I).
 
 paths:
   /admin/users/{userId}:
@@ -8829,7 +8835,8 @@ paths:
         `status` is `indexing`, `generating_agent_md`, `failed`, or `ready`. Chat stays closed
         until `ready`: create thread and post message return `409 chat_not_ready` with
         `progressMessage` when status is not ready. An open index wave reports `indexing` until
-        every job in that wave is terminal.
+        every job in that wave is terminal. When ready, includes `activeProvider` and
+        `attachmentLimits` for Conversations file uploads.
       operationId: getCodeChatReadiness
       x-test-coverage-skip: thin HTTP over deriveCodeChatReadiness; covered by code-chat-readiness unit tests
       parameters:
@@ -8853,6 +8860,58 @@ paths:
                 error: Code Intelligence is disabled for this workspace
                 code: code_intelligence_disabled
 
+  /workspaces/{workspaceId}/code-chat/attachments:
+    post:
+      tags: [CodeChat]
+      summary: Upload a Conversations attachment
+      description: >
+        Any workspace member when chat is ready. Validates size/type against the active
+        provider profile (`attachmentLimits` from readiness). Returns metadata; pass `id`
+        as `attachmentIds` on the next POST message. Max 5 MB per file.
+      operationId: postCodeChatAttachment
+      x-test-coverage-skip: thin HTTP over validateAttachment + store insert
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatUploadAttachmentBodyDto"
+      responses:
+        "201":
+          description: Attachment stored
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatAttachmentMetaDto"
+        "400":
+          description: Validation failed (size, type, totals)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Chat not ready
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: Could not process the file
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/code-chat/indexes/{indexId}:
     get:
       tags: [CodeChat]
@@ -11939,6 +11998,350 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/evals/suites:
+    get:
+      tags: [Evals]
+      summary: List eval suites for a workspace
+      description: >
+        Returns the latest version of each eval suite in the workspace (max 50 suites).
+        Requires workspace membership (`requireWorkspaceMember`). Empty workspace →
+        `{ "suites": [] }`.
+      operationId: listEvalSuites
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Suite list (latest version per suite)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteListDto"
+              example:
+                suites: []
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [Evals]
+      summary: Create an eval suite
+      description: >
+        Creates a suite at `version: 1`. Requires workspace editor or admin
+        (`requireWorkspaceEditor`). Rejects when both `target.promptBody` is empty
+        and model fields are missing; when `cases` is empty (`400`
+        `eval_suite_cases_required`); or when the workspace already has 50 suites.
+        Each case must include at least one expected signal.
+      operationId: createEvalSuite
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateEvalSuiteBodyDto"
+            example:
+              name: Greeting quality
+              description: Fixture-backed smoke suite for the support greeting prompt
+              target:
+                promptBody: "You are a support agent. Greet the user by name."
+                promptKey: support-greeting
+                provider: cursor
+                modelName: gpt-4.1-mini
+              cases:
+                - id: case-hello
+                  name: Hello Alice
+                  input: '{"name":"Alice"}'
+                  fixtureCompletion: "Hello Alice, how can I help you today?"
+                  expectedSignals:
+                    - id: sig-contains-hello
+                      kind: contains
+                      value: "Hello Alice"
+                    - id: sig-not-sorry
+                      kind: not_contains
+                      value: "I cannot"
+      responses:
+        "201":
+          description: Suite created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "400":
+          description: >
+            Validation failed — empty cases (`eval_suite_cases_required`), missing
+            target (prompt and model), invalid name/description lengths, case/signal
+            bounds, or malformed body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                cases_required:
+                  value:
+                    error: At least one case is required
+                    code: eval_suite_cases_required
+                target_required:
+                  value:
+                    error: Suite target requires promptBody or provider+modelName
+                    code: eval_suite_target_required
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Workspace already has the maximum of 50 suites
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Maximum of 50 eval suites per workspace
+                code: eval_suite_limit_reached
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}:
+    get:
+      tags: [Evals]
+      summary: Get an eval suite (latest version)
+      description: >
+        Returns the latest version of the suite. Historical versions are retained for
+        runs via `suiteVersion` + snapshot on each run; this endpoint does not expose
+        prior versions. Requires workspace membership.
+      operationId: getEvalSuite
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "200":
+          description: Suite (latest version)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [Evals]
+      summary: Update an eval suite
+      description: >
+        Replaces mutable suite fields. Requires workspace editor or admin.
+        Changing `target`, `cases`, or `promptBody` increments `version` by 1 and
+        keeps prior versions immutable for historical runs. Cosmetic
+        name/description-only updates do not bump `version`. Same validation rules
+        as create (cases required, target required, bounds).
+      operationId: updateEvalSuite
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateEvalSuiteBodyDto"
+      responses:
+        "200":
+          description: Suite updated (possibly with bumped version)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "400":
+          description: Validation failed (same codes as create)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}/runs:
+    get:
+      tags: [Evals]
+      summary: List recent eval runs for a suite
+      description: >
+        Returns the last 50 runs for the suite (newest first). Empty → `{ "runs": [] }`.
+        Requires workspace membership. Does not trigger scoring.
+      operationId: listEvalRuns
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "200":
+          description: Run history (max 50)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunListDto"
+              example:
+                runs: []
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [Evals]
+      summary: Enqueue an eval suite run
+      description: >
+        Enqueues an async eval run. Returns `202` with `{ runId, status: "queued" }`.
+        Never scores on the request path — a worker claims the run, uses
+        `fixtureCompletion` when present (or live completion when provider credentials
+        exist), applies deterministic expected-signal scoring, and persists results.
+        Requires workspace editor or admin. At most one active (`queued`|`running`)
+        run per suite; a second POST returns `409` `eval_run_in_progress`.
+      operationId: enqueueEvalRun
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "202":
+          description: Run queued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunEnqueueResponseDto"
+              example:
+                runId: "22222222-2222-4222-8222-222222222222"
+                status: queued
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: An active queued or running eval already exists for this suite
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: An eval run is already in progress for this suite
+                code: eval_run_in_progress
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}/runs/{runId}:
+    get:
+      tags: [Evals]
+      summary: Get an eval run with case results
+      description: >
+        Returns persisted run status and case results. While `queued` or `running`,
+        `caseResults` may be empty and `score` null. Requires workspace membership.
+        Does not trigger scoring.
+      operationId: getEvalRun
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+        - $ref: "#/components/parameters/EvalRunId"
+      responses:
+        "200":
+          description: Run detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace, suite, or run not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/evals/insights:
+    get:
+      tags: [Evals]
+      summary: Eval insights (regressions, tips, efficiency, model comparison)
+      description: >
+        Workspace-level Insights for prompt/model evals. Computes regressions when
+        prior score − current score ≥ 0.10 on the same suiteId+suiteVersion case set
+        (or suite score drop ≥ 0.10); prompt tips from failed signal notes / case
+        names; token efficiency averages over successful cases in the last succeeded
+        run per suite; and model comparison rollups. No succeeded runs → empty arrays
+        and null `tokenEfficiency`. Requires workspace membership. Distinct from
+        `/insights-recommendations` and AI Usage & Spend.
+      operationId: getEvalInsights
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Insights payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalInsightsDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
 components:
   securitySchemes:
     bearerAuth:
@@ -11954,6 +12357,22 @@ components:
       required: true
       schema:
         type: string
+    EvalSuiteId:
+      name: suiteId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Eval suite id (`tai_workspace_eval_suites.id`).
+    EvalRunId:
+      name: runId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Eval run id (`tai_workspace_eval_runs.id`).
     RepoId:
       name: repoId
       in: path
@@ -13666,7 +14085,44 @@ components:
           format: date-time
           nullable: true
 
-    CodeChatReadinessDto:
+    CodeChatAttachmentLimitsDto:
+      type: object
+      required:
+        - maxFiles
+        - maxBytesPerFile
+        - maxTotalBytes
+        - maxTextChars
+        - maxPdfPages
+        - allowedMimeTypes
+        - allowedExtensions
+        - supportsImages
+        - supportsPdf
+      properties:
+        maxFiles: { type: integer, minimum: 1 }
+        maxBytesPerFile: { type: integer, minimum: 1 }
+        maxTotalBytes: { type: integer, minimum: 1 }
+        maxTextChars: { type: integer, minimum: 1 }
+        maxPdfPages: { type: integer, minimum: 1 }
+        allowedMimeTypes:
+          type: array
+          items: { type: string }
+        allowedExtensions:
+          type: array
+          items: { type: string }
+        supportsImages: { type: boolean }
+        supportsPdf: { type: boolean }
+
+    CodeChatAttachmentMetaDto:
+      type: object
+      required: [id, filename, mimeType, sizeBytes, createdAt]
+      properties:
+        id: { type: string, format: uuid }
+        filename: { type: string }
+        mimeType: { type: string }
+        sizeBytes: { type: integer, minimum: 1 }
+        createdAt: { type: string, format: date-time }
+
+    CodeChatReadinessDto:
       type: object
       required:
         - status
@@ -13705,6 +14161,13 @@ components:
           type: string
           nullable: true
           enum: [generated, admin]
+        activeProvider:
+          type: string
+          nullable: true
+          enum: [claude, cursor]
+          description: Active Ask synthesizer for attachment limit profiles
+        attachmentLimits:
+          $ref: "#/components/schemas/CodeChatAttachmentLimitsDto"
 
     CodeWikiGuidanceDto:
       type: object
@@ -23515,6 +23978,10 @@ components:
           type: array
           items: { $ref: "#/components/schemas/CodeChatCitationDto" }
         createdAt: { type: string, format: date-time }
+        attachments:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatAttachmentMetaDto" }
+          description: Present on user turns that included uploaded files
 
     CodeChatThreadDetailDto:
       allOf:
@@ -23541,6 +24008,24 @@ components:
           description: >
             Optional force deterministic inventory catalog instead of LLM synthesis.
             When omitted, the server classifies listing-style API/module questions automatically.
+        attachmentIds:
+          type: array
+          maxItems: 5
+          items: { type: string, format: uuid }
+          description: Previously uploaded attachment ids to bind to this user turn
+
+    CodeChatUploadAttachmentBodyDto:
+      type: object
+      required: [filename, mimeType, contentBase64]
+      properties:
+        filename: { type: string, minLength: 1, maxLength: 255 }
+        mimeType: { type: string, minLength: 1, maxLength: 255 }
+        contentBase64:
+          type: string
+          minLength: 1
+          description: Base64-encoded file bytes (no data-URL prefix required)
+        threadId: { type: string, format: uuid, nullable: true }
+        pdfPageCount: { type: integer, minimum: 1, nullable: true }
 
     CodeChatMessageReplyDto:
       allOf:
@@ -25489,3 +25974,539 @@ components:
         total: { type: integer, minimum: 0 }
         limit: { type: integer, minimum: 1 }
         offset: { type: integer, minimum: 0 }
+    EvalExpectedSignalKindDto:
+      type: string
+      description: >
+        Deterministic scorer kinds for golden-case expected signals. Case pass =
+        all signals pass. No LLM-as-judge in v1.
+      enum: [contains, not_contains, regex, json_path_equals]
+
+    EvalAiProviderDto:
+      type: string
+      description: >
+        Model provider vocabulary aligned with AI Usage `modelName` surfaces
+        (`cursor` | `claude`).
+      enum: [cursor, claude]
+
+    EvalExpectedSignalDto:
+      type: object
+      additionalProperties: false
+      required: [id, kind]
+      description: >
+        One expected signal on a golden case. Use `value` for `contains` /
+        `not_contains` (substring) and for `json_path_equals` (expected value as
+        string). Use `pattern` for `regex`. Use `path` (JSONPath) for
+        `json_path_equals`.
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        kind:
+          $ref: "#/components/schemas/EvalExpectedSignalKindDto"
+        value:
+          type: string
+          maxLength: 8000
+          description: >
+            Substring for `contains` / `not_contains`, or expected value for
+            `json_path_equals`.
+        pattern:
+          type: string
+          maxLength: 2000
+          description: Regular expression source for `regex`.
+        path:
+          type: string
+          maxLength: 500
+          description: JSONPath expression for `json_path_equals`.
+
+    EvalCaseDto:
+      type: object
+      additionalProperties: false
+      required: [id, name, input, expectedSignals]
+      description: >
+        One golden case in a suite. 1–20 cases per suite; each case requires ≥1
+        expected signal. When `fixtureCompletion` is set, the worker scores that
+        text without calling a live model (CI/demo path).
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        name:
+          type: string
+          minLength: 1
+          maxLength: 200
+        input:
+          type: string
+          minLength: 1
+          maxLength: 20000
+          description: Case input payload (opaque string; often JSON text).
+        fixtureCompletion:
+          type: string
+          maxLength: 100000
+          description: >
+            Optional fixture completion. When present, the worker uses it instead
+            of a live provider call.
+        expectedSignals:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalExpectedSignalDto"
+
+    EvalSuiteTargetDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Suite target — at least one of prompt or model. Prompt path requires
+        non-empty `promptBody` (text snapshot) and may include optional `promptKey`
+        slug. Model path requires `provider` + `modelName` (vendor string, same
+        vocabulary as AI Usage `modelName`). Create/update reject when both
+        prompt body is empty and model fields are missing. No separate
+        prompt-template registry in v1; versioning is the suite `version`.
+      properties:
+        promptBody:
+          type: string
+          maxLength: 100000
+          description: Prompt text snapshot. Empty string allowed only when model fields are set.
+        promptKey:
+          type: string
+          maxLength: 120
+          nullable: true
+          description: Optional slug for the prompt (not a registry foreign key in v1).
+        provider:
+          type: string
+          nullable: true
+          enum: [cursor, claude]
+          description: Model provider; null when suite is prompt-only.
+        modelName:
+          type: string
+          maxLength: 200
+          nullable: true
+          description: Vendor model id string (aligned with AI Usage `modelName`).
+
+    EvalSuiteDto:
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - name
+        - description
+        - version
+        - createdAt
+        - updatedAt
+        - createdByUserId
+        - target
+        - cases
+      description: >
+        Latest version of a workspace eval suite. Max 50 suites per workspace.
+        Name 1–120 chars; description ≤ 2000; version starts at 1.
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+        version:
+          type: integer
+          minimum: 1
+          description: Monotonic suite version; bumps when target/cases/promptBody change.
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        createdByUserId:
+          type: string
+          format: uuid
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
+
+    EvalSuiteListDto:
+      type: object
+      additionalProperties: false
+      required: [suites]
+      properties:
+        suites:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/EvalSuiteDto"
+
+    CreateEvalSuiteBodyDto:
+      type: object
+      additionalProperties: false
+      required: [name, target, cases]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+          default: ""
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
+
+    UpdateEvalSuiteBodyDto:
+      type: object
+      additionalProperties: false
+      required: [name, target, cases]
+      description: >
+        Full replace of mutable suite fields. Version bumps only when `target`,
+        `cases`, or `promptBody` change versus the stored latest version.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+          default: ""
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
+
+    EvalRunStatusDto:
+      type: string
+      enum: [queued, running, succeeded, failed, cancelled]
+
+    EvalCaseResultStatusDto:
+      type: string
+      description: >
+        Per-case outcome. `error` is used when completion is unavailable
+        (`code: completion_unavailable`) or another non-score failure occurs.
+      enum: [passed, failed, error]
+
+    EvalCaseResultDto:
+      type: object
+      additionalProperties: false
+      required:
+        - caseId
+        - name
+        - status
+        - pass
+        - failedSignalIds
+      description: >
+        Persisted result for one case. `pass` is true only when `status` is
+        `passed` (all expected signals matched). On signal failure, `pass` is
+        false and `failedSignalIds` lists the failing signal ids. On
+        `completion_unavailable`, `status` is `error` and `code` is set.
+      properties:
+        caseId:
+          type: string
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/EvalCaseResultStatusDto"
+        pass:
+          type: boolean
+        failedSignalIds:
+          type: array
+          items:
+            type: string
+        completion:
+          type: string
+          nullable: true
+          description: Completion text used for scoring (fixture or live).
+        inputTokens:
+          type: integer
+          nullable: true
+          minimum: 0
+        outputTokens:
+          type: integer
+          nullable: true
+          minimum: 0
+        costCents:
+          type: number
+          nullable: true
+          minimum: 0
+          description: Provider-reported cost in cents when available.
+        code:
+          type: string
+          nullable: true
+          description: >
+            Machine-readable error when `status` is `error`
+            (e.g. `completion_unavailable`).
+        error:
+          type: string
+          nullable: true
+          description: Human-readable error detail when `status` is `error`.
+
+    EvalSuiteSnapshotDto:
+      type: object
+      additionalProperties: false
+      required: [name, description, version, target, cases]
+      description: >
+        Immutable suite snapshot pinned on a run (`suiteVersion` + JSON). Used so
+        historical runs stay interpretable after later suite edits.
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        version:
+          type: integer
+          minimum: 1
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
+
+    EvalRunDto:
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - suiteId
+        - suiteVersion
+        - status
+        - startedAt
+        - finishedAt
+        - passCount
+        - failCount
+        - errorCount
+        - score
+        - caseResults
+      description: >
+        Persisted eval run. Suite score = `passedCases / scoredCases` in [0,1]
+        when at least one case was scored; `null` when the run ends with all
+        cases in `error` (status `failed`). List endpoints return at most the
+        last 50 runs per suite.
+      properties:
+        id:
+          type: string
+          format: uuid
+        suiteId:
+          type: string
+          format: uuid
+        suiteVersion:
+          type: integer
+          minimum: 1
+        status:
+          $ref: "#/components/schemas/EvalRunStatusDto"
+        startedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Set when the worker claims the run (`running`).
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+        passCount:
+          type: integer
+          minimum: 0
+        failCount:
+          type: integer
+          minimum: 0
+        errorCount:
+          type: integer
+          minimum: 0
+        score:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 1
+          description: >
+            `passedCases / scoredCases` in [0,1], or null when no case was scored
+            (all-error run).
+        caseResults:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalCaseResultDto"
+        suiteSnapshot:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/EvalSuiteSnapshotDto"
+          description: Pinned suite snapshot for this run (present on persisted runs).
+
+    EvalRunListDto:
+      type: object
+      additionalProperties: false
+      required: [runs]
+      properties:
+        runs:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/EvalRunDto"
+
+    EvalRunEnqueueResponseDto:
+      type: object
+      additionalProperties: false
+      required: [runId, status]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued]
+          description: Always `queued` on enqueue; poll GET run for progress.
+
+    EvalRegressionDto:
+      type: object
+      additionalProperties: false
+      required:
+        - suiteId
+        - suiteVersion
+        - priorScore
+        - currentScore
+        - scoreDrop
+      description: >
+        Regression when prior score − current score ≥ 0.10 on the same
+        suiteId+suiteVersion case set, or suite score drop ≥ 0.10.
+      properties:
+        suiteId:
+          type: string
+          format: uuid
+        suiteName:
+          type: string
+        suiteVersion:
+          type: integer
+          minimum: 1
+        caseId:
+          type: string
+          nullable: true
+          description: Set for case-level regressions; null for suite-level score drops.
+        caseName:
+          type: string
+          nullable: true
+        priorRunId:
+          type: string
+          format: uuid
+        currentRunId:
+          type: string
+          format: uuid
+        priorScore:
+          type: number
+          minimum: 0
+          maximum: 1
+        currentScore:
+          type: number
+          minimum: 0
+          maximum: 1
+        scoreDrop:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: priorScore − currentScore (always ≥ 0.10 for listed items).
+
+    EvalPromptTipDto:
+      type: object
+      additionalProperties: false
+      required: [suiteId, message]
+      description: Tip derived from failed signal notes / case names on recent runs.
+      properties:
+        suiteId:
+          type: string
+          format: uuid
+        suiteName:
+          type: string
+        caseId:
+          type: string
+          nullable: true
+        caseName:
+          type: string
+          nullable: true
+        signalId:
+          type: string
+          nullable: true
+        message:
+          type: string
+          maxLength: 2000
+
+    EvalTokenEfficiencyDto:
+      type: object
+      additionalProperties: false
+      required: [avgInputTokens, avgOutputTokens, avgCostCents]
+      description: >
+        Averages over successful cases in the last succeeded run per suite
+        (workspace rollup). Nullables when token/cost fields were not returned.
+      properties:
+        avgInputTokens:
+          type: number
+          nullable: true
+          minimum: 0
+        avgOutputTokens:
+          type: number
+          nullable: true
+          minimum: 0
+        avgCostCents:
+          type: number
+          nullable: true
+          minimum: 0
+
+    EvalModelComparisonDto:
+      type: object
+      additionalProperties: false
+      required: [provider, modelName, suiteCount, avgScore]
+      properties:
+        provider:
+          $ref: "#/components/schemas/EvalAiProviderDto"
+        modelName:
+          type: string
+        suiteCount:
+          type: integer
+          minimum: 0
+        avgScore:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 1
+          description: Average suite score across succeeded runs for this model; null when none.
+
+    EvalInsightsDto:
+      type: object
+      additionalProperties: false
+      required: [regressions, promptTips, tokenEfficiency, modelComparison]
+      description: >
+        Insights hub payload for Prompt & model evals. Empty succeeded-run history
+        → empty arrays and null `tokenEfficiency`.
+      properties:
+        regressions:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalRegressionDto"
+        promptTips:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalPromptTipDto"
+        tokenEfficiency:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/EvalTokenEfficiencyDto"
+        modelComparison:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalModelComparisonDto"