@thinkai/tai-api-contract 2.7.2 → 2.8.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.7.2
+  version: 2.7.3
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -2348,6 +2348,109 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/readiness/repos/{repoId}/runs:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Paginated readiness run history for one repository
+      description: >
+        Append-only scan history for charts on repo detail. Ordered by scan finish time
+        (or `createdAt` when still in progress). Use `cursor` from the previous response for
+        the next page. Failed and `partial_failed` runs are included with nullable `overallScore`.
+      operationId: listReadinessRepoRuns
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/RepoId"
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+            default: desc
+        - name: cursor
+          in: query
+          description: Opaque cursor from a prior response `nextCursor` field.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Run history page
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReadinessRepoRunListDto"
+        "400":
+          description: Invalid pagination query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/score-history:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Workspace score time-series for all repositories
+      description: >
+        Returns succeeded runs with stored `overallScore` per repo in one call (avoids N+1).
+        Points are ordered ascending by `finishedAt` within each repo. Omit failed and
+        `partial_failed` runs. Use `since` to bound the window; `limitPerRepo` caps points per repo
+        (most recent first, then returned oldest-to-newest within the cap).
+      operationId: getReadinessScoreHistory
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: since
+          in: query
+          description: ISO-8601 lower bound on `finishedAt` (inclusive).
+          schema:
+            type: string
+            format: date-time
+        - name: limitPerRepo
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+      responses:
+        "200":
+          description: Score history grouped by repository
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceReadinessScoreHistoryDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/agentic-foundation/dashboard:
     get:
       tags: [AgenticFoundation]
@@ -2439,6 +2542,7 @@ paths:
                             maxScore: 3
                             issues: []
                         lastAnalyzed: "2026-05-12T12:00:00.000Z"
+                        connectedAt: "2026-05-01T10:00:00.000Z"
                         teamId: null
                         provider:
                           kind: github
@@ -5658,6 +5762,92 @@ components:
           items:
             $ref: "#/components/schemas/ReadinessIssueDto"
 
+    ReadinessRepoRunHistoryItemDto:
+      type: object
+      required: [runId, status, overallScore, createdAt, finishedAt]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          $ref: "#/components/schemas/ReadinessRunStatusDto"
+        overallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+          description: Present for succeeded runs after migration 050; null otherwise.
+        createdAt:
+          type: string
+          format: date-time
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    ReadinessRepoRunListDto:
+      type: object
+      required: [items, limit, nextCursor]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessRepoRunHistoryItemDto"
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+        nextCursor:
+          type: string
+          nullable: true
+          description: Pass as `cursor` query param to fetch the next page; null when no more rows.
+
+    ReadinessScoreHistoryPointDto:
+      type: object
+      required: [finishedAt, overallScore]
+      properties:
+        finishedAt:
+          type: string
+          format: date-time
+        overallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+
+    ReadinessRepoScoreHistoryDto:
+      type: object
+      required: [repoId, repoName, connectedAt, points]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+          maxLength: 256
+        connectedAt:
+          type: string
+          format: date-time
+          description: When the repository was first materialized in the workspace (GitHub connect).
+        points:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessScoreHistoryPointDto"
+
+    WorkspaceReadinessScoreHistoryDto:
+      type: object
+      required: [workspaceId, generatedAt, repos]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessRepoScoreHistoryDto"
+
     RepoReadinessScoreDto:
       type: object
       required:
@@ -5667,6 +5857,7 @@ components:
         - overallScore
         - dimensions
         - lastAnalyzed
+        - connectedAt
         - provider
         - analysisStatus
       properties:
@@ -5691,6 +5882,10 @@ components:
         lastAnalyzed:
           type: string
           format: date-time
+        connectedAt:
+          type: string
+          format: date-time
+          description: First time this repository was materialized in the workspace (GitHub connect).
         teamId:
           type: string
           format: uuid
@@ -5704,6 +5899,16 @@ components:
           format: uuid
           nullable: true
           description: Present when `analysisStatus` is `queued` or `running`; use with `GET .../readiness/runs/{runId}`.
+        archivedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Set when the repo has been soft-archived (removed from installation or integration disconnected). Null means active.
+        archivedReason:
+          type: string
+          nullable: true
+          enum: [github_removed, installation_disconnected, installation_replaced, superseded, null]
+          description: Why the repo was archived. Only present when `archivedAt` is set.
 
     AgenticFoundationDashboardSummaryDto:
       type: object
@@ -5885,8 +6090,11 @@ components:
           description: >
             Machine-readable failure code when status is `failed`. Values in
             `FixRetryableErrorCode` may be re-queued via POST .../readiness/fixes/{fixId}/retry.
+            Values in `FixNonRetryableErrorCode` are permanent failures that require human
+            intervention or configuration changes before retrying.
           anyOf:
             - $ref: "#/components/schemas/FixRetryableErrorCode"
+            - $ref: "#/components/schemas/FixNonRetryableErrorCode"
             - type: string
         errorMessage:
           type: string
@@ -5911,6 +6119,28 @@ components:
         - RUNNER_INTERRUPTED
       description: Error codes accepted by POST .../readiness/fixes/{fixId}/retry.
 
+    FixNonRetryableErrorCode:
+      type: string
+      enum:
+        - POLICY_DENIED
+        - CHANGE_LIMIT_EXCEEDED
+        - BUILD_FAILED
+        - MERGE_CONFLICT
+        - AUTH_REVOKED
+        - UNSUPPORTED_DIMENSION
+        - DUPLICATE_ACTIVE
+        - processor_error
+      description: >
+        Permanent failure codes that cannot be resolved by retrying the same fix.
+        `POLICY_DENIED` — blocked by repo/dimension/path allowlist policy (admin must update `READINESS_FIX_*` env config).
+        `CHANGE_LIMIT_EXCEEDED` — generated diff exceeded max files or lines guardrail.
+        `BUILD_FAILED` — pre-PR gate command or GitHub check run failed on the fix branch.
+        `MERGE_CONFLICT` — could not apply the generated fix cleanly to the target branch.
+        `AUTH_REVOKED` — GitHub installation token or Cursor API key is missing or revoked.
+        `UNSUPPORTED_DIMENSION` — no skill is implemented for this readiness dimension.
+        `DUPLICATE_ACTIVE` — another fix is already in progress for the same issue.
+        `processor_error` — unexpected processor-level failure; check batch-runner logs.
+
     CreateFixRequestBodyDto:
       type: object
       required: [issueId, repoId]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/generated/openapi.ts

@@ -915,6 +915,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/readiness/repos/{repoId}/runs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Paginated readiness run history for one repository
+         * @description Append-only scan history for charts on repo detail. Ordered by scan finish time (or `createdAt` when still in progress). Use `cursor` from the previous response for the next page. Failed and `partial_failed` runs are included with nullable `overallScore`.
+         */
+        get: operations["listReadinessRepoRuns"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/{workspaceId}/readiness/score-history": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Workspace score time-series for all repositories
+         * @description Returns succeeded runs with stored `overallScore` per repo in one call (avoids N+1). Points are ordered ascending by `finishedAt` within each repo. Omit failed and `partial_failed` runs. Use `since` to bound the window; `limitPerRepo` caps points per repo (most recent first, then returned oldest-to-newest within the cap).
+         */
+        get: operations["getReadinessScoreHistory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/agentic-foundation/dashboard": {
         parameters: {
             query?: never;
@@ -2375,6 +2415,46 @@ export interface components {
             criteriaSummary?: components["schemas"]["ReadinessCriteriaSummaryDto"] | null;
             issues: components["schemas"]["ReadinessIssueDto"][];
         };
+        ReadinessRepoRunHistoryItemDto: {
+            /** Format: uuid */
+            runId: string;
+            status: components["schemas"]["ReadinessRunStatusDto"];
+            /** @description Present for succeeded runs after migration 050; null otherwise. */
+            overallScore: number | null;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            finishedAt: string | null;
+        };
+        ReadinessRepoRunListDto: {
+            items: components["schemas"]["ReadinessRepoRunHistoryItemDto"][];
+            limit: number;
+            /** @description Pass as `cursor` query param to fetch the next page; null when no more rows. */
+            nextCursor: string | null;
+        };
+        ReadinessScoreHistoryPointDto: {
+            /** Format: date-time */
+            finishedAt: string;
+            overallScore: number;
+        };
+        ReadinessRepoScoreHistoryDto: {
+            /** Format: uuid */
+            repoId: string;
+            repoName: string;
+            /**
+             * Format: date-time
+             * @description When the repository was first materialized in the workspace (GitHub connect).
+             */
+            connectedAt: string;
+            points: components["schemas"]["ReadinessScoreHistoryPointDto"][];
+        };
+        WorkspaceReadinessScoreHistoryDto: {
+            /** Format: uuid */
+            workspaceId: string;
+            /** Format: date-time */
+            generatedAt: string;
+            repos: components["schemas"]["ReadinessRepoScoreHistoryDto"][];
+        };
         RepoReadinessScoreDto: {
             /** Format: uuid */
             repoId: string;
@@ -2385,6 +2465,11 @@ export interface components {
             dimensions: components["schemas"]["DimensionScoreDto"][];
             /** Format: date-time */
             lastAnalyzed: string;
+            /**
+             * Format: date-time
+             * @description First time this repository was materialized in the workspace (GitHub connect).
+             */
+            connectedAt: string;
             /** Format: uuid */
             teamId?: string | null;
             provider: components["schemas"]["RepoProviderDto"];
@@ -2394,6 +2479,16 @@ export interface components {
              * @description Present when `analysisStatus` is `queued` or `running`; use with `GET .../readiness/runs/{runId}`.
              */
             activeRunId?: string | null;
+            /**
+             * Format: date-time
+             * @description Set when the repo has been soft-archived (removed from installation or integration disconnected). Null means active.
+             */
+            archivedAt?: string | null;
+            /**
+             * @description Why the repo was archived. Only present when `archivedAt` is set.
+             * @enum {string|null}
+             */
+            archivedReason?: "github_removed" | "installation_disconnected" | "installation_replaced" | "superseded" | null;
         };
         AgenticFoundationDashboardSummaryDto: {
             repoCount: number;
@@ -2460,8 +2555,8 @@ export interface components {
             status: "queued" | "generating" | "pr-created" | "merged" | "failed";
             prUrl?: string;
             prNumber?: number;
-            /** @description Machine-readable failure code when status is `failed`. Values in `FixRetryableErrorCode` may be re-queued via POST .../readiness/fixes/{fixId}/retry. */
-            errorCode?: components["schemas"]["FixRetryableErrorCode"] | string;
+            /** @description Machine-readable failure code when status is `failed`. Values in `FixRetryableErrorCode` may be re-queued via POST .../readiness/fixes/{fixId}/retry. Values in `FixNonRetryableErrorCode` are permanent failures that require human intervention or configuration changes before retrying. */
+            errorCode?: components["schemas"]["FixRetryableErrorCode"] | components["schemas"]["FixNonRetryableErrorCode"] | string;
             /** @description Human-readable failure summary. Present when status is failed. */
             errorMessage?: string | null;
             /** @description Structured failure context for UI rendering (e.g. file path, provider status). Never contains secrets. */
@@ -2476,6 +2571,11 @@ export interface components {
          * @enum {string}
          */
         FixRetryableErrorCode: "PROVIDER_TIMEOUT" | "RATE_LIMITED" | "TRANSIENT_NETWORK" | "RUNNER_INTERRUPTED";
+        /**
+         * @description Permanent failure codes that cannot be resolved by retrying the same fix. `POLICY_DENIED` — blocked by repo/dimension/path allowlist policy (admin must update `READINESS_FIX_*` env config). `CHANGE_LIMIT_EXCEEDED` — generated diff exceeded max files or lines guardrail. `BUILD_FAILED` — pre-PR gate command or GitHub check run failed on the fix branch. `MERGE_CONFLICT` — could not apply the generated fix cleanly to the target branch. `AUTH_REVOKED` — GitHub installation token or Cursor API key is missing or revoked. `UNSUPPORTED_DIMENSION` — no skill is implemented for this readiness dimension. `DUPLICATE_ACTIVE` — another fix is already in progress for the same issue. `processor_error` — unexpected processor-level failure; check batch-runner logs.
+         * @enum {string}
+         */
+        FixNonRetryableErrorCode: "POLICY_DENIED" | "CHANGE_LIMIT_EXCEEDED" | "BUILD_FAILED" | "MERGE_CONFLICT" | "AUTH_REVOKED" | "UNSUPPORTED_DIMENSION" | "DUPLICATE_ACTIVE" | "processor_error";
         CreateFixRequestBodyDto: {
             /**
              * Format: uuid
@@ -2906,6 +3006,11 @@ export type ReadinessRunSummaryDto = components['schemas']['ReadinessRunSummaryD
 export type ReadinessCriteriaSummaryDto = components['schemas']['ReadinessCriteriaSummaryDto'];
 export type ReadinessIssueDto = components['schemas']['ReadinessIssueDto'];
 export type DimensionScoreDto = components['schemas']['DimensionScoreDto'];
+export type ReadinessRepoRunHistoryItemDto = components['schemas']['ReadinessRepoRunHistoryItemDto'];
+export type ReadinessRepoRunListDto = components['schemas']['ReadinessRepoRunListDto'];
+export type ReadinessScoreHistoryPointDto = components['schemas']['ReadinessScoreHistoryPointDto'];
+export type ReadinessRepoScoreHistoryDto = components['schemas']['ReadinessRepoScoreHistoryDto'];
+export type WorkspaceReadinessScoreHistoryDto = components['schemas']['WorkspaceReadinessScoreHistoryDto'];
 export type RepoReadinessScoreDto = components['schemas']['RepoReadinessScoreDto'];
 export type AgenticFoundationDashboardSummaryDto = components['schemas']['AgenticFoundationDashboardSummaryDto'];
 export type PageMetaDto = components['schemas']['PageMetaDto'];
@@ -2917,6 +3022,7 @@ export type GithubInstalledRepoListDto = components['schemas']['GithubInstalledR
 export type AgenticFoundationDashboardDto = components['schemas']['AgenticFoundationDashboardDto'];
 export type FixRequestDto = components['schemas']['FixRequestDto'];
 export type FixRetryableErrorCode = components['schemas']['FixRetryableErrorCode'];
+export type FixNonRetryableErrorCode = components['schemas']['FixNonRetryableErrorCode'];
 export type CreateFixRequestBodyDto = components['schemas']['CreateFixRequestBodyDto'];
 export type PhaseRoleDto = components['schemas']['PhaseRoleDto'];
 export type SquadMemberDto = components['schemas']['SquadMemberDto'];
@@ -5282,6 +5388,100 @@ export interface operations {
             };
         };
     };
+    listReadinessRepoRuns: {
+        parameters: {
+            query?: {
+                limit?: number;
+                order?: "asc" | "desc";
+                /** @description Opaque cursor from a prior response `nextCursor` field. */
+                cursor?: string;
+            };
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+                repoId: components["parameters"]["RepoId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Run history page */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReadinessRepoRunListDto"];
+                };
+            };
+            /** @description Invalid pagination query */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Workspace or repository not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    getReadinessScoreHistory: {
+        parameters: {
+            query?: {
+                /** @description ISO-8601 lower bound on `finishedAt` (inclusive). */
+                since?: string;
+                limitPerRepo?: number;
+            };
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Score history grouped by repository */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkspaceReadinessScoreHistoryDto"];
+                };
+            };
+            /** @description Invalid query */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Workspace does not exist */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     getAgenticFoundationDashboard: {
         parameters: {
             query?: never;