@aexhq/sdk 0.86.0 → 0.87.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.86.0 @aexhq/agentloop-pi@7.3.0 zod@4.4.3
+npm install @aexhq/sdk@0.87.0 @aexhq/agentloop-pi@8.0.0 zod@4.4.3
 ```
 
 Set `AEX_API_KEY` and `OPENAI_API_KEY` in your server environment. Save as `order.mjs` and
@@ -52,7 +52,7 @@ 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`.
+`brainEnv`, `hostEnv`, `component`, `program` 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.
@@ -122,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 7.3.0, Codex 7.2.5 and extension packages pinned to Brain 0.36.0 with this SDK.
+Use Pi 8.0.0, Codex 8.0.0 and extension packages pinned to Brain 0.37.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:
@@ -168,3 +168,7 @@ request and read its committed outcome later. Desktop apps can use
 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.
+
+The SDK prepares hosted code during session setup. To do that earlier and reuse it across
+sessions, call `const loop = await aex.prepare(pi())` during startup, then use `agentloop: loop`.
+See [Environment preparation](https://github.com/aexhq/aex/blob/main/docs/environments.md#prepare-hosted-code).

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { AexSessionHandle } from "./session.js";
 export { StructuredOutputError } from "./structured-output.js";
 export type { StructuredSendOptions } from "./structured-output.js";
 import { application } from "@aexhq/env-http";
-import { Brain, type BrainOptions, type CreateSessionOptions, type OperationOptions, type ModelSelection } from "@aexhq/brain";
+import { Brain, type PlacedAgentloop, type PlacedTool, type BrainOptions, type CreateSessionOptions, type OperationOptions, type ModelSelection } from "@aexhq/brain";
 import { AexSessionHandle } from "./session.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";
@@ -34,11 +34,12 @@ export declare class Aex {
     private readonly clientAccess?;
     constructor({ apiKey, accountToken, clientAccess, maxCostMicroUsd, ...options }: AexOptions);
     private composition;
+    private preparedComposition;
     get baseUrl(): string;
     readonly sessions: Readonly<{
         create: (options: AexSessionOptions, operation?: OperationOptions) => Promise<AexSessionHandle>;
         get: (sessionId: string, options?: {
-            tools?: readonly import("@aexhq/brain").PlacedTool[];
+            tools?: readonly PlacedTool[];
         } | undefined) => Promise<AexSessionHandle>;
         list: () => ReturnType<Brain["sessions"]["list"]>;
     }>;
@@ -48,6 +49,9 @@ export declare class Aex {
     models(...args: Parameters<Brain["models"]>): ReturnType<Brain["models"]>;
     stream(...args: Parameters<Brain["stream"]>): ReturnType<Brain["stream"]>;
     streamPath(...args: Parameters<Brain["streamPath"]>): ReturnType<Brain["streamPath"]>;
+    prepare<T extends PlacedAgentloop | PlacedTool>(extension: T): Promise<T>;
+    prepareEnvironment(...args: Parameters<Brain["prepareEnvironment"]>): ReturnType<Brain["prepareEnvironment"]>;
+    admitProgram(...args: Parameters<Brain["admitProgram"]>): ReturnType<Brain["admitProgram"]>;
     admit(...args: Parameters<Brain["admit"]>): ReturnType<Brain["admit"]>;
     admitAgentloop(...args: Parameters<Brain["admitAgentloop"]>): ReturnType<Brain["admitAgentloop"]>;
     admitTool(...args: Parameters<Brain["admitTool"]>): ReturnType<Brain["admitTool"]>;

package/dist/index.js

@@ -3,7 +3,7 @@ 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 { Brain, inspectAgentloop, inspectTool, inspectEnvironment } from "@aexhq/brain";
 import { AexSessionHandle } from "./session.js";
 function nonnegativeInteger(value, name) {
     if (!Number.isSafeInteger(value) || value < 0)
@@ -43,9 +43,20 @@ export class Aex {
             throw new TypeError("server-side sessions require a model apiKey");
         return composeApplication({ ...options, model: { ...model, apiKey: model.apiKey } }, this.baseUrl);
     }
+    async preparedComposition(options) {
+        const composition = this.composition(options);
+        const agentloop = inspectEnvironment(inspectAgentloop(composition.agentloop).environment).driver.driver === "brain"
+            ? await this.client.prepare(composition.agentloop) : composition.agentloop;
+        const tools = [];
+        for (const tool of composition.tools ?? []) {
+            tools.push(inspectEnvironment(inspectTool(tool).environment).driver.driver === "brain"
+                ? await this.client.prepare(tool) : tool);
+        }
+        return { ...composition, agentloop, tools };
+    }
     get baseUrl() { return this.client.baseUrl; }
     sessions = Object.freeze({
-        create: async (options, operation) => new AexSessionHandle(await this.client.sessions.create(this.composition(options), operation)),
+        create: async (options, operation) => new AexSessionHandle(await this.client.sessions.create(await this.preparedComposition(options), operation)),
         get: async (...args) => new AexSessionHandle(await this.client.sessions.get(...args)),
         list: () => this.client.sessions.list(),
     });
@@ -55,6 +66,9 @@ export class Aex {
     models(...args) { return this.client.models(...args); }
     stream(...args) { return this.client.stream(...args); }
     streamPath(...args) { return this.client.streamPath(...args); }
+    prepare(extension) { return this.client.prepare(extension); }
+    prepareEnvironment(...args) { return this.client.prepareEnvironment(...args); }
+    admitProgram(...args) { return this.client.admitProgram(...args); }
     admit(...args) { return this.client.admit(...args); }
     admitAgentloop(...args) { return this.client.admitAgentloop(...args); }
     admitTool(...args) { return this.client.admitTool(...args); }
@@ -121,7 +135,7 @@ export class Aex {
         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");
+            const prepared = await this.client.sessions.prepare(await this.preparedComposition(session), "authorized-client");
             return this.request("POST", "/v1/clients", { origin, expires_at: expiresAt, session: prepared });
         },
         revoke: (id) => this.request("DELETE", `/v1/clients/${encodeURIComponent(id)}`),

package/package.json

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