@aexhq/sdk 0.84.1 → 0.86.0

package/README.md

@@ -8,14 +8,14 @@ tools, send messages, and read saved conversations without operating a Brain ser
 Create a key in the [dashboard](https://aex.dev/dashboard). With Node.js 22 or newer, install:
 
 ```sh
-npm install @aexhq/sdk@0.84.1 @aexhq/agentloop-pi@7.2.3 zod@4.4.3
+npm install @aexhq/sdk@0.86.0 @aexhq/agentloop-pi@7.3.0 zod@4.4.3
 ```
 
 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 { Aex, tool } from "@aexhq/sdk";
 import { pi } from "@aexhq/agentloop-pi";
 import { z } from "zod";
 
@@ -27,22 +27,22 @@ const lookupOrder = tool({
 });
 
 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();
+aex.sessions.create({
+  model: { provider: "openai", name: "gpt-4.1-mini", apiKey: process.env.OPENAI_API_KEY },
+  agentloop: pi(),
+  tools: [lookupOrder()],
+}).then(async session => {
+  const after = session.state.lastSequence;
+  await session.send("Look up order A-1001. Has it shipped?");
+  for await (const event of session.events(after)) {
+    if (event.type === "turn_failed") throw new Error(JSON.stringify(event.data));
   }
-} finally {
-  await aex.close();
-}
+  console.log(JSON.stringify(await session.transcript(), null, 2));
+  console.log("Session:", session.id);
+}).catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});
 ```
 
 The transcript includes an order lookup and the agent's answer. The lookup function runs in your
@@ -60,13 +60,16 @@ The SDK uses Brain's session API and extension helpers. You can import `tool`, `
 - [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.
 
-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.
+Use `ctx.finish(value)` to complete a tool. The shared tool connection suspends after five
+idle seconds and reconnects before the same live client starts more work. Configure
+`connectionIdleTimeoutMs` on `new Aex(...)`; use `0` when other callers or future autonomous
+events must reach these tools. History reads do not reconnect, and event subscriptions remain
+caller-owned. Explicit `aex.close()` permanently disposes of the client while keeping stored sessions.
 
 ## Structured output
 
-Ask for a typed application answer on one send. Before ending the session, pass a Zod
-schema alongside the message:
+Ask for a typed application answer on one send. Inside the callback, pass a Zod schema
+alongside the message:
 
 ```ts
 const answer = await session.send("Return the order status", {
@@ -119,7 +122,7 @@ correction. It supports JSON Schema, not arbitrary local Zod refinements or tran
 Brain SDK 0.34 removes typed sends and the corresponding types and errors. Aex SDK 0.84
 owns them. Existing Aex `send(..., { output })` calls keep the same syntax and behavior.
 Import `StructuredSendOptions` and `StructuredOutputError` from `@aexhq/sdk`.
-Use Pi/Codex 7.2.3 and extension packages pinned to Brain 0.34 with this SDK.
+Use Pi 7.3.0, Codex 7.2.5 and extension packages pinned to Brain 0.36.0 with this SDK.
 Mixing exact Brain dependency versions creates different TypeScript extension brands.
 
 An existing standalone Brain handle can use Aex's policy without changing servers:
@@ -159,7 +162,9 @@ independent request within the invocation's lifetime and the session's model aut
 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
+[HTTP tools](https://aex.dev/docs/application). 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.
+
+Choose [clientBrowser](https://aex.dev/docs/client-browser) for the user's connected tab, or [Application](https://aex.dev/docs/application) for a deployed backend. Both use `aex.sessions.create()` and ordinary Tool declarations.

package/dist/application.d.ts

@@ -0,0 +1,2 @@
+import { type CreateSessionOptions } from "@aexhq/brain";
+export declare function composeApplication(options: CreateSessionOptions, baseUrl: string): CreateSessionOptions;

package/dist/application.js

@@ -0,0 +1,12 @@
+import { inspectEnvironment, inspectTool } from "@aexhq/brain";
+import { applicationTool } from "@aexhq/env-http";
+export function composeApplication(options, baseUrl) {
+    const url = new URL("/environments/application", baseUrl).href;
+    return { ...options, tools: options.tools?.map(placed => {
+            const tool = inspectTool(placed);
+            const environment = inspectEnvironment(tool.environment);
+            if (environment.driver.driver !== "http" || environment.driver.url !== url)
+                return placed;
+            return applicationTool(placed, { env: tool.environment });
+        }) };
+}

package/dist/generated.d.ts

@@ -29,6 +29,38 @@ export type SyncPayment = {
 };
 export interface AexContracts {
 }
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "ClientHost".
+ */
+export interface ClientHost {
+    hostId: string;
+    token: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "ClientAccess".
+ */
+export interface ClientAccess {
+    credentials: ClientHost;
+    expires_at: number;
+    id: string;
+    token: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "ClientGrantInput".
+ */
+export interface ClientGrantInput {
+    expires_at: number;
+    origin: string;
+    /**
+     * The prepared Brain request. Credentials remain on the server.
+     */
+    session: {
+        [k: string]: unknown;
+    };
+}
 /**
  * This interface was referenced by `AexContracts`'s JSON-Schema
  * via the `definition` "HttpCatalog".

package/dist/index.d.ts

@@ -3,9 +3,10 @@ export type * from "./generated.js";
 export { AexSessionHandle } from "./session.js";
 export { StructuredOutputError } from "./structured-output.js";
 export type { StructuredSendOptions } from "./structured-output.js";
-import { Brain, type BrainOptions } from "@aexhq/brain";
+import { application } from "@aexhq/env-http";
+import { Brain, type BrainOptions, type CreateSessionOptions, type OperationOptions, type ModelSelection } from "@aexhq/brain";
 import { AexSessionHandle } from "./session.js";
-import type { EnvironmentCatalog, TokenUsage } from "./generated.js";
+import type { ClientAccess, 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;
@@ -15,16 +16,27 @@ export type AexOptions = AexConnection & {
 } & ({
     apiKey: string;
     accountToken?: never;
+    clientAccess?: never;
 } | {
     accountToken: string;
     apiKey?: never;
+    clientAccess?: never;
+} | {
+    clientAccess: ClientAccess;
+    apiKey?: never;
+    accountToken?: never;
 });
+export type AexSessionOptions = Omit<CreateSessionOptions, "model"> & {
+    model: ModelSelection | Omit<ModelSelection, "apiKey">;
+};
 export declare class Aex {
     private readonly client;
-    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }: AexOptions);
+    private readonly clientAccess?;
+    constructor({ apiKey, accountToken, clientAccess, maxCostMicroUsd, ...options }: AexOptions);
+    private composition;
     get baseUrl(): string;
     readonly sessions: Readonly<{
-        create: (options: import("@aexhq/brain").CreateSessionOptions, operation?: import("@aexhq/brain").OperationOptions | undefined) => Promise<AexSessionHandle>;
+        create: (options: AexSessionOptions, operation?: OperationOptions) => Promise<AexSessionHandle>;
         get: (sessionId: string, options?: {
             tools?: readonly import("@aexhq/brain").PlacedTool[];
         } | undefined) => Promise<AexSessionHandle>;
@@ -77,7 +89,18 @@ export declare class Aex {
         refund: (input: RefundInput, idempotencyKey: string) => Promise<Refund>;
         sync: (input: SyncPayment) => Promise<Wallet>;
     };
+    readonly clients: {
+        grant: ({ session, origin, expiresAt }: {
+            session: CreateSessionOptions;
+            origin: string;
+            expiresAt?: number;
+        }) => Promise<ClientAccess>;
+        revoke: (id: string) => Promise<void>;
+    };
     readonly environments: {
+        application: (options: Omit<Parameters<typeof application>[0], "url" | "credential"> & {
+            credential?: string;
+        }) => import("@aexhq/brain").Environment;
         http: () => Promise<import("./generated.js").HttpCatalog>;
         list: () => Promise<EnvironmentCatalog>;
     };

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "@aexhq/brain";
 export { AexSessionHandle } from "./session.js";
 export { StructuredOutputError } from "./structured-output.js";
+import { application } from "@aexhq/env-http";
+import { composeApplication } from "./application.js";
 import { Brain } from "@aexhq/brain";
 import { AexSessionHandle } from "./session.js";
 function nonnegativeInteger(value, name) {
@@ -25,14 +27,25 @@ class HostedBrain extends Brain {
 }
 export class Aex {
     client;
-    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }) {
-        if (!(apiKey || accountToken) || (apiKey && accountToken))
-            throw new TypeError("one apiKey or accountToken is required");
-        this.client = new HostedBrain({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken, maxCostMicroUsd });
+    clientAccess;
+    constructor({ apiKey, accountToken, clientAccess, maxCostMicroUsd, ...options }) {
+        if ([apiKey, accountToken, clientAccess].filter(Boolean).length !== 1)
+            throw new TypeError("one apiKey, accountToken or clientAccess is required");
+        this.clientAccess = clientAccess;
+        this.client = new HostedBrain({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken ?? clientAccess?.token,
+            ...(clientAccess && { credentials: clientAccess.credentials }), maxCostMicroUsd });
+    }
+    composition(options) {
+        if (this.clientAccess && "apiKey" in options.model)
+            throw new TypeError("client access uses server-side model credentials; omit apiKey");
+        const model = this.clientAccess ? { ...options.model, apiKey: this.clientAccess.token } : options.model;
+        if (!("apiKey" in model) || typeof model.apiKey !== "string")
+            throw new TypeError("server-side sessions require a model apiKey");
+        return composeApplication({ ...options, model: { ...model, apiKey: model.apiKey } }, this.baseUrl);
     }
     get baseUrl() { return this.client.baseUrl; }
     sessions = Object.freeze({
-        create: async (...args) => new AexSessionHandle(await this.client.sessions.create(...args)),
+        create: async (options, operation) => new AexSessionHandle(await this.client.sessions.create(this.composition(options), operation)),
         get: async (...args) => new AexSessionHandle(await this.client.sessions.get(...args)),
         list: () => this.client.sessions.list(),
     });
@@ -104,7 +117,20 @@ export class Aex {
         refund: (input, idempotencyKey) => this.request("POST", "/v1/billing/refunds", input, idempotencyKey),
         sync: (input) => this.request("POST", "/v1/billing/sync", input),
     };
+    clients = {
+        grant: async ({ session, origin, expiresAt = Math.floor(Date.now() / 1000) + 3600 }) => {
+            if (this.clientAccess)
+                throw new TypeError("client grants require a backend API key");
+            const prepared = await this.client.sessions.prepare(this.composition(session), "authorized-client");
+            return this.request("POST", "/v1/clients", { origin, expires_at: expiresAt, session: prepared });
+        },
+        revoke: (id) => this.request("DELETE", `/v1/clients/${encodeURIComponent(id)}`),
+    };
     environments = {
+        application: (options) => application({
+            ...options, credential: options.credential ?? this.clientAccess?.token ?? "",
+            url: new URL("/environments/application", this.baseUrl).href,
+        }),
         http: () => this.request("GET", "/v1/environments/http"),
         list: () => this.request("GET", "/v1/environments"),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.84.1",
+  "version": "0.86.0",
   "description": "Aex accounts and hosted sessions using the Brain SDK",
   "license": "MIT",
   "type": "module",
@@ -28,8 +28,9 @@
     "tag": "next"
   },
   "dependencies": {
-    "@aexhq/brain": "0.34.1",
-    "zod": "4.4.3"
+    "@aexhq/brain": "0.36.0",
+    "zod": "4.4.3",
+    "@aexhq/env-http": "0.3.1"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",