@thinkai/tai-api-contract 2.185.0 → 2.187.0

package/src/generated/openapi.ts

@@ -222,6 +222,79 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/admin/automation-cost/summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Estimated Agent automation spend by workspace and operation
+         * @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`.
+         */
+        get: operations["adminGetAutomationCostSummary"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/admin/workspaces/{workspaceId}/automation-cost/budget": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get automation-cost budget and month status for a workspace
+         * @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`.
+         */
+        get: operations["adminGetAutomationCostBudget"];
+        /**
+         * Upsert automation-cost budget for one operation
+         * @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`.
+         */
+        put: operations["adminPutAutomationCostBudget"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/admin/workspaces/{workspaceId}/automation-cost/pause": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pause Agent automation for selected operations
+         * @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`.
+         */
+        post: operations["adminPostAutomationCostPause"];
+        /**
+         * Clear automation-cost pause for a workspace
+         * @description Clears `automation_cost_pause` for the workspace so workers may resume when under hard cap.
+         *     **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+         */
+        delete: operations["adminDeleteAutomationCostPause"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/privacy-requests": {
         parameters: {
             query?: never;
@@ -6883,13 +6956,52 @@ export interface components {
             generatedAt: string;
             contributors: components["schemas"]["AiUsageSpendAggregatedContributorRowDto"][];
         };
+        /** @description Numeric evidence for `id=model_right_sizing` (Cost-to-Value insight #2). Premium share is `premiumSpendCents / totalModelSpendCents` against `thresholdPct` (Phase A default 40). */
+        AiUsageSpendKeyInsightModelRightSizingEvidenceDto: {
+            /** @description Premium-model share of model spend in the window (0–100). */
+            premiumSharePct: number;
+            /** @description Sum of spend_cents on premium-classified models (cents). */
+            premiumSpendCents: number;
+            /** @description Sum of spend_cents across all models in the window (cents). */
+            totalModelSpendCents: number;
+            /** @description Effective premium-share threshold used for this card (0–100). */
+            thresholdPct: number;
+            /** @description Distinct mapped person_id rows contributing to this card's sample (workspace rollup or the single person for a person-scoped card). */
+            personCount: number;
+        };
+        /** @description Optional member drill-down for person-scoped `model_right_sizing` cards. Links to `GET …/integrations/ai-tool/{provider}/members/{externalId}`. */
+        AiUsageSpendKeyInsightDrilldownDto: {
+            /**
+             * @description AI tool provider for the member detail route.
+             * @enum {string}
+             */
+            provider: "cursor" | "claude";
+            /** @description Provider member external id for the member detail route. */
+            externalId: string;
+        };
+        /** @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). */
         AiUsageSpendKeyInsightItemDto: {
-            /** @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). */
             id: string;
             /** @enum {string} */
             tone: "positive" | "warning" | "neutral";
             /** @description Human-readable insight sentence for the UI panel. */
             text: string;
+            /** @description Required when `id=model_right_sizing`. Phase A/B always `estimated` (model-mix heuristic; no task-complexity telemetry until Phase 3). */
+            dataQuality?: components["schemas"]["AiAssistedCodeDataQuality"];
+            /** @description Required when `id=model_right_sizing`. Fixed honesty string that the model mix is heuristic and does not encode task complexity. */
+            limitation?: string;
+            /** @description Required when `id=model_right_sizing`. Coaching copy for the card CTA (advisory only; not vendor enforcement). */
+            recommendedAction?: string;
+            /** @description Required when `id=model_right_sizing`. */
+            evidence?: components["schemas"]["AiUsageSpendKeyInsightModelRightSizingEvidenceDto"];
+            /**
+             * @description Optional scope for `model_right_sizing` cards. Workspace default vs per-person personalized item.
+             * @enum {string}
+             */
+            scope?: "workspace" | "person";
+            /** @description Optional when `scope=person` for `model_right_sizing`; omitted on workspace cards. */
+            drilldown?: components["schemas"]["AiUsageSpendKeyInsightDrilldownDto"];
         };
         AiUsageSpendKeyInsightsDto: {
             /** Format: uuid */
@@ -10541,6 +10653,83 @@ export interface components {
         ActivityLogPageDto: components["schemas"]["PageMetaDto"] & {
             items: components["schemas"]["ActivityLogEntryDto"][];
         };
+        /**
+         * @description Platform Agent job type in the readiness token ledger.
+         * @enum {string}
+         */
+        AutomationCostOperationDto: "readiness_analysis" | "readiness_fix";
+        AutomationCostSummaryRowDto: {
+            /** Format: uuid */
+            workspaceId: string;
+            operation: components["schemas"]["AutomationCostOperationDto"];
+            /** Format: int64 */
+            inputTokens: number;
+            /** Format: int64 */
+            outputTokens: number;
+            /** Format: int64 */
+            cacheReadTokens: number;
+            /** Format: int64 */
+            cacheWriteTokens: number;
+            /** @description Ops estimate from token totals × runtime-config pricing (integer cents). */
+            estimatedSpendCents: number;
+            invocationCount: number;
+        };
+        AutomationCostSummaryTotalsDto: {
+            /** Format: int64 */
+            inputTokens: number;
+            /** Format: int64 */
+            outputTokens: number;
+            /** Format: int64 */
+            cacheReadTokens: number;
+            /** Format: int64 */
+            cacheWriteTokens: number;
+            estimatedSpendCents: number;
+            invocationCount: number;
+        };
+        AutomationCostSummaryDto: {
+            rows: components["schemas"]["AutomationCostSummaryRowDto"][];
+            totals: components["schemas"]["AutomationCostSummaryTotalsDto"];
+        };
+        /** @enum {string} */
+        AutomationCostBudgetStatusDto: "ok" | "warn" | "hard_stopped" | "paused";
+        AutomationCostBudgetViewDto: {
+            operation: components["schemas"]["AutomationCostOperationDto"];
+            /** @description Null when no budget is configured (unlimited). */
+            monthlyBudgetCents: number | null;
+            warnThresholdPct: number;
+            hardEnabled: boolean;
+            /** @description Estimated spend for this operation in the current UTC calendar month. */
+            monthSpendCents: number;
+            status: components["schemas"]["AutomationCostBudgetStatusDto"];
+            paused: boolean;
+            pauseReason?: string | null;
+        };
+        AutomationCostBudgetListDto: {
+            budgets: components["schemas"]["AutomationCostBudgetViewDto"][];
+        };
+        AutomationCostBudgetUpsertDto: {
+            operation: components["schemas"]["AutomationCostOperationDto"];
+            monthlyBudgetCents: number;
+            /** @default 80 */
+            warnThresholdPct: number;
+            /** @default false */
+            hardEnabled: boolean;
+        };
+        AutomationCostPauseBodyDto: {
+            operations: components["schemas"]["AutomationCostOperationDto"][];
+            reason: string;
+        };
+        AutomationCostPauseStateDto: {
+            operations: components["schemas"]["AutomationCostOperationDto"][];
+            reason: string;
+            /** Format: date-time */
+            pausedAt: string;
+            /** @description Platform admin email that set the pause, when known. */
+            pausedBy?: string | null;
+        };
+        AutomationCostPauseResponseDto: {
+            pause: components["schemas"]["AutomationCostPauseStateDto"];
+        };
         ReadinessTokenUsageRowDto: {
             /**
              * Format: uuid
@@ -12751,6 +12940,8 @@ export type AiUsageSpendAggregatedTeamsDto = components['schemas']['AiUsageSpend
 export type AiUsageSpendAggregatedContributorRowDto = components['schemas']['AiUsageSpendAggregatedContributorRowDto'];
 export type AiUsageSpendAggregatedContributorsDto = components['schemas']['AiUsageSpendAggregatedContributorsDto'];
 export type AiUsageSpendContributorToolHeatmapDto = components['schemas']['AiUsageSpendContributorToolHeatmapDto'];
+export type AiUsageSpendKeyInsightModelRightSizingEvidenceDto = components['schemas']['AiUsageSpendKeyInsightModelRightSizingEvidenceDto'];
+export type AiUsageSpendKeyInsightDrilldownDto = components['schemas']['AiUsageSpendKeyInsightDrilldownDto'];
 export type AiUsageSpendKeyInsightItemDto = components['schemas']['AiUsageSpendKeyInsightItemDto'];
 export type AiUsageSpendKeyInsightsDto = components['schemas']['AiUsageSpendKeyInsightsDto'];
 export type AiAssistedCodeDataQuality = components['schemas']['AiAssistedCodeDataQuality'];
@@ -13074,6 +13265,17 @@ export type ZenHrBranchSelectionResultDto = components['schemas']['ZenHrBranchSe
 export type HrisTriggerSyncResultDto = components['schemas']['HrisTriggerSyncResultDto'];
 export type HrisProviderSyncResultDto = components['schemas']['HrisProviderSyncResultDto'];
 export type ActivityLogPageDto = components['schemas']['ActivityLogPageDto'];
+export type AutomationCostOperationDto = components['schemas']['AutomationCostOperationDto'];
+export type AutomationCostSummaryRowDto = components['schemas']['AutomationCostSummaryRowDto'];
+export type AutomationCostSummaryTotalsDto = components['schemas']['AutomationCostSummaryTotalsDto'];
+export type AutomationCostSummaryDto = components['schemas']['AutomationCostSummaryDto'];
+export type AutomationCostBudgetStatusDto = components['schemas']['AutomationCostBudgetStatusDto'];
+export type AutomationCostBudgetViewDto = components['schemas']['AutomationCostBudgetViewDto'];
+export type AutomationCostBudgetListDto = components['schemas']['AutomationCostBudgetListDto'];
+export type AutomationCostBudgetUpsertDto = components['schemas']['AutomationCostBudgetUpsertDto'];
+export type AutomationCostPauseBodyDto = components['schemas']['AutomationCostPauseBodyDto'];
+export type AutomationCostPauseStateDto = components['schemas']['AutomationCostPauseStateDto'];
+export type AutomationCostPauseResponseDto = components['schemas']['AutomationCostPauseResponseDto'];
 export type ReadinessTokenUsageRowDto = components['schemas']['ReadinessTokenUsageRowDto'];
 export type ReadinessTokenUsageByDimensionRowDto = components['schemas']['ReadinessTokenUsageByDimensionRowDto'];
 export type SdlcModuleId = components['schemas']['SdlcModuleId'];
@@ -14107,6 +14309,328 @@ export interface operations {
             };
         };
     };
+    adminGetAutomationCostSummary: {
+        parameters: {
+            query?: {
+                /** @description Filter by workspace UUID. */
+                workspaceId?: string;
+                /** @description Inclusive start (ISO-8601). Defaults to start of current UTC month. */
+                from?: string;
+                /** @description Inclusive end (ISO-8601). Defaults to end of current UTC month. */
+                to?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Summary rows and portfolio totals (empty rows / zero totals when no usage). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AutomationCostSummaryDto"];
+                };
+            };
+            /** @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"];
+                };
+            };
+        };
+    };
+    adminGetAutomationCostBudget: {
+        parameters: {
+            query?: {
+                /** @description Limit to one operation; omit for both. */
+                operation?: "readiness_analysis" | "readiness_fix";
+            };
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Budget views for the requested operations. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AutomationCostBudgetListDto"];
+                };
+            };
+            /** @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 Workspace not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Workspace not found",
+                     *       "code": "workspace_not_found"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    adminPutAutomationCostBudget: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AutomationCostBudgetUpsertDto"];
+            };
+        };
+        responses: {
+            /** @description Updated budget view(s). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AutomationCostBudgetListDto"];
+                };
+            };
+            /** @description Invalid body. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "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 Workspace not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Workspace not found",
+                     *       "code": "workspace_not_found"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    adminPostAutomationCostPause: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AutomationCostPauseBodyDto"];
+            };
+        };
+        responses: {
+            /** @description Pause state stored. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AutomationCostPauseResponseDto"];
+                };
+            };
+            /** @description Empty or invalid operations list. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "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 Workspace not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Workspace not found",
+                     *       "code": "workspace_not_found"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    adminDeleteAutomationCostPause: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Pause cleared. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @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 Workspace not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Workspace not found",
+                     *       "code": "workspace_not_found"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     submitPublicPrivacyRequest: {
         parameters: {
             query?: never;

package/src/index.ts

@@ -884,11 +884,45 @@ export interface AiUsageSpendContributorToolHeatmapDto {
   contributors: AiUsageSpendAggregatedContributorRowDto[];
 }
 
-/** One card in the AI usage & spend key insights panel. */
+/**
+ * Numeric evidence for `id=model_right_sizing` (Cost-to-Value insight #2).
+ * Premium share is premiumSpendCents / totalModelSpendCents against thresholdPct.
+ */
+export interface AiUsageSpendKeyInsightModelRightSizingEvidenceDto {
+  premiumSharePct: number;
+  premiumSpendCents: number;
+  totalModelSpendCents: number;
+  thresholdPct: number;
+  personCount: number;
+}
+
+/** Optional member drill-down for person-scoped model_right_sizing cards. */
+export interface AiUsageSpendKeyInsightDrilldownDto {
+  provider: "cursor" | "claude";
+  externalId: string;
+}
+
+/**
+ * One card in the AI usage & spend key insights panel.
+ * When `id` is `model_right_sizing`, `dataQuality`, `limitation`,
+ * `recommendedAction`, and `evidence` are required; `scope` / `drilldown` optional.
+ */
 export interface AiUsageSpendKeyInsightItemDto {
   id: string;
   tone: "positive" | "warning" | "neutral";
   text: string;
+  /** Required when id=model_right_sizing; Phase A/B always `estimated`. */
+  dataQuality?: AiAssistedCodeDataQuality;
+  /** Required when id=model_right_sizing; heuristic honesty string. */
+  limitation?: string;
+  /** Required when id=model_right_sizing; advisory coaching CTA copy. */
+  recommendedAction?: string;
+  /** Required when id=model_right_sizing. */
+  evidence?: AiUsageSpendKeyInsightModelRightSizingEvidenceDto;
+  /** Optional scope for model_right_sizing (workspace default vs person). */
+  scope?: "workspace" | "person";
+  /** Optional person drill-down when scope=person. */
+  drilldown?: AiUsageSpendKeyInsightDrilldownDto;
 }
 
 /** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/key-insights */