@aexhq/sdk 0.85.0 → 0.87.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.85.0 @aexhq/agentloop-pi@7.2.4 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
 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
@@ -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.
@@ -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.4 and extension packages pinned to Brain 0.35.1 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:
@@ -165,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.85.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.35.1",
+    "@aexhq/brain": "0.37.0",
     "zod": "4.4.3",
-    "@aexhq/env-http": "0.3.0"
+    "@aexhq/env-http": "0.3.2"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",