@thinkai/tai-api-contract 2.185.0 → 2.186.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.185.0
+  version: 2.186.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]
@@ -25400,6 +25663,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.186.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",