@aexhq/sdk 0.56.0 → 0.57.0

package/README.md

@@ -1,40 +1,105 @@
-# @aexhq/sdk
+# `@aexhq/sdk`
+
+TypeScript client for durable Aex sessions.
 
 ```ts
-import { Aex } from "@aexhq/sdk";
+import { Aex, tool } from "@aexhq/sdk";
 import { z } from "zod";
 
-const aex = new Aex({ apiKey: "aex_sk_..." });
-const session = await aex.sessions.create({
-  model: {
-    provider: "anthropic",
-    name: "claude-sonnet-5",
-    apiKey: "sk-ant-...",
+const lookup = tool(
+  z.object({ id: z.string() }),
+  async function lookup({ id }) {
+    return database.customers.find(id);
   },
+).client();
+
+const aex = new Aex({
+  apiKey: process.env.AEX_API_KEY!,
+  client: { id: "customer-api" },
 });
+const model = {
+  provider: "openai" as const,
+  name: "gpt-5.4",
+  apiKey: process.env.OPENAI_API_KEY!,
+};
+const session = await aex.sessions.create({ model, tools: [lookup] });
 
 const result = await session.send("Answer the question.", {
   output: z.object({ answer: z.string() }),
 });
 ```
 
-`send()` returns text by default. Passing `output` returns a normal typed Promise and uses
-`https://api.aex.dev` by default. Zod schemas must be representable as JSON Schema; process-local
-custom refinements and transforms fail before any model work is admitted.
+`send()` returns text by default. Passing `output` returns a typed Promise. The client uses
+`https://api.aex.dev` by default; the model `baseUrl` is independent of the Aex API origin.
+`send()` resolves only the durable winning assistant message after provider recovery. The lower-
+level `session.events()` stream is raw and attempt-aware: provisional frames have no durable cursor
+and can later be superseded, so live renderers must key them by `attempt_id` and process
+`model.attempt_superseded` instead of concatenating attempts.
+The SDK always generates and reuses an `Idempotency-Key` for root/child creation and messages; pass
+`idempotencyKey` explicitly when the application must recover the same operation across its own
+process restart. Raw hosted REST calls must supply that header for those operations.
+
+Hosted alpha has one managed-compute shape, `1gb` (0.5 vCPU and 1 GiB), so the SDK exposes no shape
+selector. Child sessions and managed sandboxes inherit the root's physical seal.
 
-Sessions start with no model tools. Configure the exact capabilities at creation:
+Tools are immutable once the session is created. `.client()` keeps closures in this application;
+`.server(import.meta.url)` bundles a module whose default export is the completed Tool value for the
+session's shared managed computer. One customer-app socket is shared across sessions; call
+`aex.close()` during graceful process shutdown to stop it and interrupt process-local work. A
+closed `Aex` instance cannot create another session. The
+default `.client()` registration
+is derived from its contract. If one application intentionally has different closures with the
+same name and schemas, give each a stable `.client({ registration: "..." })`; a live runner rejects
+a registration collision instead of invoking the wrong closure. Sessions grant no execution
+capabilities by default. Add only the official capabilities needed. Aex's reserved output protocol is
+present but inert unless a particular `send({ output })` request arms it:
+
+Hosted `.server()` bindings use distinct generation-lifetime unprivileged users, separate from the
+ordinary shell, while sharing the workspace through a group. Declared environment secrets are not
+written by Aex to the workspace, arguments, results, or logs. This blocks ordinary sibling reads,
+not guest-root compromise or a Tool deliberately writing the value. Use `.client()` or an external
+service for that stronger boundary; local mode is intentionally unsandboxed.
 
 ```ts
-import { bash, edit, read, subagents, write } from "@aexhq/tools";
+import { bash, edit, read, sandbox, storage, subagents, write } from "@aexhq/tools";
 
 const session = await aex.sessions.create({
-  model: {
-    provider: "anthropic",
-    name: "claude-sonnet-5",
-    apiKey: "sk-ant-...",
-  },
-  tools: [bash(), read(), write(), edit(), subagents()],
+  model,
+  tools: [bash(), read(), write(), edit(), storage(), sandbox(), subagents()],
+  network: { outbound: "none" },
+});
+```
+
+Omitting `tools` and passing `tools: []` are equivalent. Zod schemas must be representable as JSON
+Schema; process-local refinements and transforms fail before model work starts. Temporary files are
+available through `session.sandbox.files`; durable objects use `session.storage`. Large transfers
+automatically bypass the Brain actor. Durable direct children use `session.children`.
+Sandbox file operations honor guest permissions; they do not bypass a `.server()` binding's
+deliberate mode-0600 files. The binding must explicitly export or relax those permissions.
+
+Buffered `upload()` and `download()` are convenient for small objects. Large transfers can stay
+O(1)-heap with `downloadStream()` and a replayable declared source:
+
+```ts
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
+
+await session.storage.upload("inputs/archive.tar", {
+  bytes: stat.size,
+  sha256: digest,
+  stream: () => Readable.toWeb(createReadStream(filename)),
 });
+const body = await session.storage.downloadStream("inputs/archive.tar");
 ```
 
-Omitting `tools` and passing `tools: []` are equivalent.
+The same methods are available on `session.sandbox.files`; the SDK enforces upload length, ticket
+ceilings, abort signals, and the downloaded object's exact metadata length while bytes bypass
+Brain. Direct large sandbox transfers are a happy-path convenience: the SDK does not automatically
+retry an ambiguous completion or recover a ticket after Brain restart or expiry. Inspect the
+generation and path, then prepare a fresh transfer. Put bytes in `session.storage` and copy them to
+or from the sandbox when the transfer itself must be recovery-safe.
+
+`await session.end()` closes work but retains journal and storage. Both deletion modes first make
+the same short, durable deletion-job request. `await session.delete()` then polls the status
+resource for confirmed removal; `{ queue: true }` returns after acceptance. No HTTP request stays
+open while sandbox and storage cleanup runs.

package/dist/index.d.ts

@@ -1,18 +1,28 @@
 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, McpServerOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export type { CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export { SandboxFiles, SessionChild, SessionChildren, SessionSandbox, SessionStorage, } from "./resources.js";
+export type { BinarySource, ChildSummary, IdempotentOperationOptions, OperationOptions, PageOptions, SandboxFile, SandboxFileOptions, SandboxFilePage, SandboxFilePageOptions, SandboxStatus, StorageObject, StoragePage, StreamingUploadSource, UploadSource, } from "./resources.js";
 export type { EventOptions } from "./transport.js";
-export { defineIntrinsicTool, definePreinstalledTool, defineServerTool, defineTool, } from "@aexhq/brain";
-export type { DefineIntrinsicToolOptions, DefinePreinstalledToolOptions, DefineServerToolOptions, DefineToolOptions, Tool, ToolContext, ToolHandler, } from "@aexhq/brain";
+export { tool } from "@aexhq/brain";
+export type { ClientToolOptions, Tool, ToolBuilder, ToolContract, ToolContext, ToolHandler, ServerToolOptions, NetworkDestination, NetworkPolicy, WebSocketFactory, } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;
     fetch?: Fetch;
+    webSocketFactory?: WebSocketFactory;
+    /** Stable tenant-scoped identity for this exact customer-application runner. */
+    client?: {
+        id: string;
+    };
 }
 export declare class Aex {
     readonly sessions: Sessions;
     constructor(options: AexOptions);
+    /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
+    close(): void;
 }

package/dist/index.js

@@ -2,7 +2,8 @@ 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 { defineIntrinsicTool, definePreinstalledTool, defineServerTool, defineTool, } from "@aexhq/brain";
+export { SandboxFiles, SessionChild, SessionChildren, SessionSandbox, SessionStorage, } from "./resources.js";
+export { tool } from "@aexhq/brain";
 const DEFAULT_API_URL = "https://api.aex.dev";
 export class Aex {
     sessions;
@@ -13,7 +14,19 @@ export class Aex {
         if (fetchImplementation === undefined) {
             throw new TypeError("This runtime does not provide fetch; pass a fetch implementation to Aex");
         }
+        if (options.client !== undefined &&
+            !/^[A-Za-z0-9_.:-]{1,128}$/u.test(options.client.id)) {
+            throw new TypeError("Aex client.id must contain 1 through 128 letters, digits, dots, colons, underscores, or hyphens");
+        }
         const transport = new Transport(options.apiKey, options.baseUrl ?? DEFAULT_API_URL, fetchImplementation);
-        this.sessions = new Sessions(transport);
+        const webSocketFactory = options.webSocketFactory ??
+            (globalThis.WebSocket === undefined
+                ? undefined
+                : (request) => new globalThis.WebSocket(request.url, request.protocol));
+        this.sessions = new Sessions(transport, webSocketFactory, options.client?.id);
+    }
+    /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
+    close() {
+        this.sessions.close();
     }
 }

package/dist/resources.d.ts

@@ -0,0 +1,157 @@
+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);
+    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: {
+        key: string;
+        path: string;
+        sandboxGeneration: string;
+        overwrite?: boolean;
+    }, options?: OperationOptions): Promise<StorageObject>;
+    copyToSandbox(input: {
+        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;
+}