@thinkai/tai-api-contract 2.180.0 → 2.182.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.180.0
+  version: 2.182.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -419,6 +419,235 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /admin/workspaces/{workspaceId}/assessment-preflight:
+    post:
+      tags: [PlatformAdmin]
+      summary: Evaluate assessment preflight from server-loaded evidence
+      operationId: runLiveAssessmentPreflight
+      description: >
+        Loads repository scope, readiness scan age, and window coverage for one
+        workspace. Client fields for scope, scans, windows, and engineer counts
+        are ignored, so an unscanned source cannot be marked fresh. The
+        five-business-day clock uses Monday–Friday in America/New_York and is
+        stored on the first passing result. A later blocker does not clear it.
+        Active-engineer counts stay unloaded until stored activity can be counted.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - offerId
+                - sourceControl
+                - platformExecutionReady
+                - premiumAi
+                - jiraSelected
+                - incidentSelected
+                - incidentAvailable
+              properties:
+                offerId:
+                  type: string
+                  enum: [engineering_readiness_baseline, agentic_ai_roi]
+                sourceControl:
+                  type: string
+                  enum: [connected, pending_approval, setup_in_progress, revoked, stale, missing]
+                platformExecutionReady:
+                  type: boolean
+                premiumAi:
+                  type: object
+                  required: [cursor, claude, copilot]
+                  properties:
+                    cursor:
+                      type: boolean
+                    claude:
+                      type: boolean
+                    copilot:
+                      type: boolean
+                jiraSelected:
+                  type: boolean
+                incidentSelected:
+                  type: boolean
+                incidentAvailable:
+                  type: boolean
+                owner:
+                  type: string
+                  nullable: true
+      responses:
+        "200":
+          description: >
+            Preflight result. `dueDate` is set once the clock has started and stays
+            set if a later check is blocked.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  [ready, clockStarted, dueDate, owner, blocker, nextAction, failures, chapters]
+                properties:
+                  ready:
+                    type: boolean
+                  clockStarted:
+                    type: boolean
+                  dueDate:
+                    type: string
+                    nullable: true
+                    format: date
+                  owner:
+                    type: string
+                    nullable: true
+                  blocker:
+                    type: string
+                    nullable: true
+                  nextAction:
+                    type: object
+                    nullable: true
+                    required: [label, href]
+                    properties:
+                      label:
+                        type: string
+                      href:
+                        type: string
+                        nullable: true
+                  failures:
+                    type: array
+                    items:
+                      type: object
+                      required: [code, blocker, nextAction]
+                      properties:
+                        code:
+                          type: string
+                        blocker:
+                          type: string
+                        nextAction:
+                          type: object
+                          required: [label, href]
+                          properties:
+                            label:
+                              type: string
+                            href:
+                              type: string
+                              nullable: true
+                  chapters:
+                    type: array
+                    items:
+                      type: object
+                      required: [id, status, reason]
+                      properties:
+                        id:
+                          type: string
+                          enum: [jira, incidents]
+                        status:
+                          type: string
+                          enum: [unavailable]
+                        reason:
+                          type: string
+        "400":
+          description: Body or workspace id failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: offerId is not a known assessment offer
+                code: invalid_body
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "503":
+          description: Evidence store is unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /admin/assessment-queue:
+    get:
+      tags: [PlatformAdmin]
+      summary: List operator assessment records
+      operationId: listAssessmentQueue
+      description: >
+        Returns the stored assessment record for each workspace an operator has
+        evaluated. The next blocker is on this list. A second workspace is not
+        required.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      responses:
+        "200":
+          description: Operator queue.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [records]
+                properties:
+                  records:
+                    type: array
+                    items:
+                      type: object
+                      required:
+                        [workspaceId, offerId, ready, blocker, nextAction, dueDate, evaluatedAt]
+                      properties:
+                        workspaceId:
+                          type: string
+                          format: uuid
+                        offerId:
+                          type: string
+                          enum: [engineering_readiness_baseline, agentic_ai_roi]
+                        ready:
+                          type: boolean
+                        blocker:
+                          type: string
+                          nullable: true
+                        nextAction:
+                          type: object
+                          nullable: true
+                          required: [label, href]
+                          properties:
+                            label:
+                              type: string
+                            href:
+                              type: string
+                              nullable: true
+                        dueDate:
+                          type: string
+                          nullable: true
+                          format: date
+                        evaluatedAt:
+                          type: string
+                          format: date-time
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+
   /admin/assessment-manifest-validation:
     post:
       tags: [PlatformAdmin]
@@ -8925,7 +9154,10 @@ paths:
       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.
+        as `attachmentIds` on the next POST message. Max 5 MB per file (JSON bodyLimit is
+        raised for `contentBase64`). When unbound uploads already sit at the per-message
+        file cap (e.g. after an aborted send), the oldest unbound rows are pruned so a new
+        attach can proceed.
       operationId: postCodeChatAttachment
       x-test-coverage-skip: thin HTTP over validateAttachment + store insert
       parameters:
@@ -8944,7 +9176,11 @@ paths:
               schema:
                 $ref: "#/components/schemas/CodeChatAttachmentMetaDto"
         "400":
-          description: Validation failed (size, type, totals)
+          description: >
+            Validation failed after decode (size, type, totals). Stable codes include
+            `attachment_too_large`, `attachment_total_too_large`, `attachment_too_many`,
+            `attachment_type_unsupported`, `attachment_pdf_too_long`, `attachment_failed`,
+            `invalid_input`.
           content:
             application/json:
               schema:
@@ -8963,6 +9199,19 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "413":
+          description: >
+            Fastify rejected the JSON body before the handler (`request_body_too_large`).
+            Typical when `contentBase64` exceeds the route bodyLimit (aligned with the
+            5 MB per-file cap after base64 expansion). Decoded-size overruns still return
+            `400` `attachment_too_large`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Request body is too large.
+                code: request_body_too_large
         "422":
           description: Could not process the file
           content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.180.0",
+  "version": "2.182.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
   "devDependencies": {
     "@stoplight/spectral-cli": "^6.17.0",
     "@types/node": "^26.6.5",
-    "jsonpath-plus": "^11.1.1",
+    "jsonpath-plus": "^11.2.1",
     "openapi-typescript": "^7.13.0",
     "typescript": "~6.0.3"
   },

package/src/generated/openapi.ts

@@ -67,6 +67,48 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/admin/workspaces/{workspaceId}/assessment-preflight": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Evaluate assessment preflight from server-loaded evidence
+         * @description Loads repository scope, readiness scan age, and window coverage for one workspace. Client fields for scope, scans, windows, and engineer counts are ignored, so an unscanned source cannot be marked fresh. The five-business-day clock uses Monday–Friday in America/New_York and is stored on the first passing result. A later blocker does not clear it. Active-engineer counts stay unloaded until stored activity can be counted.
+         *     **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+         */
+        post: operations["runLiveAssessmentPreflight"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/admin/assessment-queue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List operator assessment records
+         * @description Returns the stored assessment record for each workspace an operator has evaluated. The next blocker is on this list. A second workspace is not required.
+         *     **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+         */
+        get: operations["listAssessmentQueue"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/admin/assessment-manifest-validation": {
         parameters: {
             query?: never;
@@ -3301,7 +3343,7 @@ export interface paths {
         put?: never;
         /**
          * 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.
+         * @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 (JSON bodyLimit is raised for `contentBase64`). When unbound uploads already sit at the per-message file cap (e.g. after an aborted send), the oldest unbound rows are pruned so a new attach can proceed.
          */
         post: operations["postCodeChatAttachment"];
         delete?: never;
@@ -12735,6 +12777,182 @@ export interface operations {
             };
         };
     };
+    runLiveAssessmentPreflight: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @enum {string} */
+                    offerId: "engineering_readiness_baseline" | "agentic_ai_roi";
+                    /** @enum {string} */
+                    sourceControl: "connected" | "pending_approval" | "setup_in_progress" | "revoked" | "stale" | "missing";
+                    platformExecutionReady: boolean;
+                    premiumAi: {
+                        cursor: boolean;
+                        claude: boolean;
+                        copilot: boolean;
+                    };
+                    jiraSelected: boolean;
+                    incidentSelected: boolean;
+                    incidentAvailable: boolean;
+                    owner?: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Preflight result. `dueDate` is set once the clock has started and stays set if a later check is blocked. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        ready: boolean;
+                        clockStarted: boolean;
+                        /** Format: date */
+                        dueDate: string | null;
+                        owner: string | null;
+                        blocker: string | null;
+                        nextAction: {
+                            label: string;
+                            href: string | null;
+                        } | null;
+                        failures: {
+                            code: string;
+                            blocker: string;
+                            nextAction: {
+                                label: string;
+                                href: string | null;
+                            };
+                        }[];
+                        chapters: {
+                            /** @enum {string} */
+                            id: "jira" | "incidents";
+                            /** @enum {string} */
+                            status: "unavailable";
+                            reason: string;
+                        }[];
+                    };
+                };
+            };
+            /** @description Body or workspace id failed validation. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "offerId is not a known assessment offer",
+                     *       "code": "invalid_body"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Missing or invalid JWT. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Caller is not a platform admin. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Forbidden",
+                     *       "code": "forbidden"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Evidence store is unavailable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    listAssessmentQueue: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Operator queue. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        records: {
+                            /** Format: uuid */
+                            workspaceId: string;
+                            /** @enum {string} */
+                            offerId: "engineering_readiness_baseline" | "agentic_ai_roi";
+                            ready: boolean;
+                            blocker: string | null;
+                            nextAction: {
+                                label: string;
+                                href: string | null;
+                            } | null;
+                            /** Format: date */
+                            dueDate: string | null;
+                            /** Format: date-time */
+                            evaluatedAt: string;
+                        }[];
+                    };
+                };
+            };
+            /** @description Missing or invalid JWT. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Caller is not a platform admin. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Forbidden",
+                     *       "code": "forbidden"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     runAssessmentManifestValidation: {
         parameters: {
             query?: never;
@@ -21362,7 +21580,7 @@ export interface operations {
                     "application/json": components["schemas"]["CodeChatAttachmentMetaDto"];
                 };
             };
-            /** @description Validation failed (size, type, totals) */
+            /** @description Validation failed after decode (size, type, totals). Stable codes include `attachment_too_large`, `attachment_total_too_large`, `attachment_too_many`, `attachment_type_unsupported`, `attachment_pdf_too_long`, `attachment_failed`, `invalid_input`. */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -21390,6 +21608,21 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorMessageDto"];
                 };
             };
+            /** @description Fastify rejected the JSON body before the handler (`request_body_too_large`). Typical when `contentBase64` exceeds the route bodyLimit (aligned with the 5 MB per-file cap after base64 expansion). Decoded-size overruns still return `400` `attachment_too_large`. */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Request body is too large.",
+                     *       "code": "request_body_too_large"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
             /** @description Could not process the file */
             422: {
                 headers: {