@aexhq/sdk 0.56.0 → 0.57.0

package/dist/session.js

@@ -1,17 +1,38 @@
+import { CustomerHand } from "@aexhq/brain";
 import * as z from "zod";
 import { AbortError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
 import { canonicalize, jcsSha256, randomIdempotencyKey } from "./json.js";
 import { compileTools } from "./tools.js";
+import { SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
 export class Sessions {
     #transport;
-    constructor(transport) {
+    #webSocketFactory;
+    #clientId;
+    #customerHand;
+    #customerHandInstance;
+    #closed = false;
+    constructor(transport, webSocketFactory, clientId) {
         this.#transport = transport;
+        this.#webSocketFactory = webSocketFactory;
+        this.#clientId = clientId;
+    }
+    /** @internal Called by `Aex.close()`. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#customerHandInstance?.close();
+        this.#customerHandInstance = undefined;
+        this.#customerHand = undefined;
     }
     async create(options, request = {}) {
+        if (this.#closed)
+            throw new SessionError("Aex client is closed");
         const compiledTools = await compileTools(options.tools);
-        if (compiledTools.attached.size > 0) {
-            throw new TypeError("Attached-process Tools are not available through this Aex SDK revision; use the default Hand execution mode");
+        if (options.client?.submitRetries !== undefined && this.#clientId === undefined) {
+            throw new TypeError("client.submitRetries requires Aex({ client: { id } })");
         }
+        await this.#ensureCustomerHand(compiledTools.clientRegistrations, request.signal);
         const body = {
             model: {
                 provider: options.model.provider,
@@ -21,6 +42,9 @@ export class Sessions {
                 ...(options.model.maxOutputTokens === undefined
                     ? {}
                     : { max_output_tokens: options.model.maxOutputTokens }),
+                ...(options.model.contextWindowTokens === undefined
+                    ? {}
+                    : { context_window_tokens: options.model.contextWindowTokens }),
                 ...(options.model.temperature === undefined ? {} : { temperature: options.model.temperature }),
                 ...(options.model.reasoningEffort === undefined
                     ? {}
@@ -28,31 +52,42 @@ export class Sessions {
             },
             tools: {
                 items: compiledTools.items,
-                ...(options.mcp === undefined
-                    ? {}
-                    : {
-                        mcp: options.mcp.map((server) => ({
-                            name: server.name,
-                            url: server.url,
-                            ...(server.headers === undefined ? {} : { headers: server.headers }),
-                            ...(server.protocol === undefined ? {} : { protocol: server.protocol }),
-                            ...(server.allowedTools === undefined
-                                ? {}
-                                : { allowed_tools: [...server.allowedTools] }),
-                        })),
-                    }),
             },
             ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
-            ...(options.hand === undefined
+            ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+            ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
+            ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+            ...(options.network === undefined
+                ? {}
+                : { network: options.network }),
+            ...(options.providerRecoveryRetries === undefined
+                ? {}
+                : { provider_recovery_retries: options.providerRecoveryRetries }),
+            ...(this.#clientId === undefined
                 ? {}
                 : {
-                    hand: {
-                        ...(options.hand.enabled === undefined ? {} : { enabled: options.hand.enabled }),
-                        ...(options.hand.env === undefined ? {} : { env: options.hand.env }),
+                    client: {
+                        id: this.#clientId,
+                        ...(options.client?.submitRetries === undefined
+                            ? {}
+                            : { submit_retries: options.client.submitRetries }),
+                    },
+                }),
+            ...(options.children === undefined
+                ? {}
+                : {
+                    children: {
+                        ...(options.children.maxDepth === undefined
+                            ? {}
+                            : { max_depth: options.children.maxDepth }),
+                        ...(options.children.maxDirectChildren === undefined
+                            ? {}
+                            : { max_direct_children: options.children.maxDirectChildren }),
+                        ...(options.children.maxDescendants === undefined
+                            ? {}
+                            : { max_descendants: options.children.maxDescendants }),
                     },
                 }),
-            ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
-            ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
         };
         const data = await this.#transport.json("POST", "/v1/sessions", {
             body,
@@ -84,13 +119,87 @@ export class Sessions {
             ...(list.next_cursor === undefined ? {} : { nextCursor: list.next_cursor }),
         };
     }
+    async #ensureCustomerHand(registrations, signal) {
+        if (this.#closed)
+            throw new SessionError("Aex client is closed");
+        if (registrations.length === 0)
+            return;
+        if (this.#clientId === undefined) {
+            throw new TypeError("Customer-app Tools require Aex({ client: { id } })");
+        }
+        if (this.#webSocketFactory === undefined) {
+            throw new TypeError("This runtime does not provide WebSocket; pass webSocketFactory to Aex");
+        }
+        if (this.#customerHand === undefined) {
+            let partial;
+            const starting = (async () => {
+                try {
+                    partial = new CustomerHand(async () => {
+                        const grant = await this.#transport.customerHandGrant(this.#clientId);
+                        return {
+                            request: { url: grant.url, protocol: grant.protocol },
+                            observe: (observation) => this.#transport.customerHandObserve(grant.observationUrl, grant.observationToken, observation),
+                        };
+                    }, registrations, this.#webSocketFactory, { clientId: this.#clientId });
+                    this.#customerHandInstance = partial;
+                    await partial.ready;
+                    if (this.#closed) {
+                        partial.close();
+                        throw new SessionError("Aex client is closed");
+                    }
+                    return partial;
+                }
+                catch (error) {
+                    partial?.close();
+                    throw error;
+                }
+            })();
+            this.#customerHand = starting;
+            void starting.catch(() => {
+                if (this.#customerHand === starting) {
+                    this.#customerHand = undefined;
+                    if (this.#customerHandInstance === partial)
+                        this.#customerHandInstance = undefined;
+                }
+            });
+            // The request may stop waiting, but the process-scoped runner remains reconnectable for
+            // later sessions. Its grant/reconnect lifetime must never inherit one create signal.
+            await waitWithSignal(starting, signal);
+            return;
+        }
+        const hand = await waitWithSignal(this.#customerHand, signal);
+        if (this.#closed)
+            throw new SessionError("Aex client is closed");
+        await waitWithSignal(hand.register(registrations), signal);
+    }
+}
+function waitWithSignal(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortError(signal.reason));
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(abortError(signal.reason));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+    });
 }
 export class Session {
     #transport;
     #data;
+    sandbox;
+    storage;
+    children;
     constructor(transport, data) {
         this.#transport = transport;
         this.#data = data;
+        this.sandbox = new SessionSandbox(transport, data.id);
+        this.storage = new SessionStorage(transport, data.id);
+        this.children = new SessionChildren(transport, data.id);
     }
     get id() {
         return this.#data.id;
@@ -98,11 +207,24 @@ export class Session {
     get state() {
         return this.#data.state;
     }
+    get turnState() {
+        return this.#data.turn_state;
+    }
+    get parentId() {
+        return this.#data.parent_id;
+    }
+    get rootId() {
+        return this.#data.root_id;
+    }
+    get depth() {
+        return this.#data.depth;
+    }
     get model() {
         return {
             provider: this.#data.model.provider,
             name: this.#data.model.name,
             ...(this.#data.model.base_url === undefined ? {} : { baseUrl: this.#data.model.base_url }),
+            contextWindowTokens: this.#data.model.context_window_tokens,
         };
     }
     get createdAt() {
@@ -200,21 +322,31 @@ export class Session {
         }
         throw new SessionError("The Aex event stream ended before the session finished its work");
     }
+    /**
+     * 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 = {}) {
         return this.#transport.events(this.id, options);
     }
     async cancel(options = {}) {
-        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/cancel`, { signal: options.signal });
+        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/cancel`, { signal: options.signal, retry: true });
+        return this;
+    }
+    async end(options = {}) {
+        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/end`, { signal: options.signal, retry: true });
         return this;
     }
     async delete(options = {}) {
-        await this.#transport.json("DELETE", `/v1/sessions/${encodeURIComponent(this.id)}`, {
-            signal: options.signal,
-        });
-        this.#data = { ...this.#data, state: "deleted" };
+        await this.#transport.deleteSession(this.id, options.queue !== true, options.signal);
+        this.#data = {
+            ...this.#data,
+            state: options.queue === true ? "deleting" : "deleted",
+        };
     }
     markIdle() {
-        this.#data = { ...this.#data, state: "idle" };
+        this.#data = { ...this.#data, turn_state: "idle" };
     }
 }
 function isOutputOptions(options) {

package/dist/tools.d.ts

@@ -1,2 +1,2 @@
 export { compileTools } from "@aexhq/brain";
-export type { CompiledTools, Tool } from "@aexhq/brain";
+export type { ClientRegistration, CompiledTools, Tool } from "@aexhq/brain";

package/dist/transport.d.ts

@@ -1,11 +1,6 @@
 import type { Event } from "@aexhq/brain/session";
+import type { JsonRequestOptions, TransferTicket } from "@aexhq/brain";
 export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
-interface JsonRequestOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    signal?: AbortSignal | undefined;
-    retry?: boolean;
-}
 export interface EventOptions {
     after?: number;
     follow?: boolean;
@@ -15,8 +10,22 @@ export declare class Transport {
     #private;
     readonly baseUrl: string;
     constructor(apiKey: string, baseUrl: string, fetchImplementation: Fetch);
+    customerHandGrant(clientId: string, signal?: AbortSignal): Promise<{
+        url: string;
+        protocol: string;
+        expiresAt: string;
+        observationUrl: string;
+        observationToken: string;
+    }>;
+    customerHandObserve(url: string, token: string, observation: unknown): Promise<void>;
+    downloadTransfer(ticket: TransferTicket, signal?: AbortSignal, expectedBytes?: number): Promise<Uint8Array>;
+    downloadTransferStream(ticket: TransferTicket, signal?: AbortSignal, expectedBytes?: number): Promise<ReadableStream<Uint8Array>>;
+    uploadTransfer(ticket: TransferTicket, content: Uint8Array | (() => ReadableStream<Uint8Array>), bytes: number, signal?: AbortSignal): Promise<void>;
     json<T>(method: "GET" | "POST" | "DELETE", path: string, options?: JsonRequestOptions): Promise<T>;
+    /** Accept one durable deletion job; strict callers poll its short status resource client-side. */
+    deleteSession(sessionId: string, waitForCompletion: boolean, signal?: AbortSignal): Promise<void>;
     events(sessionId: string, options?: EventOptions): AsyncGenerator<Event>;
     private responseError;
 }
-export {};
+/** @internal Incremental, constant-space decoder for Brain's bounded public SSE events. */
+export declare function parseEventStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<Event>;