@aexhq/sdk 0.75.3 → 0.77.0

package/README.md

@@ -1,5 +1,16 @@
 # Aex SDK
 
+`aex.billing` reads credits and ledger entries, accepts a pricebook and spend limit, creates
+idempotent Stripe topups/refunds, and synchronizes provider status and receipt links. Mutations
+require an account credential. Configure `maxCostMicroUsd` on a prepaid workload client for its
+per-operation ceiling. Attachment uploads also accept `downloadBudgetBytes` and an optional
+operation-specific `maxCostMicroUsd`. See [billing](../../docs/billing.md) for units and recovery.
+
+`session.submit()` returns the saved turn's event sequence immediately. Hosted Tools keep running
+after client close; host Tools require their process online. Follow Events from that sequence and read
+the transcript when the turn terminates. Put structured correction policy in the hosted Agentloop
+when submitting from a short-lived Server Action.
+
 Install `@aexhq/sdk`. Create an API key at https://aex.dev/dashboard.
 
 ```ts
@@ -10,8 +21,8 @@ console.log(await aex.account.get());
 ```
 
 `Aex` extends the pinned Brain client. Its sessions, registration, Events, Components and
-extension builders are Brain's implementations. SDK 0.75 uses Brain SDK 0.24 and Pi/Codex/Tools
-6.1. Images and PDFs use HTTPS URLs; Aex owns attachment publication and expiry. Deploy the matching
+extension builders are Brain's implementations. SDK 0.77 uses Brain SDK 0.27 and Pi/Codex
+6.2. Images and PDFs use HTTPS URLs; Aex owns attachment publication and expiry. Deploy the matching
 runtime and extensions together. Retained sessions require a compatibility check before upgrading.
 See https://aex.dev/docs
 for a complete session example.
@@ -42,8 +53,10 @@ standalone Brain and require operator deployment. See [official extensions](http
 
 Place uploaded Wasm Agentloops and Tools in `brainEnv` for hosted execution. `hostEnv`
 executes application functions in your process. Native hosted Components receive no server
-secrets, filesystem or network grants. Customer-selected HTTP Environments are not enabled
-on the initial deployment. Hosted `brainEnv` configuration must be empty; resource access
+secrets, filesystem or network grants. `await aex.environments.list()` lists your account's
+published configurations. Import `modal` from `@aexhq/env-modal` and pass the catalog URL and
+granted profile name; [managed execution](../../docs/environments.md) reserves credits at creation.
+Customer-selected HTTP endpoints are denied. Hosted `brainEnv` configuration must be empty; resource access
 is configured by each Environment, not declared through extension `needs`. Prepare dependencies
 for `hostEnv` Tools in your application before registering them. Supply your model key per session.
 
@@ -53,6 +66,12 @@ not grant authority to create more credentials. New key secrets are returned onc
 
 ## Structured output
 
+For asynchronous hosted work, configure the official loop with
+`output: {schema: z.toJSONSchema(answerType), maxCorrections: 2}` and use `session.submit()`.
+Validation and bounded corrections run inside that turn. Corrections cannot dispatch Tools;
+only a schema-valid final answer emits an assistant message. Business refinements belong in
+your Tools or application, and are not encoded by JSON Schema.
+
 Pass `output: { type: z.object({ name: z.string() }), maxRetries: 2 }` in the second
 argument to `session.send`. The SDK prompts for JSON, validates with Zod locally,
 and returns the inferred parsed value. Two additional correction turns are allowed

package/dist/generated.d.ts

@@ -3,7 +3,30 @@ import type { Media } from "@aexhq/brain";
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "Billing".
  */
-export type Billing = "preview_customer_model_keys";
+export type Billing = "preview_customer_model_keys" | "prepaid_customer_model_keys";
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "BillingMode".
+ */
+export type BillingMode = "preview" | "prepaid";
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Mode".
+ */
+export type Mode = "test" | "live";
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "SyncPayment".
+ */
+export type SyncPayment = {
+    checkout_id?: string | null;
+    id: string;
+    kind: "topup";
+} | {
+    id: string;
+    kind: "refund";
+    refund_id?: string | null;
+};
 export interface AexContracts {
 }
 /**
@@ -123,3 +146,137 @@ export interface AccountSession {
     expires: number;
     token: string;
 }
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Pricebook".
+ */
+export interface Pricebook {
+    id: string;
+    rates: {
+        attachment_byte_secs?: Rate;
+        egress_bytes?: Rate;
+        sandbox_ms?: Rate;
+        turn_ms?: Rate;
+    };
+}
+/**
+ * A rational price in micro-USD. Rating rounds once over cumulative resource usage.
+ *
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Rate".
+ */
+export interface Rate {
+    micro_usd: number;
+    units: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Wallet".
+ */
+export interface Wallet {
+    accepted_pricebook?: string | null;
+    available_micro_usd: number;
+    balance_micro_usd: number;
+    currency: string;
+    mode: BillingMode;
+    offered_pricebook?: Pricebook | null;
+    payment_mode?: Mode | null;
+    reserved_micro_usd: number;
+    spend_limit_micro_usd?: number | null;
+    spent_this_month_micro_usd: number;
+    suspended: boolean;
+    topup_amounts_cents: number[];
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "BillingSettings".
+ */
+export interface BillingSettings {
+    pricebook: string;
+    spend_limit_micro_usd: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "LedgerEntry".
+ */
+export interface LedgerEntry {
+    created: number;
+    delta_micro_usd: number;
+    description: string;
+    id: number;
+    kind: string;
+    reference: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "LedgerPage".
+ */
+export interface LedgerPage {
+    entries: LedgerEntry[];
+    next_before?: number | null;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "TopupInput".
+ */
+export interface TopupInput {
+    amount_cents: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Topup".
+ */
+export interface Topup {
+    amount_cents: number;
+    checkout_url?: string | null;
+    created: number;
+    id: string;
+    receipt_url?: string | null;
+    refunded_cents: number;
+    state: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "RefundInput".
+ */
+export interface RefundInput {
+    amount_cents: number;
+    topup: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Refund".
+ */
+export interface Refund {
+    amount_cents: number;
+    created: number;
+    id: string;
+    state: string;
+    topup: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "EnvironmentProfile".
+ */
+export interface EnvironmentProfile {
+    maxLifetimeMs: number;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "EnvironmentCatalog".
+ */
+export interface EnvironmentCatalog {
+    driver_url: string;
+    profiles: {
+        [k: string]: EnvironmentProfile;
+    };
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "EnvironmentSelection".
+ */
+export interface EnvironmentSelection {
+    lifetimeMs: number;
+    profile: string;
+}

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export * from "@aexhq/brain";
 export type * from "./generated.js";
 import { Brain, type BrainOptions } from "@aexhq/brain";
-import type { Attachment, Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession } from "./generated.js";
+import type { EnvironmentCatalog } from "./generated.js";
+import type { Attachment, Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession, Wallet, BillingSettings, LedgerPage, Topup, TopupInput, Refund, RefundInput, SyncPayment } from "./generated.js";
 export type AexConnection = Omit<BrainOptions, "token" | "baseUrl"> & {
     baseUrl?: string;
 };
-export type AexOptions = AexConnection & ({
+export type AexOptions = AexConnection & {
+    maxCostMicroUsd?: number;
+} & ({
     apiKey: string;
     accountToken?: never;
 } | {
@@ -13,13 +16,18 @@ export type AexOptions = AexConnection & ({
     apiKey?: never;
 });
 export declare class Aex extends Brain {
-    constructor({ apiKey, accountToken, ...options }: AexOptions);
+    private readonly maxCostMicroUsd?;
+    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }: AexOptions);
+    /** The ceiling applies separately to each admitted operation. Model BYOK charges remain with the provider. */
+    request<T>(method: string, path: string, body?: unknown, idempotencyKey?: string, contentType?: string, signal?: AbortSignal, extraHeaders?: HeadersInit): Promise<T>;
     static exchangeLogin(input: LoginExchange, options?: AexConnection): Promise<AccountSession>;
     readonly attachments: {
         upload: (sessionId: string, bytes: Uint8Array, options: {
             contentType: string;
             expiresAt?: number;
             idempotencyKey: string;
+            downloadBudgetBytes?: number;
+            maxCostMicroUsd?: number;
             signal?: AbortSignal;
         }) => Promise<Attachment>;
         delete: (sessionId: string, id: string) => Promise<void>;
@@ -30,6 +38,19 @@ export declare class Aex extends Brain {
         logout: () => Promise<void>;
         authorizeLogin: (input: LoginGrantInput) => Promise<LoginGrant>;
     };
+    readonly billing: {
+        get: () => Promise<Wallet>;
+        update: (input: BillingSettings) => Promise<Wallet>;
+        ledger: (before?: number) => Promise<LedgerPage>;
+        topups: () => Promise<Topup[]>;
+        topup: (input: TopupInput, idempotencyKey: string) => Promise<Topup>;
+        refunds: () => Promise<Refund[]>;
+        refund: (input: RefundInput, idempotencyKey: string) => Promise<Refund>;
+        sync: (input: SyncPayment) => Promise<Wallet>;
+    };
+    readonly environments: {
+        list: () => Promise<EnvironmentCatalog>;
+    };
     /** Key management requires an account session; workload API keys cannot create credentials. */
     readonly keys: {
         list: () => Promise<ApiKey[]>;

package/dist/index.js

@@ -1,10 +1,25 @@
 export * from "@aexhq/brain";
 import { Brain } from "@aexhq/brain";
+function nonnegativeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new TypeError(`${name} must be a nonnegative safe integer`);
+}
 export class Aex extends Brain {
-    constructor({ apiKey, accountToken, ...options }) {
+    maxCostMicroUsd;
+    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }) {
         if (!(apiKey || accountToken) || (apiKey && accountToken))
             throw new TypeError("one apiKey or accountToken is required");
         super({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken });
+        if (maxCostMicroUsd !== undefined)
+            nonnegativeInteger(maxCostMicroUsd, "maxCostMicroUsd");
+        this.maxCostMicroUsd = maxCostMicroUsd;
+    }
+    /** The ceiling applies separately to each admitted operation. Model BYOK charges remain with the provider. */
+    request(method, path, body, idempotencyKey, contentType = "application/json", signal, extraHeaders) {
+        const headers = new Headers(extraHeaders);
+        if (this.maxCostMicroUsd !== undefined && !headers.has("x-aex-max-cost-micro-usd"))
+            headers.set("x-aex-max-cost-micro-usd", String(this.maxCostMicroUsd));
+        return super.request(method, path, body, idempotencyKey, contentType, signal, headers);
     }
     static exchangeLogin(input, options = {}) {
         return new Brain({ baseUrl: "https://api.aex.dev", ...options }).request("POST", "/v1/auth/exchange", input);
@@ -13,7 +28,18 @@ export class Aex extends Brain {
         upload: (sessionId, bytes, options) => {
             if (options.expiresAt !== undefined && (!Number.isSafeInteger(options.expiresAt) || options.expiresAt <= 0))
                 throw new TypeError("expiresAt must be positive Unix seconds");
-            return this.request("POST", `/v1/sessions/${encodeURIComponent(sessionId)}/attachments`, bytes, options.idempotencyKey, options.contentType, options.signal, options.expiresAt === undefined ? undefined : { "x-aex-expires-at": String(options.expiresAt) });
+            const headers = {};
+            if (options.expiresAt !== undefined)
+                headers["x-aex-expires-at"] = String(options.expiresAt);
+            if (options.maxCostMicroUsd !== undefined) {
+                nonnegativeInteger(options.maxCostMicroUsd, "maxCostMicroUsd");
+                headers["x-aex-max-cost-micro-usd"] = String(options.maxCostMicroUsd);
+            }
+            if (options.downloadBudgetBytes !== undefined) {
+                nonnegativeInteger(options.downloadBudgetBytes, "downloadBudgetBytes");
+                headers["x-aex-download-budget-bytes"] = String(options.downloadBudgetBytes);
+            }
+            return this.request("POST", `/v1/sessions/${encodeURIComponent(sessionId)}/attachments`, bytes, options.idempotencyKey, options.contentType, options.signal, headers);
         },
         delete: (sessionId, id) => this.request("DELETE", `/v1/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(id)}`),
     };
@@ -23,6 +49,23 @@ export class Aex extends Brain {
         logout: () => this.request("DELETE", "/v1/account/session"),
         authorizeLogin: (input) => this.request("POST", "/v1/auth/grants", input),
     };
+    billing = {
+        get: () => this.request("GET", "/v1/billing"),
+        update: (input) => this.request("PUT", "/v1/billing", input),
+        ledger: (before) => {
+            if (before !== undefined)
+                nonnegativeInteger(before, "before");
+            return this.request("GET", `/v1/billing/ledger${before === undefined ? "" : `?before=${before}`}`);
+        },
+        topups: () => this.request("GET", "/v1/billing/topups"),
+        topup: (input, idempotencyKey) => this.request("POST", "/v1/billing/topups", input, idempotencyKey),
+        refunds: () => this.request("GET", "/v1/billing/refunds"),
+        refund: (input, idempotencyKey) => this.request("POST", "/v1/billing/refunds", input, idempotencyKey),
+        sync: (input) => this.request("POST", "/v1/billing/sync", input),
+    };
+    environments = {
+        list: () => this.request("GET", "/v1/environments"),
+    };
     /** Key management requires an account session; workload API keys cannot create credentials. */
     keys = {
         list: () => this.request("GET", "/v1/keys"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.75.3",
+  "version": "0.77.0",
   "description": "Aex accounts and hosted sessions using the Brain SDK",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
     "tag": "next"
   },
   "dependencies": {
-    "@aexhq/brain": "0.24.4"
+    "@aexhq/brain": "0.27.0"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",