@cubos/agent-sdk 0.0.1154897 → 0.0.1154905

package/dist/admin/index.d.ts

@@ -13,7 +13,7 @@ import { mcpsApi } from "./mcps.js";
 import { instanceMetricsApi, metricsApi } from "./metrics.js";
 import { skillsApi } from "./skills.js";
 import { backgroundTasksApi, scheduledRunsApi, taskTemplatesApi } from "./task-templates.js";
-import { userRolesApi, usersApi, userTokensApi } from "./users.js";
+import { costLimitsApi, userRolesApi, usersApi, userTokensApi } from "./users.js";
 export interface AdminClientOptions {
     /** Where the Cubos Agent core is reachable, e.g. `https://agent.acme.com`. */
     baseUrl: string;
@@ -40,6 +40,8 @@ export interface TenantScope {
     users: ReturnType<typeof usersApi>;
     userRoles: ReturnType<typeof userRolesApi>;
     userTokens: ReturnType<typeof userTokensApi>;
+    /** Tenant-wide default spend ceilings; per-user overrides live under `users`. */
+    costLimits: ReturnType<typeof costLimitsApi>;
     knowledgeBases: ReturnType<typeof knowledgeBasesApi>;
     taskTemplates: ReturnType<typeof taskTemplatesApi>;
     scheduledRuns: ReturnType<typeof scheduledRunsApi>;

package/dist/admin/users.d.ts

@@ -1,5 +1,11 @@
 import type { Transport } from "../http.js";
 import type { Schemas } from "../schemas.js";
+/**
+ * The windows a spend ceiling can be set over. Each is also a `granularity` of
+ * the metrics API, so an operator who sets a weekly ceiling can read the
+ * weekly series of `cost_usd` filtered to that user.
+ */
+export type CostPeriod = "hour" | "day" | "week" | "month";
 export declare function usersApi(t: Transport, tenantSlug: string): {
     list: (query?: {
         status?: string;
@@ -30,6 +36,51 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
         updated_at: string;
         user_md: string;
     }>;
+    /**
+     * Spend against the ceilings actually in force for this user — tenant
+     * defaults and per-user overrides already resolved.
+     *
+     * This is the one to draw a meter from. `costLimits.get` returns only the
+     * user's own overrides, so an empty list there means "inherits", not
+     * "unlimited".
+     */
+    costStatus: (id: string, signal?: AbortSignal) => Promise<{
+        blocked_by: import("../generated/schema.js").components["schemas"]["Period"] | null;
+        windows: import("../generated/schema.js").components["schemas"]["CostStatusWindow"][];
+    }>;
+    /**
+     * This user's spend-ceiling overrides. Declarative: `put` replaces the
+     * whole set, and putting `{ rules: [] }` drops every override so they fall
+     * back to the tenant defaults.
+     */
+    costLimits: {
+        get: (id: string, signal?: AbortSignal) => Promise<{
+            default_messages: {
+                [key: string]: string;
+            } | null;
+            locale: import("../generated/schema.js").components["schemas"]["CostLimitLocale"] | null;
+            message: string | null;
+            placeholder_examples: {
+                [key: string]: {
+                    [key: string]: string;
+                };
+            } | null;
+            rules: import("../generated/schema.js").components["schemas"]["CostLimitRule"][];
+        }>;
+        put: (id: string, input: Schemas["PutCostLimits"]) => Promise<{
+            default_messages: {
+                [key: string]: string;
+            } | null;
+            locale: import("../generated/schema.js").components["schemas"]["CostLimitLocale"] | null;
+            message: string | null;
+            placeholder_examples: {
+                [key: string]: {
+                    [key: string]: string;
+                };
+            } | null;
+            rules: import("../generated/schema.js").components["schemas"]["CostLimitRule"][];
+        }>;
+    };
     create: (input: Schemas["CreateUserInput"]) => Promise<{
         created_at: string;
         display_name: string | null;
@@ -203,6 +254,55 @@ export declare function userRolesApi(t: Transport, tenantSlug: string): {
     }>;
     delete: (slug: string) => Promise<void>;
 };
+/**
+ * Tenant-wide default spend ceilings — what applies to every user with no
+ * override of their own.
+ *
+ * Nothing is seeded: a tenant starts with an empty list, meaning no user has a
+ * ceiling. A rule with `limit_usd: 0` is not the same as no rule — absent is
+ * unlimited, zero stops the user outright.
+ */
+export declare function costLimitsApi(t: Transport, tenantSlug: string): {
+    get: (signal?: AbortSignal) => Promise<{
+        default_messages: {
+            [key: string]: string;
+        } | null;
+        locale: import("../generated/schema.js").components["schemas"]["CostLimitLocale"] | null;
+        message: string | null;
+        placeholder_examples: {
+            [key: string]: {
+                [key: string]: string;
+            };
+        } | null;
+        rules: import("../generated/schema.js").components["schemas"]["CostLimitRule"][];
+    }>;
+    /** Replaces the whole set; any period left out is removed. */
+    put: (input: Schemas["PutCostLimits"]) => Promise<{
+        default_messages: {
+            [key: string]: string;
+        } | null;
+        locale: import("../generated/schema.js").components["schemas"]["CostLimitLocale"] | null;
+        message: string | null;
+        placeholder_examples: {
+            [key: string]: {
+                [key: string]: string;
+            };
+        } | null;
+        rules: import("../generated/schema.js").components["schemas"]["CostLimitRule"][];
+    }>;
+    /**
+     * Everyone currently blocked by a ceiling. Computed at read time — a
+     * ceiling lifts by the clock passing an instant, so there is no stored
+     * flag that could be trusted between the window turning over and a
+     * refresh.
+     */
+    overLimit: (query?: {
+        limit?: number;
+    }, signal?: AbortSignal) => Promise<{
+        truncated: boolean;
+        users: import("../generated/schema.js").components["schemas"]["OverLimitUser"][];
+    }>;
+};
 /**
  * Mints the short-lived tokens a browser SDK runs on (see `createUserClient`).
  * Call this from your own backend only — it needs an api_key, which must never

package/dist/errors.d.ts

@@ -1,3 +1,23 @@
+/**
+ * A spend ceiling was reached. The body of a 402, parsed.
+ *
+ * Carries no amounts, deliberately. The dollar figures behind a ceiling are
+ * the operator's accounting: most products put their own layer over this —
+ * credits, a plan tier, a quota in requests — so "you spent 0.055 of 0.05"
+ * would be a unit the user was never sold in. Those figures live on the admin
+ * surface, behind `users:read`.
+ *
+ * What is here is what an app can act on: `message`, authored by the tenant
+ * and therefore already speaking in whatever unit they sell; the window that
+ * tripped; and when it lifts.
+ */
+export interface OverBudget {
+    period: "hour" | "day" | "week" | "month";
+    /** When the window turns over and access returns, as an ISO instant. */
+    resetsAt: string;
+    /** Ready to show, already naming the window and the reset. */
+    message: string;
+}
 /** Base for everything this SDK throws, so `catch (e) { if (e instanceof
  * AgentError) }` covers both an HTTP failure and a connection that never got
  * there. */
@@ -23,8 +43,25 @@ export declare class AgentApiError extends AgentError {
     /** The request clashed with current state — a slug already taken, a
      * conversation that belongs to a channel, a user already blocked. */
     get isConflict(): boolean;
-    /** Worth retrying after a pause: the server is overloaded or briefly down. */
+    /**
+     * Worth retrying after a pause: the server is overloaded or briefly down.
+     *
+     * Note what is absent. A 402 is *not* retryable here, deliberately: the
+     * window it names is hours or days away, so retrying is pointless and
+     * retrying automatically would spend the user's backoff budget on a wall
+     * that is not going to move.
+     */
     get isRetryable(): boolean;
+    /**
+     * The spend ceiling this request hit, or `null` when the failure was
+     * something else.
+     *
+     * Distinct from `isAuthError` on purpose — a blocked user (403) and a user
+     * over budget (402) look the same to a client that only checks "was I
+     * refused", and they are opposite situations: one needs an operator, the
+     * other needs a clock.
+     */
+    get overBudget(): OverBudget | null;
 }
 /**
  * The client was constructed wrong — a `baseUrl` with no scheme, most often.