@aexhq/sdk 0.55.1 → 0.57.0

package/dist/session.js

@@ -1,12 +1,38 @@
+import { CustomerHand } from "@aexhq/brain";
 import * as z from "zod";
-import { AbortError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
-import { jcsSha256, randomIdempotencyKey } from "./json.js";
+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 (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,
@@ -16,13 +42,52 @@ 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
                     ? {}
                     : { reasoning_effort: options.model.reasoningEffort }),
             },
+            tools: {
+                items: compiledTools.items,
+            },
+            ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
+            ...(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
+                ? {}
+                : {
+                    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 }),
+                    },
+                }),
         };
         const data = await this.#transport.json("POST", "/v1/sessions", {
             body,
@@ -54,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;
@@ -68,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() {
@@ -89,15 +241,35 @@ export class Session {
         return this;
     }
     async send(input, options = {}) {
+        const outputOptions = isOutputOptions(options) ? options : undefined;
+        const compiled = outputOptions === undefined
+            ? undefined
+            : await compileOutputSchema(outputOptions.output, outputOptions.outputRetries);
         const accepted = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/messages`, {
             body: {
                 content: input,
                 ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+                ...(compiled === undefined
+                    ? {}
+                    : {
+                        output: {
+                            schema: compiled.jsonSchema,
+                            schema_hash: compiled.schemaHash,
+                            ...(compiled.retries === undefined ? {} : { retries: compiled.retries }),
+                        },
+                    }),
             },
             headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
             signal: options.signal,
             retry: true,
         });
+        if (compiled !== undefined) {
+            if (accepted.session_id !== this.id ||
+                accepted.output_id === undefined ||
+                accepted.schema_hash !== compiled.schemaHash) {
+                throw new SessionError("Aex returned an inconsistent typed-output admission");
+            }
+        }
         let answer = "";
         try {
             for await (const event of this.events({ after: Math.max(0, accepted.seq - 1), signal: options.signal })) {
@@ -105,79 +277,39 @@ export class Session {
                     answer = event.text;
                 }
                 else if (event.type === "turn.failed" && event.turn_id === accepted.turn_id) {
-                    throw errorFromApi(event.error);
+                    throw errorFromApi(event.error, undefined, outputIssues(event.error));
                 }
                 else if (event.type === "turn.completed" && event.turn_id === accepted.turn_id) {
                     this.markIdle();
                     if (event.stop_reason === "cancelled")
                         throw new AbortError();
-                    return answer;
-                }
-            }
-        }
-        catch (error) {
-            if (options.signal?.aborted === true)
-                throw abortError(error);
-            throw error;
-        }
-        throw new SessionError("The Aex event stream ended before the session finished its work");
-    }
-    async output(schema, input, options = {}) {
-        let jsonSchema;
-        try {
-            assertPortableOutputSchema(schema);
-            jsonSchema = z.toJSONSchema(schema, {
-                target: "draft-2020-12",
-                unrepresentable: "throw",
-            });
-        }
-        catch (cause) {
-            throw new OutputSchemaError(messageOf(cause, "The Zod schema cannot be represented as JSON Schema"), {
-                cause,
-            });
-        }
-        if (jsonSchema.type !== "object") {
-            throw new OutputSchemaError("session.output() requires a Zod object schema");
-        }
-        const schemaHash = await jcsSha256(jsonSchema);
-        const body = {
-            schema: jsonSchema,
-            schema_hash: schemaHash,
-            ...(input === undefined ? {} : { input }),
-            ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-        };
-        const accepted = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/output`, {
-            body,
-            headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
-            signal: options.signal,
-            retry: true,
-        });
-        if (accepted.session_id !== this.id || accepted.schema_hash !== schemaHash) {
-            throw new SessionError("Aex returned an inconsistent output admission");
-        }
-        try {
-            for await (const event of this.events({ after: Math.max(0, accepted.seq - 1), signal: options.signal })) {
-                if (event.type === "output.failed" && event.output_id === accepted.output_id) {
-                    if (event.schema_hash !== schemaHash) {
-                        throw new SessionError("Aex returned an output failure for a different schema");
-                    }
-                    this.markIdle();
-                    throw outputEventError(event.error, event.issues);
-                }
-                if (event.type === "output.completed" && event.output_id === accepted.output_id) {
-                    if (event.output.schema_hash !== schemaHash) {
-                        throw new SessionError("Aex returned an output value for a different schema");
-                    }
-                    this.markIdle();
-                    const parsed = await schema.safeParseAsync(event.output.value);
-                    if (!parsed.success) {
-                        throw new OutputValidationError("The output passed the wire schema but failed the original Zod schema", parsed.error.issues.map((issue) => ({
-                            path: jsonPointer(issue.path),
-                            message: issue.message,
-                            keyword: issue.code,
-                        })));
+                    if (compiled !== undefined && outputOptions !== undefined) {
+                        if (event.result === undefined) {
+                            if (event.stop_reason === "refusal") {
+                                throw new OutputRefusalError("The model refused the structured-output request");
+                            }
+                            throw new OutputValidationError("The model ended the turn without submitting the requested structured output", [{
+                                    path: "",
+                                    message: "The model did not call aex_submit_output",
+                                    keyword: "missing_output",
+                                }]);
+                        }
+                        if (event.result.name !== "aex_submit_output" ||
+                            event.result.metadata?.output_id !== accepted.output_id ||
+                            event.result.metadata?.schema_hash !== compiled.schemaHash) {
+                            throw new SessionError("Aex returned a typed result for a different request");
+                        }
+                        const parsed = await outputOptions.output.safeParseAsync(event.result.value);
+                        if (!parsed.success) {
+                            throw new OutputValidationError("The output passed the wire schema but failed the original Zod schema", parsed.error.issues.map((issue) => ({
+                                path: jsonPointer(issue.path),
+                                message: issue.message,
+                                keyword: issue.code,
+                            })));
+                        }
+                        return parsed.data;
                     }
-                    return parsed.data;
+                    return answer;
                 }
             }
         }
@@ -188,27 +320,111 @@ export class Session {
             }
             throw error;
         }
-        throw new SessionError("The Aex event stream ended before the typed output completed");
+        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) {
+    return "output" in options;
+}
+async function compileOutputSchema(schema, retries) {
+    let jsonSchema;
+    try {
+        assertPortableOutputSchema(schema);
+        jsonSchema = z.toJSONSchema(schema, {
+            target: "draft-2020-12",
+            unrepresentable: "throw",
+        });
+    }
+    catch (cause) {
+        throw new OutputSchemaError(messageOf(cause, "The Zod schema cannot be represented as JSON Schema"), {
+            cause,
+        });
+    }
+    if (jsonSchema.type !== "object") {
+        throw new OutputSchemaError("session.send() output requires a Zod object schema");
     }
+    assertSupportedJsonSchema(jsonSchema);
+    return { jsonSchema, schemaHash: await jcsSha256(jsonSchema), retries };
+}
+function assertSupportedJsonSchema(schema) {
+    const bytes = new TextEncoder().encode(canonicalize(schema));
+    if (bytes.byteLength > 64 * 1024) {
+        throw new OutputSchemaError("The output schema exceeds the 65536-byte service limit");
+    }
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (depth > 64)
+            throw new OutputSchemaError("The output schema exceeds the service depth limit");
+        nodes += 1;
+        if (nodes > 4096)
+            throw new OutputSchemaError("The output schema exceeds the service node limit");
+        if (Array.isArray(value)) {
+            for (const child of value)
+                visit(child, depth + 1);
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        const object = value;
+        if ("pattern" in object || "patternProperties" in object) {
+            throw new OutputSchemaError("Regular-expression JSON Schema keywords are not supported for Aex structured output");
+        }
+        for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"]) {
+            const reference = object[keyword];
+            if (typeof reference === "string" && !reference.startsWith("#")) {
+                throw new OutputSchemaError("Remote JSON Schema references are not supported for Aex structured output");
+            }
+        }
+        for (const child of Object.values(object))
+            visit(child, depth + 1);
+    };
+    visit(schema, 0);
 }
-function outputEventError(error, issues) {
-    return errorFromApi(error, undefined, issues ?? []);
+function outputIssues(error) {
+    const details = error.details;
+    if (details === undefined || details === null || typeof details !== "object")
+        return [];
+    const issues = details.issues;
+    if (!Array.isArray(issues))
+        return [];
+    return issues.flatMap((issue) => {
+        if (issue === null || typeof issue !== "object")
+            return [];
+        const value = issue;
+        if (typeof value.path !== "string" || typeof value.message !== "string")
+            return [];
+        return [{
+                path: value.path,
+                message: value.message,
+                ...(typeof value.keyword === "string" ? { keyword: value.keyword } : {}),
+            }];
+    });
 }
 function jsonPointer(path) {
     if (path.length === 0)

package/dist/tools.d.ts

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

package/dist/tools.js

@@ -0,0 +1 @@
+export { compileTools } from "@aexhq/brain";

package/dist/transport.d.ts

@@ -1,11 +1,6 @@
-import type { Event } from "@aexhq/contracts/session";
+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>;