@aexhq/sdk 0.77.0 → 0.79.0

package/README.md

@@ -21,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.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
+extension builders are Brain's implementations. SDK 0.79 uses Brain SDK 0.29 and Pi/Codex
+7.0.1. 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.
@@ -39,7 +39,16 @@ and transforms before the handler. Ordinary objects strip extra properties and s
 reject them. Pi dispatches in parallel; coordinate shared resources in their owning Tool or
 Environment. The official loops explain unanswered calls after interruption without replaying them.
 
-Host Tools return ordinary successful output or a Brain `Outcome` directly. Structured errors retain
+Tool return and completion are separate. `return ctx.finish(value)` emits an optional result
+and finishes an ordinary Tool. Returning a value alone emits it and releases the synchronous
+caller; the Tool remains open for `ctx.emitResult(value)` and `ctx.finish()` afterward.
+Background observations wake the Agentloop, which chooses whether to call the model and what
+to put in its transcript. Results and finish always enter the journal. Keep the host client
+connected until all its Tools finish. Interrupt cancels unfinished Tools even while idle.
+A forgotten finish stays open until the original deadline, cancellation or Environment loss;
+without a deadline it can remain open indefinitely.
+
+Host Tools accept ordinary successful output or a Brain `Outcome` directly. Structured errors retain
 code, message, retryable and details. The top-level statuses `ok`, `error`, `timeout`, `cancelled`
 and `unknown` declare outcomes; malformed envelopes fail validation, and only successful values
 pass through the output schema. Tool deadlines produce `timeout`, explicit cancellation produces
@@ -99,6 +108,7 @@ await account.keys.update(issued.key.id, { name: "Renamed app" });
 await account.keys.delete(issued.key.id);
 await account.account.get(); // includes billing status and limits
 await account.account.usage();
+await account.account.modelUsage(sessionId);
 await account.account.logout();
 ```
 
@@ -108,3 +118,8 @@ contract for clients. The `@aexhq/cli` package handles opening the browser, PKCE
 loopback callback and local credential storage.
 
 Image and PDF uploads use the [attachment API](../../docs/attachments.md). `models(provider?)` forwards Brain's catalogue unchanged, with models.dev metadata when known. Brain validates model selections; Aex has no separate model allowlist.
+
+Token usage reports separate recorded quantities and hosting charges from pending estimates.
+Foreground and background calls use the same meter. Spending control is asynchronous;
+`maxCostMicroUsd` remains a resource-operation ceiling, not a model token budget.
+Your provider separately bills your model key. See [billing](../../docs/billing.md).

package/dist/generated.d.ts

@@ -63,6 +63,18 @@ export interface Limits {
     upstream_timeout_secs: number;
     usage_max_age_secs: number;
 }
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "TokenUsage".
+ */
+export interface TokenUsage {
+    charged_micro_usd: number;
+    pending_estimate_micro_usd: number;
+    rated_micro_usd: number;
+    reported_input_tokens: number;
+    reported_output_tokens: number;
+    unmeasured_calls: number;
+}
 /**
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "Usage".
@@ -72,6 +84,7 @@ export interface Usage {
     attachment_bytes: number;
     attachments: number;
     measured_at?: number | null;
+    model: TokenUsage;
     retained_bytes: number;
     sessions: number;
 }
@@ -155,6 +168,7 @@ export interface Pricebook {
     rates: {
         attachment_byte_secs?: Rate;
         egress_bytes?: Rate;
+        model_tokens?: Rate;
         sandbox_ms?: Rate;
         turn_ms?: Rate;
     };
@@ -175,12 +189,14 @@ export interface Rate {
  */
 export interface Wallet {
     accepted_pricebook?: string | null;
+    accepted_rates?: Pricebook | null;
     available_micro_usd: number;
     balance_micro_usd: number;
     currency: string;
     mode: BillingMode;
     offered_pricebook?: Pricebook | null;
     payment_mode?: Mode | null;
+    pending_estimate_micro_usd: number;
     reserved_micro_usd: number;
     spend_limit_micro_usd?: number | null;
     spent_this_month_micro_usd: number;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from "@aexhq/brain";
 export type * from "./generated.js";
 import { Brain, type BrainOptions } from "@aexhq/brain";
-import type { EnvironmentCatalog } from "./generated.js";
+import type { EnvironmentCatalog, TokenUsage } 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;
@@ -18,7 +18,7 @@ export type AexOptions = AexConnection & {
 export declare class Aex extends Brain {
     private readonly maxCostMicroUsd?;
     constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }: AexOptions);
-    /** The ceiling applies separately to each admitted operation. Model BYOK charges remain with the provider. */
+    /** Resource and legacy turn reservations use this ceiling; token hosting follows the account limit. */
     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: {
@@ -35,6 +35,7 @@ export declare class Aex extends Brain {
     readonly account: {
         get: () => Promise<Account>;
         usage: () => Promise<Usage>;
+        modelUsage: (sessionId: string) => Promise<TokenUsage>;
         logout: () => Promise<void>;
         authorizeLogin: (input: LoginGrantInput) => Promise<LoginGrant>;
     };

package/dist/index.js

@@ -14,7 +14,7 @@ export class Aex extends Brain {
             nonnegativeInteger(maxCostMicroUsd, "maxCostMicroUsd");
         this.maxCostMicroUsd = maxCostMicroUsd;
     }
-    /** The ceiling applies separately to each admitted operation. Model BYOK charges remain with the provider. */
+    /** Resource and legacy turn reservations use this ceiling; token hosting follows the account limit. */
     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"))
@@ -46,6 +46,7 @@ export class Aex extends Brain {
     account = {
         get: () => this.request("GET", "/v1/account"),
         usage: () => this.request("GET", "/v1/usage"),
+        modelUsage: (sessionId) => this.request("GET", `/v1/usage/${encodeURIComponent(sessionId)}`),
         logout: () => this.request("DELETE", "/v1/account/session"),
         authorizeLogin: (input) => this.request("POST", "/v1/auth/grants", input),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.77.0",
+  "version": "0.79.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.27.0"
+    "@aexhq/brain": "0.29.0"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",