@cubos/agent-sdk 0.0.1154888 → 0.0.1154905

package/dist/generated/schema.d.ts

@@ -7615,6 +7615,188 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/tenants/{tenantSlug}/cost-limits": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Tenant-default spend ceilings
+         * @description The ceilings that apply to every user of this tenant who has no override of their own. An empty list means no default ceiling — the shipped state. Requires `users:read`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CostLimits"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        /**
+         * Replace the tenant-default spend ceilings
+         * @description Declarative: the body is the complete set, and any period left out is removed. Clears every budget hold in the tenant, so a scheduled run frozen under the old ceilings is reconsidered on the next poll. Requires `users:write`.
+         */
+        put: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["PutCostLimits"];
+                };
+            };
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CostLimits"];
+                    };
+                };
+                /** @description A period appears twice, or a ceiling is negative or not finite. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description The message has a `{word}` that is not a placeholder: `error` is `unknown_placeholder` and `placeholder` names it. */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/tenants/{tenantSlug}/cost/over-limit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Users currently blocked by a ceiling
+         * @description Everyone sitting at or past one of their ceilings right now, shortest breached window first. Computed at read time — nothing stores "is over", because a ceiling lifts by the clock passing an instant and a stored flag would be stale between the window turning over and whatever refreshed it. Requires `users:read`.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Rows to return, 1–500 (default 100). */
+                    limit?: number;
+                };
+                header?: never;
+                path: {
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["OverLimitList"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/tenants/{tenantSlug}/knowledge-bases": {
         parameters: {
             query?: never;
@@ -11270,6 +11452,184 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/tenants/{tenantSlug}/users/{id}/cost-limits": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * One user's spend-ceiling overrides
+         * @description Only this user's own overrides — an empty list means they inherit the tenant defaults, not that they are unlimited. `…/cost/status` is what reports the ceilings actually in force. Requires `users:read`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description User id. */
+                    id: string;
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CostLimits"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        /**
+         * Replace one user's spend-ceiling overrides
+         * @description Declarative: the body is the complete set of overrides, and an empty list drops them all so the user falls back to the tenant defaults. Clears this user's budget holds. Requires `users:write`.
+         */
+        put: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description User id. */
+                    id: string;
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["PutCostLimits"];
+                };
+            };
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CostLimits"];
+                    };
+                };
+                /** @description A period appears twice, or a ceiling is negative or not finite. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/tenants/{tenantSlug}/users/{id}/cost/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Spend against the ceilings in force
+         * @description Spent-versus-limit for each window that applies to this user, with overrides already resolved against the tenant defaults. The cheap read the dashboard needs to draw "3.20 of 10.00 this month" — `…/cost` is the series and the per-model breakdown. Requires `users:read`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description User id. */
+                    id: string;
+                    /** @description Tenant slug (kebab-case). */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CostStatus"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/tenants/{tenantSlug}/users/{id}/identities": {
         parameters: {
             query?: never;
@@ -13150,6 +13510,98 @@ export interface components {
             conversations: number;
             tag: string;
         };
+        /**
+         * @description The language a refusal's placeholders are written in, and of its default
+         *     wording — the tenant's choice, stored beside its wording
+         *     (`tenants.cost_limit_locale`, beside `cost_limit_message`). A closed set
+         *     because each value is a translation shipped here.
+         * @enum {string}
+         */
+        CostLimitLocale: "pt-BR" | "en" | "es";
+        CostLimitRule: {
+            /**
+             * Format: double
+             * @description Ceiling in USD. `0` stops the user outright — the comparison is
+             *     `spent >= limit` — which together with "no rule means no ceiling" gives
+             *     two distinct states: absent is unlimited, zero is off.
+             */
+            limit_usd: number;
+            /**
+             * @description Window the ceiling applies over: `hour`, `day`, `week` or `month`.
+             *     Windows are calendar-aligned and cut in the user's own timezone.
+             */
+            period: components["schemas"]["Period"];
+            /**
+             * Format: int32
+             * @description `month` only: the day of the month (1–31) it turns over on; a month
+             *     without that day turns over on its last. Default 1.
+             */
+            reset_day?: number | null;
+            /**
+             * Format: int32
+             * @description `day`, `week` and `month`: the hour (0–23, on the user's clock) the
+             *     window turns over at. Default 0. Whole hours only: the spend is read
+             *     from a rollup kept per hour. Refused on `hour`.
+             */
+            reset_hour?: number | null;
+            reset_weekday?: components["schemas"]["ResetWeekday"] | null;
+        };
+        CostLimits: {
+            /**
+             * @description Tenant scope only: the default wording in every locale, so an editor
+             *     can show what "unset" resolves to without a copy of its own.
+             */
+            default_messages: {
+                [key: string]: string;
+            } | null;
+            locale: components["schemas"]["CostLimitLocale"] | null;
+            /**
+             * @description Tenant scope only: the wording a refused user is shown, as typed, or
+             *     null when the tenant has authored none and the locale's default
+             *     applies. Absent on the per-user route — the message is a tenant
+             *     setting, because the same person hitting the same ceiling must not be
+             *     told two different things depending on which agent they reached.
+             */
+            message: string | null;
+            /**
+             * @description Tenant scope only: what each placeholder renders as, in every locale,
+             *     for an example instant (tomorrow at 00:00 UTC) — written by the same
+             *     code as a real refusal, so an editor can preview the text without a
+             *     copy of the formats. Its keys are the placeholders there are.
+             */
+            placeholder_examples: {
+                [key: string]: {
+                    [key: string]: string;
+                };
+            } | null;
+            /**
+             * @description The rules for this scope, shortest window first. Empty means no
+             *     ceiling is configured here.
+             */
+            rules: components["schemas"]["CostLimitRule"][];
+        };
+        CostStatus: {
+            blocked_by: components["schemas"]["Period"] | null;
+            /**
+             * @description Every ceiling in force for this user, tenant defaults and overrides
+             *     already resolved, shortest window first.
+             */
+            windows: components["schemas"]["CostStatusWindow"][];
+        };
+        CostStatusWindow: {
+            /** @description True once `spent_usd >= limit_usd`. */
+            exceeded: boolean;
+            /** Format: double */
+            limit_usd: number;
+            period: components["schemas"]["Period"];
+            /**
+             * Format: date-time
+             * @description Start of the next window — when this one frees up.
+             */
+            resets_at: string;
+            /** Format: double */
+            spent_usd: number;
+        };
         CountTokensResponse: {
             breakdown: components["schemas"]["Breakdown"] | null;
             /**
@@ -14589,6 +15041,38 @@ export interface components {
              */
             retrying: number;
         };
+        OverLimitList: {
+            /**
+             * @description True when the tenant has more blocked users than were returned. A
+             *     truncated list that did not say so would be the worst possible answer
+             *     here: the reader would conclude the ones they cannot see are fine.
+             */
+            truncated: boolean;
+            users: components["schemas"]["OverLimitUser"][];
+        };
+        OverLimitUser: {
+            display_name: string | null;
+            /** Format: double */
+            limit_usd: number;
+            /**
+             * @description The breached window. Shortest first across the list, so whoever frees
+             *     up soonest is at the top.
+             */
+            period: components["schemas"]["Period"];
+            primary_identifier: string | null;
+            /** Format: date-time */
+            resets_at: string;
+            /** Format: double */
+            spent_usd: number;
+            /**
+             * @description The user's own timezone, which is where the window was cut — the
+             *     `resets_at` above is an instant, and a client showing it should render
+             *     it here rather than in the operator's zone.
+             */
+            timezone: string;
+            /** Format: uuid */
+            user_id: string;
+        };
         /**
          * @description One citation note, already parsed.
          *
@@ -14615,6 +15099,15 @@ export interface components {
             source_id: string;
             source_title: string;
         };
+        /**
+         * @description The four windows a ceiling can be set over.
+         *
+         *     Ordered shortest-first, which is also the order a breach is reported in:
+         *     the shortest breached window is the one that frees up soonest, so it is the
+         *     one whose `resets_at` is worth telling the user about.
+         * @enum {string}
+         */
+        Period: "hour" | "day" | "week" | "month";
         PersonalMemoryObservation: {
             content: string;
             /** Format: uuid */
@@ -14704,6 +15197,19 @@ export interface components {
         PutAutoCallToolsInput: {
             tools: components["schemas"]["AutoCallToolRef"][];
         };
+        PutCostLimits: {
+            locale?: components["schemas"]["CostLimitLocale"] | null;
+            /**
+             * @description Tenant scope only. Sent as typed, but for its placeholders — `{date}`,
+             *     `{time}` and `{weekday}`, filled in with when access returns, on the
+             *     user's clock and in the locale's format. Any other `{word}` is refused
+             *     (422). Omit to leave the current wording alone; send an empty string to
+             *     clear it back to the locale's default. Ignored by the per-user route.
+             */
+            message?: string | null;
+            /** @description The complete set for this scope. Omitted periods are removed. */
+            rules: components["schemas"]["CostLimitRule"][];
+        };
         /**
          * @description The reasoning a model produced for the assistant turn it sits in. Carries the
          *     human-readable chain-of-thought and/or an opaque continuity blob — a turn may
@@ -14770,6 +15276,12 @@ export interface components {
         ReplaceClientToolsInput: {
             tools: components["schemas"]["NamedClientToolInput"][];
         };
+        /**
+         * @description A day of the week, as the API spells it. Kept apart from
+         *     `chrono::Weekday` so the wire format is ours.
+         * @enum {string}
+         */
+        ResetWeekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";
         /**
          * @description The query as it was answered: defaults filled in and the interval rounded
          *     to whole hours.

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export type { AdminClient, AdminClientOptions, TenantScope } from "./admin/index.js";
 export { createAdminClient } from "./admin/index.js";
 export type { Dimension, DimensionValues, DimensionValuesQuery, EntityLabel, Granularity, MetricId, MetricIdOf, MetricInfo, MetricSpec, MetricsCatalog, MetricsCompleteness, MetricsFilter, MetricsFilters, MetricsInclude, MetricsOrderBy, MetricsQuery, MetricsResult, MetricsRow, } from "./admin/metrics.js";
+export type { CostPeriod } from "./admin/users.js";
 export type { CachedConversation, ConversationCache, MemoryConversationCacheOptions, } from "./cache.js";
 export { MemoryConversationCache } from "./cache.js";
 export type { ClientOptions, ClientOptions as UserClientOptions, ConversationHandlers, ConversationSubscription, HistoryStart, ListHandlers, UserCredential, } from "./client.js";
 export { AgentClient, createUserClient } from "./client.js";
 export type { ClientTool, ClientToolContext, ClientToolsSession, ServeClientToolsOptions, } from "./client-tools.js";
 export { serveClientTools } from "./client-tools.js";
+export type { OverBudget } from "./errors.js";
 export { AgentApiError, AgentConfigError, AgentError, AgentNetworkError } from "./errors.js";
 export type { Auth, TokenSource, Transport } from "./http.js";
 export { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS } from "./http.js";

package/dist/index.js

@@ -36,6 +36,18 @@ class AgentApiError extends AgentError {
   get isRetryable() {
     return this.status === 429 || this.status >= 500;
   }
+  get overBudget() {
+    if (this.status !== 402)
+      return null;
+    const b = this.json();
+    if (b?.error !== "over_budget" || !b.period || !b.resets_at)
+      return null;
+    return {
+      period: b.period,
+      resetsAt: b.resets_at,
+      message: b.message ?? "Spending limit reached."
+    };
+  }
 }
 
 class AgentConfigError extends AgentError {
@@ -1096,6 +1108,11 @@ function usersApi(t, tenantSlug) {
   return {
     list: (query = {}, signal) => t.request("GET", base, { query, signal }),
     get: (id, signal) => t.request("GET", user(id), { signal }),
+    costStatus: (id, signal) => t.request("GET", `${user(id)}/cost/status`, { signal }),
+    costLimits: {
+      get: (id, signal) => t.request("GET", `${user(id)}/cost-limits`, { signal }),
+      put: (id, input) => t.request("PUT", `${user(id)}/cost-limits`, { body: input })
+    },
     create: (input) => t.request("POST", base, { body: input }),
     update: (id, input) => t.request("PATCH", user(id), { body: input }),
     delete: (id) => t.request("DELETE", user(id), { raw: true }),
@@ -1138,6 +1155,17 @@ function userRolesApi(t, tenantSlug) {
     delete: (slug) => t.request("DELETE", role(slug), { raw: true })
   };
 }
+function costLimitsApi(t, tenantSlug) {
+  const base = `${tenantPath(tenantSlug)}/cost-limits`;
+  return {
+    get: (signal) => t.request("GET", base, { signal }),
+    put: (input) => t.request("PUT", base, { body: input }),
+    overLimit: (query = {}, signal) => t.request("GET", `${tenantPath(tenantSlug)}/cost/over-limit`, {
+      query,
+      signal
+    })
+  };
+}
 function userTokensApi(t, tenantSlug) {
   return {
     create: (input) => t.request("POST", `${tenantPath(tenantSlug)}/user-tokens`, {
@@ -1159,6 +1187,7 @@ function tenantScope(t, slug) {
     users: usersApi(t, slug),
     userRoles: userRolesApi(t, slug),
     userTokens: userTokensApi(t, slug),
+    costLimits: costLimitsApi(t, slug),
     knowledgeBases: knowledgeBasesApi(t, slug),
     taskTemplates: taskTemplatesApi(t, slug),
     scheduledRuns: scheduledRunsApi(t, slug),
@@ -2071,5 +2100,5 @@ export {
   serveClientTools
 };
 
-//# debugId=DA5368DD2353F7BE64756E2164756E21
+//# debugId=F7769B86B91CDAD264756E2164756E21
 //# sourceMappingURL=index.js.map