@aexhq/sdk 0.79.0 → 0.81.0

package/README.md

@@ -1,125 +1,93 @@
 # 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.
+Run AI agents on [Aex](https://aex.dev) from JavaScript or TypeScript. Connect your model and
+tools, send messages, and read saved conversations without operating a Brain server.
 
-`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.
+## Get started
 
-Install `@aexhq/sdk`. Create an API key at https://aex.dev/dashboard.
+Create a key in the [dashboard](https://aex.dev/dashboard). With Node.js 22 or newer, install:
 
-```ts
-import { Aex, agentloop, brainEnv, component, hostEnv, tool } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-console.log(await aex.account.get());
+```sh
+npm install @aexhq/sdk@0.81.0 @aexhq/agentloop-pi@7.1.1 zod@4
 ```
 
-`Aex` extends the pinned Brain client. Its sessions, registration, Events, Components and
-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.
-
-Put client use, including session creation, inside `try/finally` and `await aex.close()` in
-`finally`. The client retains one shared host connection until close, even if creation fails.
-Close releases client I/O and local handlers while retaining stored sessions. Use
-`session.interrupt()` to stop the current turn, `session.end()` to finish the conversation,
-and `session.delete()` to remove an ended or failed session. `interrupt()` replaces SDK
-`cancel()`; the HTTP route is unchanged. See the [session example](../../examples/session.mjs).
-
-Tool schemas describe accepted inputs. Defaulted arguments are optional; Zod applies defaults
-and transforms before the handler. Ordinary objects strip extra properties and strict objects
-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.
-
-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
-`cancelled`, and missing reliable results after dispatch produce `unknown`. All are failed Tool
-results. Timeout and cancellation do not promise rollback. See
-[the full return contract](https://aex.dev/brain/docs/guides/write-a-tool#return-values-and-outcomes).
-
-`@aexhq/tools-mcp` runs selected MCP Tools in your application host, preserving structured failures
-and original JSON Schema constraints. The official Docker and browser HTTP Environments target
-standalone Brain and require operator deployment. See [official extensions](https://github.com/aexhq/extensions).
-
-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. `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.
-
-`account.get()` and `account.usage()` accept a workload API key. `keys` management requires
-an authenticated account session and is normally performed in the dashboard. API keys do
-not grant authority to create more credentials. New key secrets are returned once.
-
-## 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
-by default; set zero to disable retries. Ordinary sends keep returning session state;
-`idle` alone does not mean the turn succeeded. No terminal Tool is needed for structured output.
-
-See the [executable example](https://github.com/aexhq/aex/blob/main/examples/structured-output.mjs)
-and [full contract](https://aex.dev/brain/docs/guides/structured-output).
-Exhaustion throws `StructuredOutputError` with `attempts`, `lastOutput`, and `issues`.
-Retries run in your client and are ordinary turns with the session's existing tools.
-Use exclusive ownership of sends during the operation. An optional top-level
-`signal` cancels the active turn and stops corrections. Raw attempts remain visible
-in history and streams; validation does not change the Agentloop or provider format.
-
-## Account management
-
-Use an account session obtained through browser login for account management. Workload
-API keys remain scoped to runtime operations and read-only account/usage access.
-
-```ts
-const account = new Aex({ accountToken: process.env.AEX_ACCOUNT_TOKEN! });
-await account.keys.list();
-const issued = await account.keys.create({ name: "My app" });
-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();
+Set `AEX_API_KEY` and `OPENAI_API_KEY` in your server environment. Save as `order.mjs` and
+run `node order.mjs`:
+
+```js
+import { Aex, brainEnv, tool } from "@aexhq/sdk";
+import { pi } from "@aexhq/agentloop-pi";
+import { z } from "zod";
+
+const lookupOrder = tool({
+  name: "lookup_order",
+  description: "Look up an order by id.",
+  input: z.object({ id: z.string() }),
+  run: ({ id }, ctx) => ctx.finish({ id, status: "shipped" }),
+});
+
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY });
+try {
+  const session = await aex.sessions.create({
+    model: { provider: "openai", name: "gpt-4.1-mini", apiKey: process.env.OPENAI_API_KEY },
+    agentloop: pi({ env: brainEnv({ name: "brain" }) }),
+    tools: [lookupOrder()],
+  });
+  try {
+    await session.send("Look up order A-1001. Has it shipped?");
+    console.log(JSON.stringify(await session.transcript(), null, 2));
+    console.log("Session:", session.id);
+  } finally {
+    await session.end();
+  }
+} finally {
+  await aex.close();
+}
 ```
 
-`account.account.authorizeLogin({code_challenge, redirect_uri})` and
-`Aex.exchangeLogin({code, code_verifier, redirect_uri})` expose the shared HTTP login
-contract for clients. The `@aexhq/cli` package handles opening the browser, PKCE,
-loopback callback and local credential storage.
+The transcript includes an order lookup and the agent's answer. The lookup function runs in your
+process; keep it connected while the agent needs that tool. The [quickstart](https://aex.dev/docs)
+explains setup and where other tools run.
+
+## Sessions and tools
+
+The SDK uses Brain's session API and extension helpers. You can import `tool`, `agentloop`,
+`brainEnv`, `hostEnv`, `component` and `environment` from `@aexhq/sdk`.
+
+- [Sessions](https://aex.dev/brain/docs/concepts/sessions): send, submit, stream, reconnect and stop.
+- [Tools](https://aex.dev/brain/docs/guides/write-a-tool): application functions and packaged tools.
+- [Structured output](https://aex.dev/brain/docs/guides/structured-output): validated JSON answers.
+- [Managed environments](https://github.com/aexhq/aex/blob/main/docs/environments.md): hosted tools and workspaces.
+- [Attachments](https://github.com/aexhq/aex/blob/main/docs/attachments.md): upload images and PDFs.
 
-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.
+Use `ctx.finish(value)` to complete a tool. Use `aex.close()` in `finally` to close client
+connections. Closing the client keeps stored sessions; tools in your process still require it.
+
+## Account and usage
+
+```js
+console.log(await aex.account.get());
+console.log(await aex.account.usage());
+console.log(await aex.account.modelUsage(sessionId));
+console.log(await aex.environments.list());
+```
 
-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).
+Run these before closing the client. Workload keys can read account and usage information.
+Creating keys, accepting prices, topups and refunds require an account login; use the
+[dashboard](https://aex.dev/dashboard) or [CLI](https://www.npmjs.com/package/@aexhq/cli).
+
+See the [billing guide](https://github.com/aexhq/aex/blob/main/docs/billing.md) for account API
+methods and `maxCostMicroUsd`, the ceiling for a resource operation. Aex spending controls do
+not cap your separate model-provider bill.
+
+Inline Tools default to the process registering them. Published libraries use Brain's generated
+bindings and the selected Environment's prepared runtime. `ctx.finish(value, { content: summary })`
+retains the structured result while offering concise model text. `ctx.model({ messages })` runs an
+independent request within the invocation's lifetime and the session's model authority; hosted
+usage and spending controls include those requests. The Agentloop owns the shared conversation.
+
+Connect short application functions through an authenticated HTTP route with
+[HTTP tools](https://github.com/aexhq/aex/blob/main/docs/http-tools.md). Submit a turn, close the
+request and read its committed outcome later. Desktop apps can use
+[upload-only grants](https://github.com/aexhq/aex/blob/main/docs/attachments.md#upload-from-a-desktop-without-an-account-key)
+without receiving an account credential.

package/dist/generated.d.ts

@@ -29,6 +29,58 @@ export type SyncPayment = {
 };
 export interface AexContracts {
 }
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "HttpCatalog".
+ */
+export interface HttpCatalog {
+    bindings: {
+        [k: string]: number;
+    };
+    driver_url: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "HttpSelection".
+ */
+export interface HttpSelection {
+    binding: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "UploadGrantInput".
+ */
+export interface UploadGrantInput {
+    bytes: number;
+    content_type: string;
+    expires_at?: number | null;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "UploadGrant".
+ */
+export interface UploadGrant {
+    attachment_expires_at: number;
+    bytes: number;
+    content_type: string;
+    expires_at: number;
+    id: string;
+    token: string;
+    upload_url: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "AttachmentLimits".
+ */
+export interface AttachmentLimits {
+    bytes_per_account: number;
+    count_per_account: number;
+    max_bytes: number;
+    region: string;
+    session_retention_secs: number;
+    ttl_secs: number;
+    upload_grant_secs: number;
+}
 /**
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "Attachment".

package/dist/index.d.ts

@@ -22,6 +22,13 @@ export declare class Aex extends Brain {
     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: {
+        limits: () => Promise<import("./generated.js").AttachmentLimits>;
+        grant: (sessionId: string, input: import("./generated.js").UploadGrantInput, options: {
+            idempotencyKey: string;
+            downloadBudgetBytes?: number;
+            maxCostMicroUsd?: number;
+        }) => Promise<import("./generated.js").UploadGrant>;
+        get: (sessionId: string, id: string) => Promise<Attachment>;
         upload: (sessionId: string, bytes: Uint8Array, options: {
             contentType: string;
             expiresAt?: number;
@@ -50,6 +57,7 @@ export declare class Aex extends Brain {
         sync: (input: SyncPayment) => Promise<Wallet>;
     };
     readonly environments: {
+        http: () => Promise<import("./generated.js").HttpCatalog>;
         list: () => Promise<EnvironmentCatalog>;
     };
     /** Key management requires an account session; workload API keys cannot create credentials. */

package/dist/index.js

@@ -25,6 +25,20 @@ export class Aex extends Brain {
         return new Brain({ baseUrl: "https://api.aex.dev", ...options }).request("POST", "/v1/auth/exchange", input);
     }
     attachments = {
+        limits: () => this.request("GET", "/v1/attachments/limits"),
+        grant: (sessionId, input, options) => {
+            const headers = new Headers();
+            if (options.downloadBudgetBytes !== undefined) {
+                nonnegativeInteger(options.downloadBudgetBytes, "downloadBudgetBytes");
+                headers.set("x-aex-download-budget-bytes", String(options.downloadBudgetBytes));
+            }
+            if (options.maxCostMicroUsd !== undefined) {
+                nonnegativeInteger(options.maxCostMicroUsd, "maxCostMicroUsd");
+                headers.set("x-aex-max-cost-micro-usd", String(options.maxCostMicroUsd));
+            }
+            return this.request("POST", `/v1/sessions/${encodeURIComponent(sessionId)}/attachment-grants`, input, options.idempotencyKey, "application/json", undefined, headers);
+        },
+        get: (sessionId, id) => this.request("GET", `/v1/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(id)}`),
         upload: (sessionId, bytes, options) => {
             if (options.expiresAt !== undefined && (!Number.isSafeInteger(options.expiresAt) || options.expiresAt <= 0))
                 throw new TypeError("expiresAt must be positive Unix seconds");
@@ -65,6 +79,7 @@ export class Aex extends Brain {
         sync: (input) => this.request("POST", "/v1/billing/sync", input),
     };
     environments = {
+        http: () => this.request("GET", "/v1/environments/http"),
         list: () => this.request("GET", "/v1/environments"),
     };
     /** Key management requires an account session; workload API keys cannot create credentials. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.79.0",
+  "version": "0.81.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.29.0"
+    "@aexhq/brain": "0.31.0"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",