@thinkai/tai-api-contract 2.185.0 → 2.187.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.185.0
+  version: 2.187.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1069,6 +1069,269 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /admin/automation-cost/summary:
+    get:
+      tags: [PlatformAdmin]
+      summary: Estimated Agent automation spend by workspace and operation
+      operationId: adminGetAutomationCostSummary
+      description: >
+        Rolls up `tai_readiness_token_usage` for the given UTC range (defaults to the current
+        UTC calendar month when `from`/`to` are omitted). Each row is one
+        `(workspaceId, operation)` with token totals, invocation count, and
+        `estimatedSpendCents` from `workers.automationCost.pricing` (Cursor Auto pool list-rate
+        defaults when keys are missing). Portfolio `totals` are sums of the returned rows.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+        Separate from customer Insights AI Usage & Spend / `ai_cost_budget`.
+      parameters:
+        - name: workspaceId
+          in: query
+          required: false
+          schema:
+            type: string
+            format: uuid
+          description: Filter by workspace UUID.
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: Inclusive start (ISO-8601). Defaults to start of current UTC month.
+        - name: to
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: Inclusive end (ISO-8601). Defaults to end of current UTC month.
+      responses:
+        "200":
+          description: Summary rows and portfolio totals (empty rows / zero totals when no usage).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostSummaryDto"
+        "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/workspaces/{workspaceId}/automation-cost/budget:
+    get:
+      tags: [PlatformAdmin]
+      summary: Get automation-cost budget and month status for a workspace
+      operationId: adminGetAutomationCostBudget
+      description: >
+        Returns budget rows for `readiness_analysis` and/or `readiness_fix` with
+        `monthSpendCents` (estimated from token rows in the current UTC month) and
+        `status` (`ok` | `warn` | `hard_stopped` | `paused`). When no budget is configured,
+        `monthlyBudgetCents` is null and status is `ok` (unlimited) unless paused.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: operation
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [readiness_analysis, readiness_fix]
+          description: Limit to one operation; omit for both.
+      responses:
+        "200":
+          description: Budget views for the requested operations.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostBudgetListDto"
+        "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
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+    put:
+      tags: [PlatformAdmin]
+      summary: Upsert automation-cost budget for one operation
+      operationId: adminPutAutomationCostBudget
+      description: >
+        Upserts `{ operation, monthlyBudgetCents, warnThresholdPct, hardEnabled }` into
+        workspace `automation_cost_budget` (not `ai_cost_budget`). Default `warnThresholdPct`
+        is 80. `monthlyBudgetCents: 0` with `hardEnabled: true` is an immediate hard stop.
+        Returns the refreshed budget view for that operation.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AutomationCostBudgetUpsertDto"
+      responses:
+        "200":
+          description: Updated budget view(s).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostBudgetListDto"
+        "400":
+          description: Invalid body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "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
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+
+  /admin/workspaces/{workspaceId}/automation-cost/pause:
+    post:
+      tags: [PlatformAdmin]
+      summary: Pause Agent automation for selected operations
+      operationId: adminPostAutomationCostPause
+      description: >
+        Sets a per-workspace pause kill-switch for the listed operations. Workers honor pause
+        the same as a hard budget stop (enforcement is a follow-up slice). Empty `operations`
+        → `400`.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AutomationCostPauseBodyDto"
+      responses:
+        "200":
+          description: Pause state stored.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostPauseResponseDto"
+        "400":
+          description: Empty or invalid operations list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "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
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+    delete:
+      tags: [PlatformAdmin]
+      summary: Clear automation-cost pause for a workspace
+      operationId: adminDeleteAutomationCostPause
+      description: >
+        Clears `automation_cost_pause` for the workspace so workers may resume when under hard
+        cap.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: Pause cleared.
+        "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
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+
   /privacy-requests:
     post:
       tags: [PrivacyRequests]
@@ -17165,20 +17428,107 @@ components:
           items:
             $ref: "#/components/schemas/AiUsageSpendAggregatedContributorRowDto"
 
+    AiUsageSpendKeyInsightModelRightSizingEvidenceDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Numeric evidence for `id=model_right_sizing` (Cost-to-Value insight #2).
+        Premium share is `premiumSpendCents / totalModelSpendCents` against
+        `thresholdPct` (Phase A default 40).
+      required:
+        - premiumSharePct
+        - premiumSpendCents
+        - totalModelSpendCents
+        - thresholdPct
+        - personCount
+      properties:
+        premiumSharePct:
+          type: number
+          description: Premium-model share of model spend in the window (0–100).
+        premiumSpendCents:
+          type: integer
+          description: Sum of spend_cents on premium-classified models (cents).
+        totalModelSpendCents:
+          type: integer
+          description: Sum of spend_cents across all models in the window (cents).
+        thresholdPct:
+          type: number
+          description: Effective premium-share threshold used for this card (0–100).
+        personCount:
+          type: integer
+          description: >
+            Distinct mapped person_id rows contributing to this card's sample
+            (workspace rollup or the single person for a person-scoped card).
+
+    AiUsageSpendKeyInsightDrilldownDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Optional member drill-down for person-scoped `model_right_sizing` cards.
+        Links to `GET …/integrations/ai-tool/{provider}/members/{externalId}`.
+      required: [provider, externalId]
+      properties:
+        provider:
+          type: string
+          enum: [cursor, claude]
+          description: AI tool provider for the member detail route.
+        externalId:
+          type: string
+          description: Provider member external id for the member detail route.
+
     AiUsageSpendKeyInsightItemDto:
       type: object
       additionalProperties: false
       required: [id, tone, text]
+      description: >
+        One Key Insights panel card. Base fields (`id`, `tone`, `text`) apply to
+        all insights. When `id` is `model_right_sizing`, clients MUST treat
+        `dataQuality`, `limitation`, `recommendedAction`, and `evidence` as
+        required; `scope` and `drilldown` are optional (person cards may set both).
       properties:
         id:
           type: string
-          description: Stable insight key (e.g. spend-leader, spend-vs-output).
+          description: >
+            Stable insight key (e.g. spend-leader, spend-vs-output,
+            model_right_sizing).
         tone:
           type: string
           enum: [positive, warning, neutral]
         text:
           type: string
           description: Human-readable insight sentence for the UI panel.
+        dataQuality:
+          allOf:
+            - $ref: "#/components/schemas/AiAssistedCodeDataQuality"
+          description: >
+            Required when `id=model_right_sizing`. Phase A/B always `estimated`
+            (model-mix heuristic; no task-complexity telemetry until Phase 3).
+        limitation:
+          type: string
+          description: >
+            Required when `id=model_right_sizing`. Fixed honesty string that the
+            model mix is heuristic and does not encode task complexity.
+        recommendedAction:
+          type: string
+          description: >
+            Required when `id=model_right_sizing`. Coaching copy for the card CTA
+            (advisory only; not vendor enforcement).
+        evidence:
+          allOf:
+            - $ref: "#/components/schemas/AiUsageSpendKeyInsightModelRightSizingEvidenceDto"
+          description: Required when `id=model_right_sizing`.
+        scope:
+          type: string
+          enum: [workspace, person]
+          description: >
+            Optional scope for `model_right_sizing` cards. Workspace default vs
+            per-person personalized item.
+        drilldown:
+          allOf:
+            - $ref: "#/components/schemas/AiUsageSpendKeyInsightDrilldownDto"
+          description: >
+            Optional when `scope=person` for `model_right_sizing`; omitted on
+            workspace cards.
 
     AiUsageSpendKeyInsightsDto:
       type: object
@@ -25400,6 +25750,186 @@ components:
               items:
                 $ref: "#/components/schemas/ActivityLogEntryDto"
 
+    AutomationCostOperationDto:
+      type: string
+      enum: [readiness_analysis, readiness_fix]
+      description: Platform Agent job type in the readiness token ledger.
+
+    AutomationCostSummaryRowDto:
+      type: object
+      required:
+        - workspaceId
+        - operation
+        - inputTokens
+        - outputTokens
+        - cacheReadTokens
+        - cacheWriteTokens
+        - estimatedSpendCents
+        - invocationCount
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        inputTokens:
+          type: integer
+          format: int64
+        outputTokens:
+          type: integer
+          format: int64
+        cacheReadTokens:
+          type: integer
+          format: int64
+        cacheWriteTokens:
+          type: integer
+          format: int64
+        estimatedSpendCents:
+          type: integer
+          description: Ops estimate from token totals × runtime-config pricing (integer cents).
+        invocationCount:
+          type: integer
+
+    AutomationCostSummaryTotalsDto:
+      type: object
+      required:
+        - inputTokens
+        - outputTokens
+        - cacheReadTokens
+        - cacheWriteTokens
+        - estimatedSpendCents
+        - invocationCount
+      properties:
+        inputTokens:
+          type: integer
+          format: int64
+        outputTokens:
+          type: integer
+          format: int64
+        cacheReadTokens:
+          type: integer
+          format: int64
+        cacheWriteTokens:
+          type: integer
+          format: int64
+        estimatedSpendCents:
+          type: integer
+        invocationCount:
+          type: integer
+
+    AutomationCostSummaryDto:
+      type: object
+      required: [rows, totals]
+      properties:
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostSummaryRowDto"
+        totals:
+          $ref: "#/components/schemas/AutomationCostSummaryTotalsDto"
+
+    AutomationCostBudgetStatusDto:
+      type: string
+      enum: [ok, warn, hard_stopped, paused]
+
+    AutomationCostBudgetViewDto:
+      type: object
+      required:
+        - operation
+        - monthlyBudgetCents
+        - warnThresholdPct
+        - hardEnabled
+        - monthSpendCents
+        - status
+        - paused
+      properties:
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        monthlyBudgetCents:
+          type: integer
+          nullable: true
+          description: Null when no budget is configured (unlimited).
+        warnThresholdPct:
+          type: integer
+          minimum: 0
+          maximum: 100
+        hardEnabled:
+          type: boolean
+        monthSpendCents:
+          type: integer
+          description: Estimated spend for this operation in the current UTC calendar month.
+        status:
+          $ref: "#/components/schemas/AutomationCostBudgetStatusDto"
+        paused:
+          type: boolean
+        pauseReason:
+          type: string
+          nullable: true
+
+    AutomationCostBudgetListDto:
+      type: object
+      required: [budgets]
+      properties:
+        budgets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostBudgetViewDto"
+
+    AutomationCostBudgetUpsertDto:
+      type: object
+      required: [operation, monthlyBudgetCents]
+      properties:
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        monthlyBudgetCents:
+          type: integer
+          minimum: 0
+        warnThresholdPct:
+          type: integer
+          minimum: 0
+          maximum: 100
+          default: 80
+        hardEnabled:
+          type: boolean
+          default: false
+
+    AutomationCostPauseBodyDto:
+      type: object
+      required: [operations, reason]
+      properties:
+        operations:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/AutomationCostOperationDto"
+        reason:
+          type: string
+
+    AutomationCostPauseStateDto:
+      type: object
+      required: [operations, reason, pausedAt]
+      properties:
+        operations:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostOperationDto"
+        reason:
+          type: string
+        pausedAt:
+          type: string
+          format: date-time
+        pausedBy:
+          type: string
+          nullable: true
+          description: Platform admin email that set the pause, when known.
+
+    AutomationCostPauseResponseDto:
+      type: object
+      required: [pause]
+      properties:
+        pause:
+          $ref: "#/components/schemas/AutomationCostPauseStateDto"
+
     ReadinessTokenUsageRowDto:
       type: object
       required:

package/package.json

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