@aexhq/sdk 0.84.0 → 0.85.0

package/README.md

@@ -8,7 +8,7 @@ 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.0 @aexhq/agentloop-pi@7.2.2 zod@4
+npm install @aexhq/sdk@0.85.0 @aexhq/agentloop-pi@7.2.4 zod@4.4.3
 ```
 
 Set `AEX_API_KEY` and `OPENAI_API_KEY` in your server environment. Save as `order.mjs` and
@@ -119,7 +119,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.2 and extension packages pinned to Brain 0.34 with this SDK.
+Use Pi/Codex 7.2.4 and extension packages pinned to Brain 0.35.1 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 +159,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.0",
+  "version": "0.85.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.0",
-    "zod": "4.4.3"
+    "@aexhq/brain": "0.35.1",
+    "zod": "4.4.3",
+    "@aexhq/env-http": "0.3.0"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",