@shardflux/sdk 0.9.0 → 0.10.0

package/dist/generated/app-api.d.ts

@@ -1536,6 +1536,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/suspend-when-idle": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Suspend the workspace if it stays idle for after_seconds from now (e.g. at the end of an agent turn)
+         * @description Records a deferred suspend for the cell’s idle loop: once the workspace has been idle for after_seconds (30..3600), it is suspended (within a few seconds of activity flush grace), at `not_before` (= now + after_seconds) at the earliest. A tool call after the request (the next turn) or a resume cancels it for good. Other work only defers it: a command still running, an attached exec/PTY stream or a keepalive postpones the suspend until after_seconds after it ends. It applies under every idle policy (`never` included) and only ever shortens the policy’s wait; a policy that suspends sooner still does. Repeating replaces the pending request (the new `requested_at` counts); DELETE cancels it; `idle.suspend_request` on the workspace shows it. 202 {workspace, operation: null, suspend_request}; when a suspend is already in progress, 202 {workspace, operation: that suspend, suspend_request: null} and nothing is recorded. The suspend, when it happens, is a system `suspend` operation with input.reason requested_after_idle (input.requested_at, input.after_seconds). Errors: 409 session_lifetime, workspace_deleted, operation_in_progress (another lifecycle operation is active), not_running, not_supported_for_mode (file-first, contracts §29). Supports Idempotency-Key.
+         */
+        post: operations["postV1WorkspacesWorkspaceIdSuspendWhenIdle"];
+        /**
+         * Cancel a pending suspend-when-idle request
+         * @description Idempotent: 200 with the workspace whether or not a request was pending, in any workspace state (idle.suspend_request is null afterwards). A suspend the request already started is not undone: it shows as the workspace’s active_operation; resume or open the workspace instead.
+         */
+        delete: operations["deleteV1WorkspacesWorkspaceIdSuspendWhenIdle"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/fork": {
         parameters: {
             query?: never;
@@ -1888,6 +1912,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/workspaces/{workspace_id}/suspend-when-idle": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Suspend the workspace if it stays idle for after_seconds from now (e.g. at the end of an agent turn)
+         * @description Records a deferred suspend for the cell’s idle loop: once the workspace has been idle for after_seconds (30..3600), it is suspended (within a few seconds of activity flush grace), at `not_before` (= now + after_seconds) at the earliest. A tool call after the request (the next turn) or a resume cancels it for good. Other work only defers it: a command still running, an attached exec/PTY stream or a keepalive postpones the suspend until after_seconds after it ends. It applies under every idle policy (`never` included) and only ever shortens the policy’s wait; a policy that suspends sooner still does. Repeating replaces the pending request (the new `requested_at` counts); DELETE cancels it; `idle.suspend_request` on the workspace shows it. 202 {workspace, operation: null, suspend_request}; when a suspend is already in progress, 202 {workspace, operation: that suspend, suspend_request: null} and nothing is recorded. The suspend, when it happens, is a system `suspend` operation with input.reason requested_after_idle (input.requested_at, input.after_seconds). Errors: 409 session_lifetime, workspace_deleted, operation_in_progress (another lifecycle operation is active), not_running, not_supported_for_mode (file-first, contracts §29). Supports Idempotency-Key.
+         */
+        post: operations["postApiV1WorkspacesWorkspaceIdSuspendWhenIdle"];
+        /**
+         * Cancel a pending suspend-when-idle request
+         * @description Idempotent: 200 with the workspace whether or not a request was pending, in any workspace state (idle.suspend_request is null afterwards). A suspend the request already started is not undone: it shows as the workspace’s active_operation; resume or open the workspace instead.
+         */
+        delete: operations["deleteApiV1WorkspacesWorkspaceIdSuspendWhenIdle"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/workspaces/{workspace_id}/fork": {
         parameters: {
             query?: never;
@@ -3971,7 +4019,7 @@ export interface paths {
         };
         /**
          * Current-period usage, included allowances and cap state of an organization
-         * @description Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted`.
+         * @description Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted` with `exhausted_reason` as details.reason. `spend_cap` is opt-in overage this period: while it is on, a CPU-hours or RAM GiB-hours allowance past `included` is in cap state `overage` (starts admitted, usage past it charged) until the spend cap is reached.
          */
         get: operations["getV1OrganizationsOrganizationIdUsageSummary"];
         put?: never;
@@ -4080,11 +4128,22 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Usage alert thresholds */
+        /**
+         * Usage alert thresholds and opt-in overage with its spend cap
+         * @description Alert thresholds, and whether overage is available, on, off or paused, with the spend cap, its bounds and the rates. Overage is off by default; owners and billing members change it with the PUT (the console on /api/v1, or a CLI session on /v1; project API keys are refused).
+         */
         get: operations["getV1OrganizationsOrganizationIdSpendPolicy"];
         /**
-         * Set usage alert thresholds (owner/billing)
-         * @description Thresholds are percentages of each allowance (1-100, at most 5). Overage cannot be enabled: this catalog has no metered prices.
+         * Set usage alert thresholds, turn overage on or off, set the spend cap (owner/billing)
+         * @description Every field is optional; send at least one. Thresholds are percentages of each allowance (1-100, at most 5).
+         *
+         *     Overage (off by default) needs a plan with opt-in overage and a spend cap: at least spend_cap_min_minor, at most the plan price (spend_cap_max_minor), and not below what overage already charged this period. Turning overage off is always allowed; what it charged stays on the next invoice.
+         *
+         *     The change takes effect at once: usage up to now is charged under the previous policy, the rest under the new one, and budget leases are re-sized in the same transaction (turning overage off or lowering the cap to the charges pauses running workspaces past the allowance). Every owner and billing member gets an email when overage is turned on or off or the cap changes.
+         *
+         *     If-Match (optional): the `version` you read; a different current version answers 409 conflict with details {reason: version_mismatch, current_version, if_match}.
+         *
+         *     422 validation_failed details {field, reason}: overage_unavailable, spend_cap_required, spend_cap_below_minimum (+ min_minor), spend_cap_above_plan_price (+ max_minor), spend_cap_below_charges (+ charges_minor).
          */
         put: operations["putV1OrganizationsOrganizationIdSpendPolicy"];
         post?: never;
@@ -4103,7 +4162,7 @@ export interface paths {
         };
         /**
          * Current-period usage, included allowances and cap state of an organization
-         * @description Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted`.
+         * @description Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted` with `exhausted_reason` as details.reason. `spend_cap` is opt-in overage this period: while it is on, a CPU-hours or RAM GiB-hours allowance past `included` is in cap state `overage` (starts admitted, usage past it charged) until the spend cap is reached.
          */
         get: operations["getApiV1OrganizationsOrganizationIdUsageSummary"];
         put?: never;
@@ -4212,11 +4271,22 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Usage alert thresholds */
+        /**
+         * Usage alert thresholds and opt-in overage with its spend cap
+         * @description Alert thresholds, and whether overage is available, on, off or paused, with the spend cap, its bounds and the rates. Overage is off by default; owners and billing members change it with the PUT (the console on /api/v1, or a CLI session on /v1; project API keys are refused).
+         */
         get: operations["getApiV1OrganizationsOrganizationIdSpendPolicy"];
         /**
-         * Set usage alert thresholds (owner/billing)
-         * @description Thresholds are percentages of each allowance (1-100, at most 5). Overage cannot be enabled: this catalog has no metered prices.
+         * Set usage alert thresholds, turn overage on or off, set the spend cap (owner/billing)
+         * @description Every field is optional; send at least one. Thresholds are percentages of each allowance (1-100, at most 5).
+         *
+         *     Overage (off by default) needs a plan with opt-in overage and a spend cap: at least spend_cap_min_minor, at most the plan price (spend_cap_max_minor), and not below what overage already charged this period. Turning overage off is always allowed; what it charged stays on the next invoice.
+         *
+         *     The change takes effect at once: usage up to now is charged under the previous policy, the rest under the new one, and budget leases are re-sized in the same transaction (turning overage off or lowering the cap to the charges pauses running workspaces past the allowance). Every owner and billing member gets an email when overage is turned on or off or the cap changes.
+         *
+         *     If-Match (optional): the `version` you read; a different current version answers 409 conflict with details {reason: version_mismatch, current_version, if_match}.
+         *
+         *     422 validation_failed details {field, reason}: overage_unavailable, spend_cap_required, spend_cap_below_minimum (+ min_minor), spend_cap_above_plan_price (+ max_minor), spend_cap_below_charges (+ charges_minor).
          */
         put: operations["putApiV1OrganizationsOrganizationIdSpendPolicy"];
         post?: never;
@@ -6424,6 +6494,20 @@ export interface components {
              */
             project_id?: string;
         };
+        /** @description A pending suspend-when-idle request (contracts §20.6): once the workspace has been idle for after_seconds, it is suspended. A tool call after requested_at (the next turn) or a resume cancels it; other work only defers it. */
+        SuspendRequest: {
+            /**
+             * Format: date-time
+             * @description When the request was made; a newer request replaces it.
+             */
+            requested_at: string;
+            after_seconds: number;
+            /**
+             * Format: date-time
+             * @description requested_at + after_seconds: the earliest suspend (within a few seconds of activity flush grace after it). A running command, an attached stream or a keepalive still active then defers the suspend until after_seconds after it ends.
+             */
+            not_before: string;
+        };
         Workspace: {
             /**
              * Format: uuid
@@ -6519,6 +6603,8 @@ export interface components {
                 basis: string | null;
                 /** @description When the workspace becomes eligible for automatic suspend if nothing happens before (work signals always win). */
                 next_eligible_at: string | null;
+                /** @description The pending suspend-when-idle request (POST …/suspend-when-idle) while the workspace runs and no tool call or resume has happened since the request, else null. It applies under every idle policy, never included. */
+                suspend_request: components["schemas"]["SuspendRequest"] | null;
             } | null;
             origin: components["schemas"]["WorkspaceOrigin"] | null;
             ended_reason: ("closed" | "idle_timeout" | "draft_discarded") | null;
@@ -6737,6 +6823,50 @@ export interface components {
             detach_requested_at: string | null;
             detached_at: string | null;
         };
+        /** @description Opt-in overage with a spend cap. Off by default. While it is on, workspaces open and run past the plan’s CPU-hours and RAM GiB-hours allowances, and the usage past them is charged at the rates below, up to the effective cap per billing period. At the cap, and while a plan invoice is past due, a used-up allowance refuses new starts (402 allowance_exhausted) and running workspaces are paused. Nothing is deleted. */
+        SpendCap: {
+            /** @description unavailable: the plan has no opt-in overage or the organization has no paid subscription. off: available, not turned on. paused: on, but a plan invoice is past due, so overage behaves as off until it is paid. within_allowance: on, no usage past the allowances yet. accruing: on, usage past an allowance is being charged. warning: charges are 80 % of the effective cap or more. reached: less than one cent of the cap is left, so starts are refused (402 allowance_exhausted, reason spend_cap_reached) and running workspaces are paused. */
+            state: "unavailable" | "off" | "paused" | "within_allowance" | "accruing" | "warning" | "reached";
+            /** @description The plan offers opt-in overage (catalog overage `opt_in`) and the organization pays for the plan with a subscription. */
+            available: boolean;
+            /** @description An owner or billing member turned overage on (spend-policy overage_enabled). */
+            enabled: boolean;
+            /** @description A plan invoice is past due (payment grace or restriction): overage behaves as off until it is paid. */
+            paused: boolean;
+            cap_minor: number | null;
+            /** @description The cap that applies: min(cap_minor, max_cap_minor), or max_cap_minor when no cap is set. 0 when overage is unavailable. */
+            effective_cap_minor: number;
+            max_cap_minor: number | null;
+            /** @description Overage charged this period so far, whole minor units (floor). It is billed on the next invoice and never exceeds the effective cap. Accrued charges stay when overage is turned off or paused. */
+            charges_minor: number;
+            /** @description What is left under the effective cap, whole minor units (floor). */
+            remaining_minor: number;
+            percent_of_cap: number | null;
+            /** @description ISO 4217 code, lower case (the plan price currency). */
+            currency: string;
+            /**
+             * Format: date-time
+             * @description When the billing period ends: charges and the cap start again from zero.
+             */
+            resets_at: string;
+            /** @description One line per dimension, RAM first (the invoice lines of the period). Empty when the plan has no overage rates. */
+            lines: {
+                /** @description The allowances overage covers. Storage and transfer never accrue overage. */
+                allowance: "ram_gib_hours" | "cpu_hours";
+                /** @description gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours. */
+                unit: "gib_hours" | "hours";
+                /** @description Usage past the allowance this period, in unit-hours (charged or not: usage before overage was turned on, while paused or past the cap is never charged). */
+                units_over: number;
+                /** @description The part of it charged this period, in unit-hours. */
+                billed_units: number;
+                /** @description Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour; 12 = $0.12 per CPU-hour). */
+                rate_minor: number;
+                /** @description billed_units × rate_minor, whole minor units (floor). Lines are floored one by one, so they may add up to one minor unit less than charges_minor. */
+                amount_minor: number;
+            }[];
+            /** @description When the charges reach the effective cap at the average burn of this period so far. Null when not accruing or when it would fall after resets_at. */
+            projected_reached_at: string | null;
+        };
     };
     responses: never;
     parameters: never;
@@ -11752,6 +11882,99 @@ export interface operations {
             };
         };
     };
+    postV1WorkspacesWorkspaceIdSuspendWhenIdle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description Seconds from now the workspace must stay idle before it is suspended (30..3600). */
+                    after_seconds: number;
+                };
+            };
+        };
+        responses: {
+            /** @description suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        workspace: components["schemas"]["Workspace"];
+                        operation: components["schemas"]["Operation"] | null;
+                        suspend_request: components["schemas"]["SuspendRequest"] | null;
+                    };
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
+    deleteV1WorkspacesWorkspaceIdSuspendWhenIdle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Workspace"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     postV1WorkspacesWorkspaceIdFork: {
         parameters: {
             query?: never;
@@ -12785,6 +13008,99 @@ export interface operations {
             };
         };
     };
+    postApiV1WorkspacesWorkspaceIdSuspendWhenIdle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description Seconds from now the workspace must stay idle before it is suspended (30..3600). */
+                    after_seconds: number;
+                };
+            };
+        };
+        responses: {
+            /** @description suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        workspace: components["schemas"]["Workspace"];
+                        operation: components["schemas"]["Operation"] | null;
+                        suspend_request: components["schemas"]["SuspendRequest"] | null;
+                    };
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
+    deleteApiV1WorkspacesWorkspaceIdSuspendWhenIdle: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Workspace"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     postApiV1WorkspacesWorkspaceIdFork: {
         parameters: {
             query?: never;
@@ -27033,6 +27349,7 @@ export interface operations {
                             included: number | null;
                             unit: string;
                         }[];
+                        exhausted_reason: ("allowance_used" | "overage_paused" | "spend_cap_reached") | null;
                         egress_override: {
                             /** @enum {string} */
                             mode: "deny_all";
@@ -27064,7 +27381,8 @@ export interface operations {
                             included_meter_units: number | null;
                             used_meter_units: number | null;
                             remaining_meter_units: number | null;
-                            cap_state: "ok" | "warning" | "exhausted" | "over_allowance" | "egress_blocked" | "uncapped" | "not_included";
+                            /** @description ok: below 80 %. warning: 80 % or more of the allowance. exhausted: a hard cap is used up and starts are refused (402 allowance_exhausted; see exhausted_reason). overage: a CPU-hours or RAM GiB-hours allowance is used up while opt-in overage is on and below its spend cap, so starts are admitted and the usage past it is charged (spend_cap). over_allowance: a reported allowance is exceeded (never refused). egress_blocked: the outbound transfer allowance is used up and outbound traffic is blocked. uncapped: runs on spare capacity. not_included: the plan does not define it. */
+                            cap_state: "ok" | "warning" | "exhausted" | "overage" | "over_allowance" | "egress_blocked" | "uncapped" | "not_included";
                         }[];
                         meters: {
                             /** @enum {string} */
@@ -27078,6 +27396,7 @@ export interface operations {
                             stripe_event_name: string | null;
                         }[];
                         alert_thresholds: number[];
+                        spend_cap: components["schemas"]["SpendCap"];
                         template_storage: components["schemas"]["OrgTemplateStorage"];
                     };
                 };
@@ -27411,11 +27730,12 @@ export interface operations {
                             currency: string;
                             interval: string;
                         } | null;
-                        /** @description Usage above the included allowances billed this period (0 while overage is disabled). */
+                        /** @description Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor). 0 while overage is off or unavailable and nothing was charged this period. */
                         usage_charges_minor: number;
                         estimated_total_minor: number | null;
                         overage: string | null;
-                        /** @description Period-to-date usage per meter at the catalog price (included in usage_charges_minor). */
+                        spend_cap: components["schemas"]["SpendCap"];
+                        /** @description Period-to-date usage per meter with its overage price and charge (included in usage_charges_minor). */
                         usage_lines: {
                             /** @enum {string} */
                             meter: "cpu_seconds" | "memory_gib_seconds" | "storage_gib_seconds" | "egress_bytes" | "ingress_bytes" | "volume_storage_gib_seconds";
@@ -27425,7 +27745,7 @@ export interface operations {
                             billable_quantity: number;
                             allowance: string | null;
                             unit_price_minor: number | null;
-                            /** @description billable_quantity x unit_price_minor above any allowance (0 without a price). */
+                            /** @description Overage charged on this meter this period, whole minor units (floor; the matching spend_cap line). 0 for meters overage never covers and when nothing was charged. */
                             amount_minor: number;
                         }[];
                         projections: {
@@ -27735,12 +28055,16 @@ export interface operations {
                         overage: string | null;
                         alert_thresholds: number[];
                         subscription_fee_minor: number | null;
+                        /** @description Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor). */
                         usage_charges_minor: number;
                         estimated_period_total_minor: number | null;
-                        /** @description Worst state over hard-cap allowances. */
-                        cap_state: "ok" | "warning" | "exhausted";
+                        /** @description Worst state over hard-cap allowances: exhausted (starts refused, see exhausted_reason) > overage (past an allowance, charged under the spend cap) > warning (80 % or more) > ok. */
+                        cap_state: "ok" | "warning" | "overage" | "exhausted";
                         exhausted: string[];
+                        exhausted_reason: ("allowance_used" | "overage_paused" | "spend_cap_reached") | null;
+                        spend_cap: components["schemas"]["SpendCap"];
                         enforcement: {
+                            /** @description refused while any hard-cap allowance is exhausted (402 allowance_exhausted with exhausted_reason as details.reason). */
                             new_starts: "allowed" | "refused";
                             running_workspaces: number;
                             /** @description How running workspaces are stopped when a hard cap is reached. */
@@ -27856,9 +28180,32 @@ export interface operations {
                          * @description UUIDv7, lowercase canonical form.
                          */
                         organization_id: string;
+                        /** @description Percentages of each allowance that send a usage email to owners and billing members. */
                         alert_thresholds: number[];
                         overage: string | null;
+                        /** @description The plan offers opt-in overage and the organization pays for it with a subscription, so overage can be turned on. */
+                        overage_available: boolean;
+                        /** @description Overage is turned on (off by default). */
+                        overage_enabled: boolean;
+                        /** @description unavailable: overage_available is false. off: available, not turned on. on: in effect up to the spend cap. paused: turned on, but a plan invoice is past due, so it behaves as off until the invoice is paid. */
+                        overage_state: "unavailable" | "off" | "on" | "paused";
+                        spend_cap_minor: number | null;
+                        spend_cap_max_minor: number | null;
+                        /** @description The smallest cap that can be set (100 = $1). */
+                        spend_cap_min_minor: number;
+                        /** @description Overage rates of the organization's plan grant. Empty when the plan has none. */
+                        rates: {
+                            /** @description The allowances overage covers. Storage and transfer never accrue overage. */
+                            allowance: "ram_gib_hours" | "cpu_hours";
+                            /** @description gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours. */
+                            unit: "gib_hours" | "hours";
+                            /** @description Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour, 12 = $0.12 per CPU-hour). */
+                            amount_minor_per_unit: number;
+                        }[];
+                        /** @description ISO 4217 code, lower case, of the cap and the rates. */
+                        currency: string;
                         updated_at: string | null;
+                        /** @description Send it as If-Match on PUT to detect a concurrent change (409 conflict, reason version_mismatch). */
                         version: number;
                     };
                 };
@@ -27886,7 +28233,10 @@ export interface operations {
     putV1OrganizationsOrganizationIdSpendPolicy: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description The spend policy version you read ("3", or "*" for any). */
+                "if-match"?: string;
+            };
             path: {
                 /** @description UUIDv7, lowercase canonical form. */
                 organization_id: string;
@@ -27896,7 +28246,12 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    alert_thresholds_percent: number[];
+                    /** @description Percentages of each allowance (1-100, at most 5). */
+                    alert_thresholds_percent?: number[];
+                    /** @description Turn overage on (needs a spend cap, given here or set before) or off. Turning it off is always allowed. */
+                    overage_enabled?: boolean;
+                    /** @description Spend cap per billing period in minor units: at least spend_cap_min_minor, at most spend_cap_max_minor (the plan price), and not below what overage already charged this period. */
+                    spend_cap_minor?: number;
                 };
             };
         };
@@ -27913,9 +28268,32 @@ export interface operations {
                          * @description UUIDv7, lowercase canonical form.
                          */
                         organization_id: string;
+                        /** @description Percentages of each allowance that send a usage email to owners and billing members. */
                         alert_thresholds: number[];
                         overage: string | null;
+                        /** @description The plan offers opt-in overage and the organization pays for it with a subscription, so overage can be turned on. */
+                        overage_available: boolean;
+                        /** @description Overage is turned on (off by default). */
+                        overage_enabled: boolean;
+                        /** @description unavailable: overage_available is false. off: available, not turned on. on: in effect up to the spend cap. paused: turned on, but a plan invoice is past due, so it behaves as off until the invoice is paid. */
+                        overage_state: "unavailable" | "off" | "on" | "paused";
+                        spend_cap_minor: number | null;
+                        spend_cap_max_minor: number | null;
+                        /** @description The smallest cap that can be set (100 = $1). */
+                        spend_cap_min_minor: number;
+                        /** @description Overage rates of the organization's plan grant. Empty when the plan has none. */
+                        rates: {
+                            /** @description The allowances overage covers. Storage and transfer never accrue overage. */
+                            allowance: "ram_gib_hours" | "cpu_hours";
+                            /** @description gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours. */
+                            unit: "gib_hours" | "hours";
+                            /** @description Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour, 12 = $0.12 per CPU-hour). */
+                            amount_minor_per_unit: number;
+                        }[];
+                        /** @description ISO 4217 code, lower case, of the cap and the rates. */
+                        currency: string;
                         updated_at: string | null;
+                        /** @description Send it as If-Match on PUT to detect a concurrent change (409 conflict, reason version_mismatch). */
                         version: number;
                     };
                 };
@@ -28026,6 +28404,7 @@ export interface operations {
                             included: number | null;
                             unit: string;
                         }[];
+                        exhausted_reason: ("allowance_used" | "overage_paused" | "spend_cap_reached") | null;
                         egress_override: {
                             /** @enum {string} */
                             mode: "deny_all";
@@ -28057,7 +28436,8 @@ export interface operations {
                             included_meter_units: number | null;
                             used_meter_units: number | null;
                             remaining_meter_units: number | null;
-                            cap_state: "ok" | "warning" | "exhausted" | "over_allowance" | "egress_blocked" | "uncapped" | "not_included";
+                            /** @description ok: below 80 %. warning: 80 % or more of the allowance. exhausted: a hard cap is used up and starts are refused (402 allowance_exhausted; see exhausted_reason). overage: a CPU-hours or RAM GiB-hours allowance is used up while opt-in overage is on and below its spend cap, so starts are admitted and the usage past it is charged (spend_cap). over_allowance: a reported allowance is exceeded (never refused). egress_blocked: the outbound transfer allowance is used up and outbound traffic is blocked. uncapped: runs on spare capacity. not_included: the plan does not define it. */
+                            cap_state: "ok" | "warning" | "exhausted" | "overage" | "over_allowance" | "egress_blocked" | "uncapped" | "not_included";
                         }[];
                         meters: {
                             /** @enum {string} */
@@ -28071,6 +28451,7 @@ export interface operations {
                             stripe_event_name: string | null;
                         }[];
                         alert_thresholds: number[];
+                        spend_cap: components["schemas"]["SpendCap"];
                         template_storage: components["schemas"]["OrgTemplateStorage"];
                     };
                 };
@@ -28404,11 +28785,12 @@ export interface operations {
                             currency: string;
                             interval: string;
                         } | null;
-                        /** @description Usage above the included allowances billed this period (0 while overage is disabled). */
+                        /** @description Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor). 0 while overage is off or unavailable and nothing was charged this period. */
                         usage_charges_minor: number;
                         estimated_total_minor: number | null;
                         overage: string | null;
-                        /** @description Period-to-date usage per meter at the catalog price (included in usage_charges_minor). */
+                        spend_cap: components["schemas"]["SpendCap"];
+                        /** @description Period-to-date usage per meter with its overage price and charge (included in usage_charges_minor). */
                         usage_lines: {
                             /** @enum {string} */
                             meter: "cpu_seconds" | "memory_gib_seconds" | "storage_gib_seconds" | "egress_bytes" | "ingress_bytes" | "volume_storage_gib_seconds";
@@ -28418,7 +28800,7 @@ export interface operations {
                             billable_quantity: number;
                             allowance: string | null;
                             unit_price_minor: number | null;
-                            /** @description billable_quantity x unit_price_minor above any allowance (0 without a price). */
+                            /** @description Overage charged on this meter this period, whole minor units (floor; the matching spend_cap line). 0 for meters overage never covers and when nothing was charged. */
                             amount_minor: number;
                         }[];
                         projections: {
@@ -28728,12 +29110,16 @@ export interface operations {
                         overage: string | null;
                         alert_thresholds: number[];
                         subscription_fee_minor: number | null;
+                        /** @description Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor). */
                         usage_charges_minor: number;
                         estimated_period_total_minor: number | null;
-                        /** @description Worst state over hard-cap allowances. */
-                        cap_state: "ok" | "warning" | "exhausted";
+                        /** @description Worst state over hard-cap allowances: exhausted (starts refused, see exhausted_reason) > overage (past an allowance, charged under the spend cap) > warning (80 % or more) > ok. */
+                        cap_state: "ok" | "warning" | "overage" | "exhausted";
                         exhausted: string[];
+                        exhausted_reason: ("allowance_used" | "overage_paused" | "spend_cap_reached") | null;
+                        spend_cap: components["schemas"]["SpendCap"];
                         enforcement: {
+                            /** @description refused while any hard-cap allowance is exhausted (402 allowance_exhausted with exhausted_reason as details.reason). */
                             new_starts: "allowed" | "refused";
                             running_workspaces: number;
                             /** @description How running workspaces are stopped when a hard cap is reached. */
@@ -28849,9 +29235,32 @@ export interface operations {
                          * @description UUIDv7, lowercase canonical form.
                          */
                         organization_id: string;
+                        /** @description Percentages of each allowance that send a usage email to owners and billing members. */
                         alert_thresholds: number[];
                         overage: string | null;
+                        /** @description The plan offers opt-in overage and the organization pays for it with a subscription, so overage can be turned on. */
+                        overage_available: boolean;
+                        /** @description Overage is turned on (off by default). */
+                        overage_enabled: boolean;
+                        /** @description unavailable: overage_available is false. off: available, not turned on. on: in effect up to the spend cap. paused: turned on, but a plan invoice is past due, so it behaves as off until the invoice is paid. */
+                        overage_state: "unavailable" | "off" | "on" | "paused";
+                        spend_cap_minor: number | null;
+                        spend_cap_max_minor: number | null;
+                        /** @description The smallest cap that can be set (100 = $1). */
+                        spend_cap_min_minor: number;
+                        /** @description Overage rates of the organization's plan grant. Empty when the plan has none. */
+                        rates: {
+                            /** @description The allowances overage covers. Storage and transfer never accrue overage. */
+                            allowance: "ram_gib_hours" | "cpu_hours";
+                            /** @description gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours. */
+                            unit: "gib_hours" | "hours";
+                            /** @description Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour, 12 = $0.12 per CPU-hour). */
+                            amount_minor_per_unit: number;
+                        }[];
+                        /** @description ISO 4217 code, lower case, of the cap and the rates. */
+                        currency: string;
                         updated_at: string | null;
+                        /** @description Send it as If-Match on PUT to detect a concurrent change (409 conflict, reason version_mismatch). */
                         version: number;
                     };
                 };
@@ -28879,7 +29288,10 @@ export interface operations {
     putApiV1OrganizationsOrganizationIdSpendPolicy: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description The spend policy version you read ("3", or "*" for any). */
+                "if-match"?: string;
+            };
             path: {
                 /** @description UUIDv7, lowercase canonical form. */
                 organization_id: string;
@@ -28889,7 +29301,12 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    alert_thresholds_percent: number[];
+                    /** @description Percentages of each allowance (1-100, at most 5). */
+                    alert_thresholds_percent?: number[];
+                    /** @description Turn overage on (needs a spend cap, given here or set before) or off. Turning it off is always allowed. */
+                    overage_enabled?: boolean;
+                    /** @description Spend cap per billing period in minor units: at least spend_cap_min_minor, at most spend_cap_max_minor (the plan price), and not below what overage already charged this period. */
+                    spend_cap_minor?: number;
                 };
             };
         };
@@ -28906,9 +29323,32 @@ export interface operations {
                          * @description UUIDv7, lowercase canonical form.
                          */
                         organization_id: string;
+                        /** @description Percentages of each allowance that send a usage email to owners and billing members. */
                         alert_thresholds: number[];
                         overage: string | null;
+                        /** @description The plan offers opt-in overage and the organization pays for it with a subscription, so overage can be turned on. */
+                        overage_available: boolean;
+                        /** @description Overage is turned on (off by default). */
+                        overage_enabled: boolean;
+                        /** @description unavailable: overage_available is false. off: available, not turned on. on: in effect up to the spend cap. paused: turned on, but a plan invoice is past due, so it behaves as off until the invoice is paid. */
+                        overage_state: "unavailable" | "off" | "on" | "paused";
+                        spend_cap_minor: number | null;
+                        spend_cap_max_minor: number | null;
+                        /** @description The smallest cap that can be set (100 = $1). */
+                        spend_cap_min_minor: number;
+                        /** @description Overage rates of the organization's plan grant. Empty when the plan has none. */
+                        rates: {
+                            /** @description The allowances overage covers. Storage and transfer never accrue overage. */
+                            allowance: "ram_gib_hours" | "cpu_hours";
+                            /** @description gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours. */
+                            unit: "gib_hours" | "hours";
+                            /** @description Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour, 12 = $0.12 per CPU-hour). */
+                            amount_minor_per_unit: number;
+                        }[];
+                        /** @description ISO 4217 code, lower case, of the cap and the rates. */
+                        currency: string;
                         updated_at: string | null;
+                        /** @description Send it as If-Match on PUT to detect a concurrent change (409 conflict, reason version_mismatch). */
                         version: number;
                     };
                 };