@aexhq/sdk 0.73.0 → 0.75.0

package/README.md

@@ -10,11 +10,24 @@ 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.73 uses Brain SDK 0.22 and Pi/Codex/Tools
-5.1. Brain 0.22 retains the existing Wasm interface. Components and session configurations are
-not migrated automatically. See https://aex.dev/docs
+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
+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.
+
 Host Tools return 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
@@ -43,7 +56,8 @@ not grant authority to create more credentials. New key secrets are returned onc
 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.
+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).
@@ -73,3 +87,5 @@ await account.account.logout();
 `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.
+
+Image and PDF uploads use the [attachment API](../../docs/attachments.md). `models(provider?)` exposes only the configured hosted model choices, with models.dev metadata when known.

package/dist/generated.d.ts

@@ -1,3 +1,4 @@
+import type { Media } from "@aexhq/brain";
 /**
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "Billing".
@@ -5,6 +6,15 @@
 export type Billing = "preview_customer_model_keys";
 export interface AexContracts {
 }
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Attachment".
+ */
+export interface Attachment {
+    expires_at: number;
+    id: string;
+    media: Media;
+}
 /**
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "Limits".
@@ -36,6 +46,8 @@ export interface Limits {
  */
 export interface Usage {
     active_turns: number;
+    attachment_bytes: number;
+    attachments: number;
     measured_at?: number | null;
     retained_bytes: number;
     sessions: number;

package/dist/generated.js

@@ -1,2 +1 @@
-/* Generated from aex-server schemas. */
 export {};

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 { Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession } from "./generated.js";
+import type { Attachment, Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession } from "./generated.js";
 export type AexConnection = Omit<BrainOptions, "token" | "baseUrl"> & {
     baseUrl?: string;
 };
@@ -15,6 +15,15 @@ export type AexOptions = AexConnection & ({
 export declare class Aex extends Brain {
     constructor({ apiKey, accountToken, ...options }: AexOptions);
     static exchangeLogin(input: LoginExchange, options?: AexConnection): Promise<AccountSession>;
+    readonly attachments: {
+        upload: (sessionId: string, bytes: Uint8Array, options: {
+            contentType: string;
+            expiresAt?: number;
+            idempotencyKey: string;
+            signal?: AbortSignal;
+        }) => Promise<Attachment>;
+        delete: (sessionId: string, id: string) => Promise<void>;
+    };
     readonly account: {
         get: () => Promise<Account>;
         usage: () => Promise<Usage>;

package/dist/index.js

@@ -9,6 +9,14 @@ export class Aex extends Brain {
     static exchangeLogin(input, options = {}) {
         return new Brain({ baseUrl: "https://api.aex.dev", ...options }).request("POST", "/v1/auth/exchange", input);
     }
+    attachments = {
+        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) });
+        },
+        delete: (sessionId, id) => this.request("DELETE", `/v1/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(id)}`),
+    };
     account = {
         get: () => this.request("GET", "/v1/account"),
         usage: () => this.request("GET", "/v1/usage"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.73.0",
+  "version": "0.75.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.22.0"
+    "@aexhq/brain": "0.24.0"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",