@aexhq/sdk 0.54.1 → 0.55.1

package/dist/session.js

@@ -0,0 +1,255 @@
+import * as z from "zod";
+import { AbortError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
+import { jcsSha256, randomIdempotencyKey } from "./json.js";
+export class Sessions {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    async create(options, request = {}) {
+        const body = {
+            model: {
+                provider: options.model.provider,
+                name: options.model.name,
+                api_key: options.model.apiKey,
+                ...(options.model.baseUrl === undefined ? {} : { base_url: options.model.baseUrl }),
+                ...(options.model.maxOutputTokens === undefined
+                    ? {}
+                    : { max_output_tokens: options.model.maxOutputTokens }),
+                ...(options.model.temperature === undefined ? {} : { temperature: options.model.temperature }),
+                ...(options.model.reasoningEffort === undefined
+                    ? {}
+                    : { reasoning_effort: options.model.reasoningEffort }),
+            },
+            ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
+            ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+        };
+        const data = await this.#transport.json("POST", "/v1/sessions", {
+            body,
+            headers: { "Idempotency-Key": request.idempotencyKey ?? randomIdempotencyKey() },
+            signal: request.signal,
+            retry: true,
+        });
+        return new Session(this.#transport, data);
+    }
+    async get(id, options = {}) {
+        const data = await this.#transport.json("GET", `/v1/sessions/${encodeURIComponent(id)}`, { signal: options.signal });
+        return new Session(this.#transport, data);
+    }
+    async list(options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        if (options.state !== undefined)
+            query.set("state", options.state);
+        const suffix = query.size === 0 ? "" : `?${query}`;
+        const list = await this.#transport.json("GET", `/v1/sessions${suffix}`, {
+            signal: options.signal,
+        });
+        return {
+            data: list.data.map((data) => new Session(this.#transport, data)),
+            hasMore: list.has_more,
+            ...(list.next_cursor === undefined ? {} : { nextCursor: list.next_cursor }),
+        };
+    }
+}
+export class Session {
+    #transport;
+    #data;
+    constructor(transport, data) {
+        this.#transport = transport;
+        this.#data = data;
+    }
+    get id() {
+        return this.#data.id;
+    }
+    get state() {
+        return this.#data.state;
+    }
+    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 }),
+        };
+    }
+    get createdAt() {
+        return this.#data.created_at;
+    }
+    get updatedAt() {
+        return this.#data.updated_at;
+    }
+    get metadata() {
+        return this.#data.metadata;
+    }
+    async refresh(options = {}) {
+        this.#data = await this.#transport.json("GET", `/v1/sessions/${encodeURIComponent(this.id)}`, { signal: options.signal });
+        return this;
+    }
+    async send(input, options = {}) {
+        const accepted = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/messages`, {
+            body: {
+                content: input,
+                ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+            },
+            headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
+            signal: options.signal,
+            retry: true,
+        });
+        let answer = "";
+        try {
+            for await (const event of this.events({ after: Math.max(0, accepted.seq - 1), signal: options.signal })) {
+                if (event.type === "assistant.message" && event.turn_id === accepted.turn_id && event.agent_id === "root") {
+                    answer = event.text;
+                }
+                else if (event.type === "turn.failed" && event.turn_id === accepted.turn_id) {
+                    throw errorFromApi(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,
+                        })));
+                    }
+                    return parsed.data;
+                }
+            }
+        }
+        catch (error) {
+            if (options.signal?.aborted === true) {
+                await this.cancel().catch(() => undefined);
+                throw abortError(error);
+            }
+            throw error;
+        }
+        throw new SessionError("The Aex event stream ended before the typed output completed");
+    }
+    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 });
+        return this;
+    }
+    async delete(options = {}) {
+        await this.#transport.json("DELETE", `/v1/sessions/${encodeURIComponent(this.id)}`, {
+            signal: options.signal,
+        });
+        this.#data = { ...this.#data, state: "deleted" };
+    }
+    markIdle() {
+        this.#data = { ...this.#data, state: "idle" };
+    }
+}
+function outputEventError(error, issues) {
+    return errorFromApi(error, undefined, issues ?? []);
+}
+function jsonPointer(path) {
+    if (path.length === 0)
+        return "";
+    return `/${path
+        .map((part) => String(part).replaceAll("~", "~0").replaceAll("/", "~1"))
+        .join("/")}`;
+}
+function messageOf(error, fallback) {
+    return error instanceof Error && error.message !== "" ? error.message : fallback;
+}
+/**
+ * A server cannot execute user-defined Zod functions. Reject them before admission instead of
+ * committing a value that only the calling process can later discover was invalid.
+ */
+function assertPortableOutputSchema(schema) {
+    const seen = new WeakSet();
+    const visit = (value) => {
+        if (value === null || typeof value !== "object" || seen.has(value))
+            return;
+        seen.add(value);
+        const internal = value;
+        if (internal._zod?.def !== undefined) {
+            const definition = internal._zod.def;
+            const unsupported = definition.type === "custom" ||
+                definition.type === "transform" ||
+                definition.type === "file" ||
+                definition.check === "overwrite";
+            if (unsupported) {
+                throw new OutputSchemaError(`This Zod schema contains ${String(definition.type ?? definition.check)} behavior that cannot be enforced by the Aex output service`);
+            }
+            visit(definition);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    visit(schema);
+}

package/dist/transport.d.ts

@@ -0,0 +1,22 @@
+import type { Event } from "@aexhq/contracts/session";
+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;
+    signal?: AbortSignal | undefined;
+}
+export declare class Transport {
+    #private;
+    readonly baseUrl: string;
+    constructor(apiKey: string, baseUrl: string, fetchImplementation: Fetch);
+    json<T>(method: "GET" | "POST" | "DELETE", path: string, options?: JsonRequestOptions): Promise<T>;
+    events(sessionId: string, options?: EventOptions): AsyncGenerator<Event>;
+    private responseError;
+}
+export {};

package/dist/transport.js

@@ -0,0 +1,196 @@
+import { AbortError, AexError, SessionError, abortError, errorFromApi } from "./errors.js";
+export class Transport {
+    baseUrl;
+    #apiKey;
+    #fetch;
+    constructor(apiKey, baseUrl, fetchImplementation) {
+        this.#apiKey = apiKey;
+        let end = baseUrl.length;
+        while (end > 0 && baseUrl.charCodeAt(end - 1) === 47)
+            end -= 1;
+        this.baseUrl = baseUrl.slice(0, end);
+        this.#fetch = fetchImplementation;
+    }
+    async json(method, path, options = {}) {
+        const attempts = options.retry === true ? 2 : 1;
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            try {
+                const response = await this.#fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        Accept: "application/json",
+                        ...(options.body === undefined ? {} : { "Content-Type": "application/json" }),
+                        Authorization: `Bearer ${this.#apiKey}`,
+                        ...options.headers,
+                    },
+                    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                });
+                if (!response.ok)
+                    throw await this.responseError(response);
+                if (response.status === 204)
+                    return undefined;
+                return (await response.json());
+            }
+            catch (error) {
+                if (options.signal?.aborted === true || isAbort(error))
+                    throw abortError(error);
+                if (error instanceof AexError)
+                    throw error;
+                lastError = error;
+            }
+        }
+        throw new SessionError("Could not reach the Aex API", { cause: lastError });
+    }
+    async *events(sessionId, options = {}) {
+        let cursor = options.after ?? 0;
+        const follow = options.follow ?? true;
+        let consecutiveFailures = 0;
+        while (true) {
+            try {
+                const query = new URLSearchParams({ after: String(cursor), follow: String(follow) });
+                const response = await this.#fetch(`${this.baseUrl}/v1/sessions/${encodeURIComponent(sessionId)}/events?${query}`, {
+                    method: "GET",
+                    headers: {
+                        Accept: "text/event-stream",
+                        Authorization: `Bearer ${this.#apiKey}`,
+                        ...(cursor > 0 ? { "Last-Event-ID": String(cursor) } : {}),
+                    },
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                });
+                if (!response.ok)
+                    throw await this.responseError(response);
+                if (response.body === null)
+                    throw new SessionError("The Aex event stream had no body");
+                let received = false;
+                for await (const event of parseEventStream(response.body)) {
+                    if (event.seq <= cursor)
+                        continue;
+                    cursor = event.seq;
+                    received = true;
+                    consecutiveFailures = 0;
+                    yield event;
+                }
+                if (!follow)
+                    return;
+                if (!received)
+                    consecutiveFailures += 1;
+            }
+            catch (error) {
+                if (options.signal?.aborted === true || isAbort(error))
+                    throw abortError(error);
+                if (error instanceof AexError && error.status !== undefined && error.status < 500)
+                    throw error;
+                consecutiveFailures += 1;
+                if (consecutiveFailures > 5) {
+                    if (error instanceof AexError)
+                        throw error;
+                    throw new SessionError("The Aex event stream disconnected", { cause: error });
+                }
+            }
+            await delay(Math.min(2_000, 100 * 2 ** (consecutiveFailures - 1)), options.signal);
+        }
+    }
+    async responseError(response) {
+        let envelope;
+        try {
+            envelope = (await response.json());
+        }
+        catch {
+            // Fall through to a status-based error.
+        }
+        if (envelope?.error !== undefined)
+            return errorFromApi(envelope.error, response.status);
+        return new SessionError(`Aex API request failed with HTTP ${response.status}`, {
+            status: response.status,
+            requestId: response.headers.get("x-request-id") ?? undefined,
+        });
+    }
+}
+async function* parseEventStream(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let frame = { data: [] };
+    const dispatch = () => {
+        if (frame.data.length === 0) {
+            frame = { data: [] };
+            return undefined;
+        }
+        const data = frame.data.join("\n");
+        frame = { data: [] };
+        try {
+            return JSON.parse(data);
+        }
+        catch (cause) {
+            throw new SessionError("Aex sent an invalid event", { cause });
+        }
+    };
+    const line = (raw) => {
+        const value = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (value === "")
+            return dispatch();
+        if (value.startsWith(":"))
+            return undefined;
+        const separator = value.indexOf(":");
+        const field = separator === -1 ? value : value.slice(0, separator);
+        let content = separator === -1 ? "" : value.slice(separator + 1);
+        if (content.startsWith(" "))
+            content = content.slice(1);
+        if (field === "data")
+            frame.data.push(content);
+        else if (field === "id")
+            frame.id = content;
+        else if (field === "event")
+            frame.event = content;
+        return undefined;
+    };
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            buffer += decoder.decode(value, { stream: !done });
+            let newline = buffer.indexOf("\n");
+            while (newline !== -1) {
+                const event = line(buffer.slice(0, newline));
+                buffer = buffer.slice(newline + 1);
+                if (event !== undefined)
+                    yield event;
+                newline = buffer.indexOf("\n");
+            }
+            if (done)
+                break;
+        }
+        if (buffer !== "") {
+            const event = line(buffer);
+            if (event !== undefined)
+                yield event;
+        }
+        const final = dispatch();
+        if (final !== undefined)
+            yield final;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function isAbort(error) {
+    return error instanceof AbortError || (error instanceof DOMException && error.name === "AbortError");
+}
+function delay(milliseconds, signal) {
+    if (signal?.aborted === true)
+        return Promise.reject(abortError(signal.reason));
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener("abort", onAbort);
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            reject(abortError(signal?.reason));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/package.json

@@ -1,64 +1,22 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.54.1",
-  "description": "Zero-dependency TypeScript SDK for the AEX v1 public API.",
-  "aex": {
-    "owner": "clients",
-    "role": "client",
-    "artifact": "npm_package",
-    "layers": [
-      "unit",
-      "user"
-    ],
-    "concerns": [
-      "contract",
-      "compatibility",
-      "property",
-      "security"
-    ],
-    "seams": [
-      "npm.registry.publish"
-    ],
-    "security_tier": "public_edge",
-    "risk": [
-      "generated_code"
-    ],
-    "scenarios": ["packed.sdk-install-node", "packed.sdk-install-bun"],
-    "targets": {
-      "conformance": "unit",
-      "security": "unit",
-      "compatibility": "unit",
-      "packed_user": "user"
-    },
-    "not_applicable": {
-      "live_suite": "clean-install and packed-tarball evidence is package-owned; the SDK has no deployed endpoint"
-    }
-  },
+  "version": "0.55.1",
+  "description": "TypeScript SDK for Aex sessions",
   "license": "Apache-2.0",
-  "keywords": [
-    "aex",
-    "agent",
-    "sdk",
-    "autonomous-agents",
-    "agent-runtime",
-    "typescript"
-  ],
   "homepage": "https://aex.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aexhq/aex.git",
     "directory": "packages/sdk"
   },
-  "bugs": {
-    "url": "https://github.com/aexhq/aex/issues"
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -68,26 +26,20 @@
   },
   "files": [
     "dist",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
+    "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "lint": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "test": "bun run test:unit",
-    "test:unit": "bun test --isolate test/unit",
-    "test:coverage": "bun test --isolate --coverage test/unit",
-    "prepack": "bun run build",
-    "pack:dry-run": "bun pm pack --dry-run --ignore-scripts"
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test"
   },
-  "dependencies": {},
-  "devDependencies": {
-    "@types/bun": "1.3.14"
+  "dependencies": {
+    "@aexhq/contracts": "0.26.1"
   },
-  "engines": {
-    "node": ">=22.0.0",
-    "bun": ">=1.3.14"
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "zod": "^4.0.0"
   }
 }