@aexhq/sdk 0.62.1 → 0.63.0

package/README.md

@@ -1,63 +1,24 @@
 # @aexhq/sdk
 
-TypeScript SDK for Aex sessions and tool extensions.
+The hosted Aex client wraps the neutral `@aexhq/brain` HTTP SDK with an Aex API key and the
+`https://api.aex.dev` base URL.
 
 ```ts
 import { Aex } from "@aexhq/sdk";
-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";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-const workspace = awsMicrovm();
-
 const session = await aex.sessions.create({
-  model: {
-    component: openai(),
-    provider: "openai",
-    name: "gpt-5.4",
-    apiKey: process.env.OPENAI_API_KEY!,
-  },
-  agentloop: pi({ instructions: "Work carefully and verify changes." }),
-  environments: { workspace },
-  tools: [bash(), read(), write(), task()],
+  agentloop_digest,
+  model: { binding_id: "vercel-ai-gateway", model: "openai/gpt-5.4" },
+  presentation,
+  environments,
+  tool_bindings,
 });
 
-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.
+Admit Agentloop packages through `aex.brain.admitAgentloop(...)`. Tool implementations remain in
+their bound remote Environment; the SDK sends definitions and binding requests, not implementation
+code.

package/dist/index.d.ts

@@ -1,25 +1,18 @@
+import { BrainClient, BrainError, type BrainOptions } from "@aexhq/brain";
 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";
+export { BrainError as AexError } from "@aexhq/brain";
+export { Session, Sessions } from "./session.js";
+export type { RequestOptions } from "./session.js";
+export type { AgentloopAdmission, CreateSessionRequest, EnvironmentRequirement, EventPage, SessionEvent, SessionList, ToolBinding, ToolDefinition, } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;
-    fetch?: Fetch;
-    webSocketFactory?: WebSocketFactory;
+    fetch?: BrainOptions["fetch"];
+    timeoutMs?: number;
 }
 export declare class Aex {
+    readonly brain: BrainClient;
     readonly sessions: Sessions;
     constructor(options: AexOptions);
-    /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
-    close(): void;
 }
+export { BrainError };

package/dist/index.js

@@ -1,28 +1,21 @@
+import { BrainClient, BrainError } from "@aexhq/brain";
 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";
+export { BrainError as AexError } from "@aexhq/brain";
+export { Session, Sessions } from "./session.js";
 const DEFAULT_API_URL = "https://api.aex.dev";
 export class Aex {
+    brain;
     sessions;
     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();
+        this.brain = new BrainClient({
+            baseUrl: options.baseUrl ?? DEFAULT_API_URL,
+            apiKey: options.apiKey,
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+        this.sessions = new Sessions(this.brain);
     }
 }
+export { BrainError };

package/dist/session.d.ts

@@ -1,137 +1,22 @@
-import type { Event, Session as BrainSessionData, SessionState } from "@aexhq/brain/session";
-import { type ComponentExtension, type SessionTool as ComponentSessionTool } from "@aexhq/brain";
-import type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
-import * as z from "zod";
-import type { EventOptions } from "./transport.js";
-import { Transport } from "./transport.js";
-import { type Tool } from "./tools.js";
-import { SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
-type SessionData = BrainSessionData & {
-    retain_until: string;
-};
-export type SessionInput = string;
-export interface ModelOptions {
-    /** Imported Model component. */
-    component: ComponentExtension<"model">;
-    provider: string;
-    name: string;
-    apiKey: string;
-    baseUrl?: string;
-    maxOutputTokens?: number;
-}
-export interface CreateSessionOptions {
-    model: ModelOptions;
-    /** The imported agent loop that drives this session and every child unless spawn overrides it. */
-    agentloop: ComponentExtension<"agentloop">;
-    /** Omitted or empty grants no tools. A non-empty list is the exact grant. */
-    environments?: Readonly<Record<string, ComponentExtension<"environment">>>;
-    tools?: readonly (Tool | ComponentSessionTool)[];
-    /** Write-only values for components that explicitly consume session secrets. */
-    secrets?: Record<string, string>;
-    /** Maximum direct outbound network authority sealed for managed sandboxes. Omission is deny-all. */
-    network?: NetworkPolicy;
-    /** Replacement attempts after an unrecoverable provider outcome. Defaults to one. */
-    providerRecoveryRetries?: 0 | 1;
-    /** Optional ceilings for durable child sessions. Omitted fields use the hosted defaults. */
-    children?: {
-        maxDepth?: number;
-        maxDirectChildren?: number;
-        maxDescendants?: number;
-    };
-    metadata?: Record<string, string>;
-    /** Finite durable-history deadline. Omit to use the Brain deployment default. */
-    retainUntil?: Date | string;
-}
+import { BrainClient, SessionHandle, type CreateSessionRequest, type Session as SessionState, type SessionEvent } from "@aexhq/brain";
 export interface RequestOptions {
-    signal?: AbortSignal;
     idempotencyKey?: string;
-    metadata?: Record<string, string>;
-}
-export interface OutputOptions<Schema extends z.ZodType = z.ZodType> extends RequestOptions {
-    output: Schema;
-    /** Extra attempts after the first invalid candidate. Defaults to 1; maximum 2. */
-    outputRetries?: 0 | 1 | 2;
-}
-export interface ListSessionsOptions {
-    limit?: number;
-    cursor?: string;
-    state?: SessionState;
-    signal?: AbortSignal;
-}
-export interface SessionList {
-    data: Session[];
-    hasMore: boolean;
-    nextCursor?: string;
-}
-export interface ModelSummary {
-    provider: string;
-    name: string;
-    baseUrl?: string;
-    contextWindowTokens: number;
-}
-export interface SessionSummary {
-    id: string;
-    parentId: string | undefined;
-    rootId: string;
-    depth: number;
-    state: SessionState;
-    turnState: SessionData["turn_state"];
-    model: ModelSummary;
-    createdAt: string;
-    updatedAt: string;
-    retainUntil: string;
-    metadata: Readonly<Record<string, string | undefined>>;
 }
 export declare class Sessions {
-    #private;
-    constructor(transport: Transport, webSocketFactory?: WebSocketFactory);
-    /** @internal Called by `Aex.close()`. */
-    close(): void;
-    create(options: CreateSessionOptions, request?: RequestOptions): Promise<Session>;
-    get(id: string, options?: Pick<RequestOptions, "signal">): Promise<Session>;
-    list(options?: ListSessionsOptions): Promise<SessionList>;
-}
-export declare class Session implements SessionSummary {
-    #private;
-    readonly storage: SessionStorage;
-    readonly children: SessionChildren;
-    constructor(transport: Transport, data: SessionData);
-    /** The Environment names this session sealed. Only these can be addressed. */
-    get environments(): readonly string[];
-    /** One sealed Environment addressed by the name the session declared it under. */
-    environment(name: string): SessionSandbox;
-    /** The session's default sandbox: the one Environment it declared. */
-    get sandbox(): SessionSandbox;
-    get id(): string;
+    private readonly brain;
+    constructor(brain: BrainClient);
+    create(request: CreateSessionRequest, options?: RequestOptions): Promise<Session>;
+    list(): Promise<Session[]>;
+    get(sessionId: string): Promise<Session>;
+}
+export declare class Session {
+    private readonly handle;
+    constructor(handle: SessionHandle);
     get state(): SessionState;
-    get turnState(): SessionData["turn_state"];
-    get parentId(): string | undefined;
-    get rootId(): string;
-    get depth(): number;
-    get model(): ModelSummary;
-    get createdAt(): string;
-    get updatedAt(): string;
-    get retainUntil(): string;
-    get metadata(): Readonly<Record<string, string | undefined>>;
-    refresh(options?: Pick<RequestOptions, "signal">): Promise<this>;
-    send(input: SessionInput, options?: RequestOptions): Promise<string>;
-    send<Schema extends z.ZodType>(input: SessionInput, options: OutputOptions<Schema>): Promise<z.output<Schema>>;
-    /**
-     * Raw, attempt-aware event stream. Provisional frames have no durable cursor and may later be
-     * superseded; consumers rendering them must key by `attempt_id` and process
-     * `model.attempt_superseded`. Use `send()` when only the durable winning answer is needed.
-     */
-    events(options?: EventOptions): AsyncGenerator<Event>;
-    cancel(options?: Pick<RequestOptions, "signal">): Promise<this>;
-    suspend(options?: Pick<RequestOptions, "signal">): Promise<this>;
-    resume(options?: Pick<RequestOptions, "signal">): Promise<this>;
-    setRetention(value: Date | string, options?: Pick<RequestOptions, "signal"> & {
-        allowShorten?: boolean;
-    }): Promise<this>;
-    end(options?: Pick<RequestOptions, "signal">): Promise<this>;
-    delete(options?: Pick<RequestOptions, "signal"> & {
-        queue?: boolean;
-    }): Promise<void>;
-    private markIdle;
+    get id(): string;
+    send(content: unknown, options?: RequestOptions): Promise<SessionState>;
+    events(after?: number): AsyncIterable<SessionEvent>;
+    cancel(options?: RequestOptions): Promise<void>;
+    end(options?: RequestOptions): Promise<SessionState>;
+    delete(options?: RequestOptions): Promise<void>;
 }
-export {};