@aexhq/sdk 0.62.1 → 0.64.0

package/README.md

@@ -1,63 +1,29 @@
 # @aexhq/sdk
 
-TypeScript SDK for Aex sessions and tool extensions.
+The hosted Aex client uses the neutral Brain composition API with the `https://api.aex.dev` base
+URL and an Aex API key.
 
 ```ts
 import { Aex } from "@aexhq/sdk";
-import { awsMicrovm } from "@aexhq/env-aws-microvm";
+import { awsMicroVm } from "@aexhq/env-aws-microvm";
 import { pi } from "@aexhq/loop-pi";
-import { openai } from "@aexhq/model-openai";
-import { bash, read, task, write } from "@aexhq/tools";
+import { bash, read } from "@aexhq/tools";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-const workspace = awsMicrovm();
-
-const session = await aex.sessions.create({
+const workspace = awsMicroVm({ region: "eu-west-2" });
+const session = await aex.createSession({
   model: {
-    component: openai(),
-    provider: "openai",
-    name: "gpt-5.4",
-    apiKey: process.env.OPENAI_API_KEY!,
+    provider: "vercel-ai-gateway",
+    name: "openai/gpt-5-mini",
+    apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY!,
   },
-  agentloop: pi({ instructions: "Work carefully and verify changes." }),
-  environments: { workspace },
-  tools: [bash(), read(), write(), task()],
+  agentLoop: pi(),
+  tools: [read().runIn(workspace), bash().runIn(workspace)],
 });
 
-console.log(await session.send("Inspect the workspace."));
-```
-
-There is no default Agentloop, Model, Tool, or Environment. A Tool component that requests the
-Environment capability requires the session's one declared Environment in the MVP.
-
-## Application Tools
-
-Application callbacks use the same Tool and Environment component ABI while the handler remains in
-your process. Declare one `app()` Environment; Aex registers each selected callback over one
-authenticated, reconnecting connection. Handler source and captured application state are never
-uploaded to Brain.
-
-```ts
-import { Aex, tool } from "@aexhq/sdk";
-import { app } from "@aexhq/env-app";
-import { z } from "zod";
-
-const lookupOrder = tool(
-  z.object({ orderId: z.string() }),
-  async function lookupOrder({ orderId }) {
-    return database.lookup(orderId);
-  },
-)
-  .describe("Look up an order")
-  .returns(z.object({ status: z.string() }));
-
-await new Aex({ apiKey: process.env.AEX_API_KEY! }).sessions.create({
-  model,
-  agentloop,
-  environments: { application: app({ id: "orders-ui" }) },
-  tools: [lookupOrder],
-});
+await session.send("Inspect the workspace.");
+for await (const event of session.events()) console.log(event);
 ```
 
-Source callback Tools are routed automatically to the single `app()` Environment. Durable objects
-remain available through `session.storage`, independently of Environment lifetime.
+Aex supplies hosted authentication and policy. Agentloop admission, Tool placement, Environment
+requirements, operation keys, and event cursors are handled by the shared Brain SDK.

package/dist/index.d.ts

@@ -1,25 +1,12 @@
-import { Sessions } from "./session.js";
-import type { Fetch } from "./transport.js";
-import type { WebSocketFactory } from "@aexhq/brain";
-export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
-export type { AexErrorOptions, OutputValidationIssue } from "./errors.js";
-export { Session, Sessions, } from "./session.js";
-export type { CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
-export { SessionChild, SessionChildren, SessionStorage, } from "./resources.js";
-export type { BinarySource, ChildSummary, IdempotentOperationOptions, OperationOptions, PageOptions, StorageObject, StoragePage, StreamingUploadSource, UploadSource, } from "./resources.js";
-export type { EventOptions } from "./transport.js";
-export { tool } from "./tools.js";
-export type { Tool, ToolContract, ToolContext, ToolHandler, } from "./tools.js";
-export type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
+import { Brain, type BrainOptions } from "@aexhq/brain";
+export { BrainError as AexError } from "@aexhq/brain";
+export type { AgentLoop, BoundTool, CreateSessionOptions, Environment, EnvironmentLifecycle, OperationOptions, SessionEvent, SessionState, Tool, ToolBindingOptions, ToolDefinition, VercelAiGatewayModel, } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;
-    fetch?: Fetch;
-    webSocketFactory?: WebSocketFactory;
+    fetch?: BrainOptions["fetch"];
+    timeoutMs?: number;
 }
-export declare class Aex {
-    readonly sessions: Sessions;
+export declare class Aex extends Brain {
     constructor(options: AexOptions);
-    /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
-    close(): void;
 }

package/dist/index.js

@@ -1,28 +1,15 @@
-import { Sessions } from "./session.js";
-import { Transport } from "./transport.js";
-export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
-export { Session, Sessions, } from "./session.js";
-export { SessionChild, SessionChildren, SessionStorage, } from "./resources.js";
-export { tool } from "./tools.js";
+import { Brain } from "@aexhq/brain";
+export { BrainError as AexError } from "@aexhq/brain";
 const DEFAULT_API_URL = "https://api.aex.dev";
-export class Aex {
-    sessions;
+export class Aex extends Brain {
     constructor(options) {
         if (options.apiKey.trim() === "")
             throw new TypeError("Aex apiKey cannot be empty");
-        const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
-        if (fetchImplementation === undefined) {
-            throw new TypeError("This runtime does not provide fetch; pass a fetch implementation to Aex");
-        }
-        const transport = new Transport(options.apiKey, options.baseUrl ?? DEFAULT_API_URL, fetchImplementation);
-        const webSocketFactory = options.webSocketFactory ??
-            (globalThis.WebSocket === undefined
-                ? undefined
-                : (request) => new globalThis.WebSocket(request.url, request.protocol));
-        this.sessions = new Sessions(transport, webSocketFactory);
-    }
-    /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
-    close() {
-        this.sessions.close();
+        super({
+            baseUrl: options.baseUrl ?? DEFAULT_API_URL,
+            token: options.apiKey,
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.62.1",
+  "version": "0.64.0",
   "description": "TypeScript SDK for Aex sessions",
   "license": "Apache-2.0",
   "homepage": "https://aex.dev",
@@ -34,14 +34,9 @@
     "test": "tsc -p tsconfig.json && node --test"
   },
   "dependencies": {
-    "@aexhq/brain": "0.5.0",
-    "@aexhq/env-app": "0.3.2"
-  },
-  "peerDependencies": {
-    "zod": "4.4.3"
+    "@aexhq/brain": "0.7.0"
   },
   "devDependencies": {
-    "typescript": "^5.9.2",
-    "zod": "4.4.3"
+    "typescript": "^5.9.2"
   }
 }

package/dist/errors.d.ts

@@ -1,39 +0,0 @@
-import type { ApiError, ApiErrorCode } from "@aexhq/brain/session";
-/** One Aex trusted-output validation failure, expressed as a JSON Pointer. */
-export interface OutputValidationIssue {
-    path: string;
-    message: string;
-    keyword?: string;
-}
-export interface AexErrorOptions {
-    code?: ApiErrorCode | undefined;
-    status?: number | undefined;
-    param?: string | undefined;
-    requestId?: string | undefined;
-    cause?: unknown;
-}
-export declare class AexError extends Error {
-    readonly code: ApiErrorCode | undefined;
-    readonly status: number | undefined;
-    readonly param: string | undefined;
-    readonly requestId: string | undefined;
-    constructor(message: string, options?: AexErrorOptions);
-}
-export declare class OutputSchemaError extends AexError {
-    constructor(message: string, options?: AexErrorOptions);
-}
-export declare class OutputRefusalError extends AexError {
-    constructor(message: string, options?: AexErrorOptions);
-}
-export declare class OutputValidationError extends AexError {
-    readonly issues: readonly OutputValidationIssue[];
-    constructor(message: string, issues?: readonly OutputValidationIssue[], options?: AexErrorOptions);
-}
-export declare class SessionError extends AexError {
-    constructor(message: string, options?: AexErrorOptions);
-}
-export declare class AbortError extends AexError {
-    constructor(message?: string, options?: AexErrorOptions);
-}
-export declare function errorFromApi(error: ApiError, status?: number, issues?: readonly OutputValidationIssue[]): AexError;
-export declare function abortError(cause?: unknown): AbortError;

package/dist/errors.js

@@ -1,69 +0,0 @@
-export class AexError extends Error {
-    code;
-    status;
-    param;
-    requestId;
-    constructor(message, options = {}) {
-        super(message, options.cause === undefined ? undefined : { cause: options.cause });
-        this.name = "AexError";
-        this.code = options.code;
-        this.status = options.status;
-        this.param = options.param;
-        this.requestId = options.requestId;
-    }
-}
-export class OutputSchemaError extends AexError {
-    constructor(message, options = {}) {
-        super(message, { ...options, code: "output_schema_error" });
-        this.name = "OutputSchemaError";
-    }
-}
-export class OutputRefusalError extends AexError {
-    constructor(message, options = {}) {
-        super(message, { ...options, code: "output_refused" });
-        this.name = "OutputRefusalError";
-    }
-}
-export class OutputValidationError extends AexError {
-    issues;
-    constructor(message, issues = [], options = {}) {
-        super(message, { ...options, code: "output_validation_error" });
-        this.name = "OutputValidationError";
-        this.issues = issues;
-    }
-}
-export class SessionError extends AexError {
-    constructor(message, options = {}) {
-        super(message, options);
-        this.name = "SessionError";
-    }
-}
-export class AbortError extends AexError {
-    constructor(message = "The operation was cancelled", options = {}) {
-        super(message, { ...options, code: "cancelled" });
-        this.name = "AbortError";
-    }
-}
-export function errorFromApi(error, status, issues = []) {
-    const options = {
-        code: error.code,
-        status,
-        param: error.param,
-        requestId: error.request_id,
-    };
-    switch (error.code) {
-        case "output_schema_error":
-            return new OutputSchemaError(error.message, options);
-        case "output_refused":
-            return new OutputRefusalError(error.message, options);
-        case "output_validation_error":
-            return new OutputValidationError(error.message, issues, options);
-        case "cancelled":
-            return new AbortError(error.message, options);
-        default:
-            return new SessionError(error.message, options);
-    }
-}
-export function abortError(cause) {
-    return new AbortError("The operation was cancelled", { cause });
-}

package/dist/json.d.ts

@@ -1,4 +0,0 @@
-/** RFC 8785 canonical JSON. Object keys sort by UTF-16 code units, as required by JCS. */
-export declare function canonicalize(value: unknown): string;
-export declare function jcsSha256(value: unknown): Promise<string>;
-export declare function randomIdempotencyKey(): string;

package/dist/json.js

@@ -1,46 +0,0 @@
-import { OutputSchemaError, SessionError } from "./errors.js";
-/** RFC 8785 canonical JSON. Object keys sort by UTF-16 code units, as required by JCS. */
-export function canonicalize(value) {
-    const visit = (current) => {
-        if (Array.isArray(current))
-            return current.map(visit);
-        if (current !== null && typeof current === "object") {
-            const object = current;
-            return Object.fromEntries(Object.keys(object)
-                .filter((key) => object[key] !== undefined)
-                .sort()
-                .map((key) => [key, visit(object[key])]));
-        }
-        if (typeof current === "number" && !Number.isFinite(current)) {
-            throw new OutputSchemaError("The output schema contains a non-finite number");
-        }
-        return current;
-    };
-    const encoded = JSON.stringify(visit(value));
-    if (encoded === undefined) {
-        throw new OutputSchemaError("The output schema is not JSON-serialisable");
-    }
-    return encoded;
-}
-export async function jcsSha256(value) {
-    const subtle = globalThis.crypto?.subtle;
-    if (subtle === undefined) {
-        throw new OutputSchemaError("This runtime does not provide Web Crypto SHA-256 support");
-    }
-    const bytes = new TextEncoder().encode(canonicalize(value));
-    const digest = await subtle.digest("SHA-256", bytes);
-    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-export function randomIdempotencyKey() {
-    const crypto = globalThis.crypto;
-    if (crypto === undefined) {
-        throw new SessionError("This runtime does not provide secure random values");
-    }
-    if (typeof crypto.randomUUID === "function")
-        return crypto.randomUUID();
-    const bytes = crypto.getRandomValues(new Uint8Array(16));
-    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
-    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
-    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
-    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
-}

package/dist/resources.d.ts

@@ -1,162 +0,0 @@
-import { SessionChildren as BrainChildren, SessionSandbox as BrainSandbox } from "@aexhq/brain";
-import type { SandboxFileEntry as BrainSandboxFileEntry, SandboxStatus as BrainSandboxStatus } from "@aexhq/brain";
-import type { Event, Session as BrainSession } from "@aexhq/brain/session";
-import type { EventOptions } from "./transport.js";
-import { Transport } from "./transport.js";
-export type BinarySource = string | ArrayBuffer | ArrayBufferView | Blob;
-/** A replayable, length- and digest-declared source for O(1)-heap large uploads. */
-export interface StreamingUploadSource {
-    readonly bytes: number;
-    readonly sha256: string;
-    stream(): ReadableStream<Uint8Array>;
-}
-export type UploadSource = BinarySource | StreamingUploadSource;
-export interface OperationOptions {
-    signal?: AbortSignal;
-}
-export interface IdempotentOperationOptions extends OperationOptions {
-    /** Stable retry identity; the SDK generates one when omitted. */
-    idempotencyKey?: string;
-}
-export interface PageOptions extends OperationOptions {
-    cursor?: string;
-    limit?: number;
-}
-export interface SandboxStatus {
-    state: BrainSandboxStatus["state"];
-    generation?: string;
-    reason?: string;
-    changedAt?: string;
-    expiresAt?: string;
-}
-export interface SandboxFile {
-    path: string;
-    kind: BrainSandboxFileEntry["kind"];
-    bytes: number;
-    sha256?: string;
-    modifiedAt: string;
-}
-export interface SandboxFilePage {
-    data: SandboxFile[];
-    hasMore: boolean;
-    nextCursor?: string;
-    generation: string;
-}
-export interface SandboxFileOptions extends OperationOptions {
-    generation: string;
-}
-export interface SandboxFilePageOptions extends SandboxFileOptions, PageOptions {
-}
-export declare class SandboxFiles {
-    #private;
-    constructor(inner: BrainSandbox["files"], transport: Transport);
-    list(path: string, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-    stat(path: string, options: SandboxFileOptions): Promise<SandboxFile>;
-    download(path: string, options: SandboxFileOptions): Promise<Uint8Array>;
-    downloadStream(path: string, options: SandboxFileOptions): Promise<ReadableStream<Uint8Array>>;
-    upload(path: string, source: UploadSource, options: SandboxFileOptions & {
-        overwrite?: boolean;
-    }): Promise<SandboxFile>;
-    find(input: {
-        path: string;
-        glob: string;
-    }, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-    grep(input: {
-        path: string;
-        query: string;
-    }, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-}
-export declare class SessionSandbox {
-    #private;
-    readonly files: SandboxFiles;
-    constructor(transport: Transport, sessionId: string, environment: string);
-    /** The declared Environment name this sandbox addresses. */
-    get environment(): string;
-    status(options?: OperationOptions): Promise<SandboxStatus>;
-    create(options?: OperationOptions): Promise<SandboxStatus>;
-}
-export interface StorageObject {
-    key: string;
-    bytes: number;
-    sha256: string;
-    contentType?: string;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface StoragePage {
-    data: StorageObject[];
-    hasMore: boolean;
-    nextCursor?: string;
-}
-export declare class SessionStorage {
-    #private;
-    constructor(transport: Transport, sessionId: string);
-    list(options?: PageOptions & {
-        prefix?: string;
-    }): Promise<StoragePage>;
-    stat(key: string, options?: OperationOptions): Promise<StorageObject>;
-    download(key: string, options?: OperationOptions): Promise<Uint8Array>;
-    downloadStream(key: string, options?: OperationOptions): Promise<ReadableStream<Uint8Array>>;
-    upload(key: string, source: UploadSource, options?: OperationOptions & {
-        contentType?: string;
-        overwrite?: boolean;
-    }): Promise<StorageObject>;
-    delete(key: string, options?: OperationOptions): Promise<void>;
-    copyFromSandbox(input: {
-        environment: string;
-        key: string;
-        path: string;
-        sandboxGeneration: string;
-        overwrite?: boolean;
-    }, options?: OperationOptions): Promise<StorageObject>;
-    copyToSandbox(input: {
-        environment: string;
-        key: string;
-        path: string;
-        sandboxGeneration: string;
-        overwrite?: boolean;
-    }, options?: OperationOptions): Promise<SandboxFile>;
-}
-export interface ChildSummary {
-    id: string;
-    parentId: string;
-    rootId: string;
-    name?: string;
-    depth: number;
-    state: BrainSession["state"];
-    turnState: BrainSession["turn_state"];
-    turnPhase?: string;
-    shape: BrainSession["shape"];
-    createdAt: string;
-    updatedAt: string;
-}
-export declare class SessionChild {
-    #private;
-    constructor(inner: ReturnType<BrainChildren["get"]>);
-    get id(): string;
-    info(options?: OperationOptions): Promise<ChildSummary>;
-    send(message: string, options?: IdempotentOperationOptions): Promise<void>;
-    followUp(message: string, options?: IdempotentOperationOptions): Promise<ChildSummary>;
-    wait(options?: OperationOptions & {
-        timeoutMs?: number;
-    }): Promise<ChildSummary>;
-    interrupt(options?: OperationOptions): Promise<ChildSummary>;
-    end(options?: OperationOptions): Promise<ChildSummary>;
-    events(options?: EventOptions): AsyncGenerator<Event>;
-}
-export declare class SessionChildren {
-    #private;
-    constructor(transport: Transport, sessionId: string);
-    create(input: {
-        prompt: string;
-        name?: string;
-        forkTurns?: "all" | "none" | `${number}`;
-    }, options?: IdempotentOperationOptions): Promise<SessionChild>;
-    list(options?: PageOptions): Promise<{
-        data: ChildSummary[];
-        hasMore: boolean;
-        nextCursor?: string;
-    }>;
-    get(childId: string): SessionChild;
-}
-export declare function encodeBase64(bytes: Uint8Array): string;