@aexhq/sdk 0.54.0 → 0.55.0

package/README.md

@@ -1,131 +1,24 @@
 # @aexhq/sdk
 
-The zero-dependency TypeScript SDK for the session-centered AEX public API.
-
-```bash
-npm install @aexhq/sdk
-```
-
-## Quickstart
-
 ```ts
-import { Aex, newId } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_WORKSPACE_API_KEY! });
-const session = await aex.sessions.sessionCreate({
-  body: {
-    provider: "openai",
-    model: process.env.AEX_MODEL!,
-    providerApiKey: process.env.AEX_PROVIDER_API_KEY!,
+import { Aex } 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-...",
   },
-  idempotencyKey: crypto.randomUUID(),
 });
 
-const committed = (async () => {
-  for await (const frame of aex.sessions.sessionMessagesStream({
-    sessionId: session.id,
-  })) {
-    if (frame.kind === "committed" && frame.message?.role === "assistant") {
-      return frame.message;
-    }
-  }
-  throw new Error("message stream ended before the assistant committed");
-})();
-
-await aex.sessions.sessionMessageSend({
-  sessionId: session.id,
-  body: { text: "Inspect the tests and summarize the failures." },
-  idempotencyKey: crypto.randomUUID(),
-});
-console.log(await committed);
-
-await aex.sessions.sessionTerminate({
-  sessionId: session.id,
-  body: {},
-  operationId: newId("operation"),
-});
+const result = await session.output(
+  z.object({ answer: z.string() }),
+  "Answer the question.",
+);
 ```
 
-Session creation takes an exact provider/model pair and a write-only
-`providerApiKey`. The key is encrypted for that session, never returned, and
-never reused by another session. Supported provider families are OpenAI,
-Anthropic, DeepSeek, xAI, Meta, Moonshot AI, and Alibaba.
-
-## Client surface
-
-Regional session and file calls use a workspace `apiKey`. Central bootstrap,
-API-key, and billing calls use a GitHub `dashboardSession`. A client may hold
-both; the SDK sends each credential only to its owning API plane.
-
-```ts
-const aex = new Aex({
-  apiKey: process.env.AEX_WORKSPACE_API_KEY!,
-  dashboardSession: process.env.AEX_DASHBOARD_SESSION!,
-});
-```
-
-Generated namespaces are `apiKeys`, `auth`, `billing`, `bootstrap`, `registry`,
-`sessions`, and `uploads`. `aex.workspaceFiles` adds verified convenience
-helpers for the latest-only file API. `ROUTES` and `aex.execute(...)` expose the
-same generated contract without a second handwritten route table.
-
-## Sessions and sandboxes
-
-A session is the only public execution resource. It owns committed messages,
-one active root message, durable tool effects, native subagents, frozen file
-mounts, sandbox state, and telemetry. There is no public run resource.
-
-The default sandbox starts preparing in the background when session creation
-commits, then suspends when no tool call is waiting. A sandbox tool call waits
-for the exact generation to become ready and resumes it when required. Set
-`sandbox.enabled` to `false` to allocate no sandbox; sandbox-only tools then
-return a structured error the model can handle.
-
-Cancel stops active work and returns the session to idle. Terminate destroys
-sandbox compute while retaining messages and telemetry. Delete irreversibly
-removes session-owned content; independent workspace files remain.
-
-## Files, tools, and MCP
-
-`aex.workspaceFiles` provides `put`, `upload`, `get`, `list`, `download`, and
-`delete`. Each logical name has only one current value. Inputs may be inline
-text or bytes, an HTTPS URL, or a direct multipart upload. Session creation
-freezes selected names and mount paths, so later overwrites do not change an
-existing session.
-
-Messages are text-only. Upload arbitrary images, PDFs, video, archives, or
-source and tell the model which path under `/workspace` to inspect.
-
-The built-in tool surface is Bash, file read/edit/write, MCP,
-`storage.persist`, and native create/wait/stop subagent tools. Configure remote
-Streamable HTTP or sandbox-process MCP per session. Large tool results keep a
-bounded preview and the full bytes at a sandbox path; `storage.persist`
-publishes a chosen sandbox file as the latest workspace value. Native
-subagents are bounded to 12 child identities per session lifetime and depth 3.
-
-`sessionMessageSend` accepts optional native JSON Schema output through
-`responseFormat`. Strict structured output is admitted only for a qualified
-provider/model capability; AEX does not present prompt emulation as strict.
-
-## Streaming, telemetry, and billing
-
-`sessionMessagesStream` emits bounded preview, gap, committed, reconcile, and
-heartbeat frames. Committed messages preserve provider-neutral text, tool-call,
-and tool-result parts.
-
-Session telemetry is available as a live stream, retained replay, and verified
-compressed download. Billing resources expose prepaid balance, saved-card
-display metadata, hosted card setup and top-up, immutable transactions, and
-usage. Billing methods require `dashboardSession`; session and file methods
-require `apiKey`.
-
-See the [AEX documentation](https://aex.dev/docs) for complete examples.
-
-## Status
-
-AEX is in active prelaunch development. Expect breaking changes and do not rely
-on the hosted service for production workloads yet.
-
-## License
-
-Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+`send()` returns text. `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.

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+import type { ApiError, ApiErrorCode, OutputValidationIssue } from "@aexhq/contracts/session";
+export interface AexErrorOptions {
+    code?: ApiErrorCode | undefined;
+    status?: number | undefined;
+    param?: string | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+export declare class AexError extends Error {
+    readonly code: ApiErrorCode | undefined;
+    readonly status: number | undefined;
+    readonly param: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: AexErrorOptions);
+}
+export declare class OutputSchemaError extends AexError {
+    constructor(message: string, options?: AexErrorOptions);
+}
+export declare class OutputRefusalError extends AexError {
+    constructor(message: string, options?: AexErrorOptions);
+}
+export declare class OutputValidationError extends AexError {
+    readonly issues: readonly OutputValidationIssue[];
+    constructor(message: string, issues?: readonly OutputValidationIssue[], options?: AexErrorOptions);
+}
+export declare class SessionError extends AexError {
+    constructor(message: string, options?: AexErrorOptions);
+}
+export declare class AbortError extends AexError {
+    constructor(message?: string, options?: AexErrorOptions);
+}
+export declare function errorFromApi(error: ApiError, status?: number, issues?: readonly OutputValidationIssue[]): AexError;
+export declare function abortError(cause?: unknown): AbortError;

package/dist/errors.js

@@ -0,0 +1,69 @@
+export class AexError extends Error {
+    code;
+    status;
+    param;
+    requestId;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "AexError";
+        this.code = options.code;
+        this.status = options.status;
+        this.param = options.param;
+        this.requestId = options.requestId;
+    }
+}
+export class OutputSchemaError extends AexError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "output_schema_error" });
+        this.name = "OutputSchemaError";
+    }
+}
+export class OutputRefusalError extends AexError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "output_refused" });
+        this.name = "OutputRefusalError";
+    }
+}
+export class OutputValidationError extends AexError {
+    issues;
+    constructor(message, issues = [], options = {}) {
+        super(message, { ...options, code: "output_validation_error" });
+        this.name = "OutputValidationError";
+        this.issues = issues;
+    }
+}
+export class SessionError extends AexError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SessionError";
+    }
+}
+export class AbortError extends AexError {
+    constructor(message = "The operation was cancelled", options = {}) {
+        super(message, { ...options, code: "cancelled" });
+        this.name = "AbortError";
+    }
+}
+export function errorFromApi(error, status, issues = []) {
+    const options = {
+        code: error.code,
+        status,
+        param: error.param,
+        requestId: error.request_id,
+    };
+    switch (error.code) {
+        case "output_schema_error":
+            return new OutputSchemaError(error.message, options);
+        case "output_refused":
+            return new OutputRefusalError(error.message, options);
+        case "output_validation_error":
+            return new OutputValidationError(error.message, issues, options);
+        case "cancelled":
+            return new AbortError(error.message, options);
+        default:
+            return new SessionError(error.message, options);
+    }
+}
+export function abortError(cause) {
+    return new AbortError("The operation was cancelled", { cause });
+}

package/dist/index.d.ts

@@ -1,23 +1,16 @@
-export { Aex } from "./client/aex.js";
-export type { AexOptions } from "./client/aex.js";
-export { DashboardSession, WorkspaceApiKey, parseCredential, regionalHost, } from "./client/credentials.js";
-export type { ParsedCredential, RegionCode } from "./client/credentials.js";
-export { resolveCentralBaseUrl, resolveRegionalBaseUrl } from "./client/routing.js";
-export type { RegionalRoutingOptions } from "./client/routing.js";
-export { AexApiError, AexAuthError, AexConfigError, AexConflictError, AexError, AexGoneError, AexInternalError, AexNotFoundError, AexPreconditionError, AexQuotaError, AexStateError, AexStreamProtocolError, AexUnavailableError, AexValidationError, apiErrorFromResponse, isRetryable, } from "./transport/errors.js";
-export type { AexErrorCode } from "./transport/errors.js";
-export { RETRY_POLICY, executeWithRetry } from "./transport/retry.js";
-export { FetchTransport } from "./transport/transport.js";
-export type { AexTransport, WireRequest, WireResponse, WireStreamResponse } from "./transport/transport.js";
-export { Page } from "./transport/pagination.js";
-export { WorkspaceFiles } from "./files/workspace-files.js";
-export type { CurrentWorkspaceFile, WorkspaceFileInput, WorkspaceFilePutOptions, } from "./files/workspace-files.js";
-export { Download, MAX_SINGLE_GET_BYTES, planDownloadRanges } from "./downloads/download.js";
-export type { DownloadRange } from "./downloads/download.js";
-export { parseNdjsonFrames } from "./observations/stream.js";
-export { ERROR_METADATA } from "./generated/errors.js";
-export type { ErrorClass } from "./generated/errors.js";
-export { ROUTES } from "./generated/routes.js";
-export type { RouteDescriptor, RouteId } from "./generated/routes.js";
-export * from "./generated/models.js";
-export type { ExecuteOptions, ResourceExecutor } from "./generated/resources.js";
+import { Sessions } from "./session.js";
+import type { Fetch } from "./transport.js";
+export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
+export type { AexErrorOptions } from "./errors.js";
+export { Session, Sessions, } from "./session.js";
+export type { CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export type { EventOptions } from "./transport.js";
+export interface AexOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: Fetch;
+}
+export declare class Aex {
+    readonly sessions: Sessions;
+    constructor(options: AexOptions);
+}

package/dist/index.js

@@ -1,16 +1,18 @@
-export { Aex } from "./client/aex.js";
-export { DashboardSession, WorkspaceApiKey, parseCredential, regionalHost, } from "./client/credentials.js";
-export { resolveCentralBaseUrl, resolveRegionalBaseUrl } from "./client/routing.js";
-export { AexApiError, AexAuthError, AexConfigError, AexConflictError, AexError, AexGoneError, AexInternalError, AexNotFoundError, AexPreconditionError, AexQuotaError, AexStateError, AexStreamProtocolError, AexUnavailableError, AexValidationError, apiErrorFromResponse, isRetryable, } from "./transport/errors.js";
-export { RETRY_POLICY, executeWithRetry } from "./transport/retry.js";
-export { FetchTransport } from "./transport/transport.js";
-export { Page } from "./transport/pagination.js";
-export { WorkspaceFiles } from "./files/workspace-files.js";
-export { Download, MAX_SINGLE_GET_BYTES, planDownloadRanges } from "./downloads/download.js";
-export { parseNdjsonFrames } from "./observations/stream.js";
-export { ERROR_METADATA } from "./generated/errors.js";
-export { ROUTES } from "./generated/routes.js";
-// Models and identifier constructors are emitted from the authored contract.
-// Re-exporting them here keeps application code on one dependency-free package.
-export * from "./generated/models.js";
-//# sourceMappingURL=index.js.map
+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";
+const DEFAULT_API_URL = "https://api.aex.dev";
+export class Aex {
+    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);
+        this.sessions = new Sessions(transport);
+    }
+}

package/dist/json.d.ts

@@ -0,0 +1,4 @@
+/** RFC 8785 canonical JSON. Object keys sort by UTF-16 code units, as required by JCS. */
+export declare function canonicalize(value: unknown): string;
+export declare function jcsSha256(value: unknown): Promise<string>;
+export declare function randomIdempotencyKey(): string;

package/dist/json.js

@@ -0,0 +1,46 @@
+import { OutputSchemaError, SessionError } from "./errors.js";
+/** RFC 8785 canonical JSON. Object keys sort by UTF-16 code units, as required by JCS. */
+export function canonicalize(value) {
+    const visit = (current) => {
+        if (Array.isArray(current))
+            return current.map(visit);
+        if (current !== null && typeof current === "object") {
+            const object = current;
+            return Object.fromEntries(Object.keys(object)
+                .filter((key) => object[key] !== undefined)
+                .sort()
+                .map((key) => [key, visit(object[key])]));
+        }
+        if (typeof current === "number" && !Number.isFinite(current)) {
+            throw new OutputSchemaError("The output schema contains a non-finite number");
+        }
+        return current;
+    };
+    const encoded = JSON.stringify(visit(value));
+    if (encoded === undefined) {
+        throw new OutputSchemaError("The output schema is not JSON-serialisable");
+    }
+    return encoded;
+}
+export async function jcsSha256(value) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        throw new OutputSchemaError("This runtime does not provide Web Crypto SHA-256 support");
+    }
+    const bytes = new TextEncoder().encode(canonicalize(value));
+    const digest = await subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function randomIdempotencyKey() {
+    const crypto = globalThis.crypto;
+    if (crypto === undefined) {
+        throw new SessionError("This runtime does not provide secure random values");
+    }
+    if (typeof crypto.randomUUID === "function")
+        return crypto.randomUUID();
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}

package/dist/session.d.ts

@@ -0,0 +1,74 @@
+import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/contracts/session";
+import * as z from "zod";
+import type { EventOptions } from "./transport.js";
+import { Transport } from "./transport.js";
+export type SessionInput = string;
+export interface ModelOptions {
+    provider: Provider;
+    name: string;
+    apiKey: string;
+    baseUrl?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    reasoningEffort?: "low" | "medium" | "high";
+}
+export interface CreateSessionOptions {
+    model: ModelOptions;
+    systemPrompt?: string;
+    metadata?: Record<string, string>;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+export interface OutputOptions extends RequestOptions {
+}
+export interface ListSessionsOptions {
+    limit?: number;
+    cursor?: string;
+    state?: SessionState;
+    signal?: AbortSignal;
+}
+export interface SessionList {
+    data: Session[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface ModelSummary {
+    provider: Provider;
+    name: string;
+    baseUrl?: string;
+}
+export interface SessionSummary {
+    id: string;
+    state: SessionState;
+    model: ModelSummary;
+    createdAt: string;
+    updatedAt: string;
+    metadata: Readonly<Record<string, string | undefined>>;
+}
+export declare class Sessions {
+    #private;
+    constructor(transport: Transport);
+    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;
+    constructor(transport: Transport, data: SessionData);
+    get id(): string;
+    get state(): SessionState;
+    get model(): ModelSummary;
+    get createdAt(): string;
+    get updatedAt(): string;
+    get metadata(): Readonly<Record<string, string | undefined>>;
+    refresh(options?: Pick<RequestOptions, "signal">): Promise<this>;
+    send(input: SessionInput, options?: RequestOptions): Promise<string>;
+    output<Schema extends z.ZodType>(schema: Schema, input?: SessionInput, options?: OutputOptions): Promise<z.output<Schema>>;
+    events(options?: EventOptions): AsyncGenerator<Event>;
+    cancel(options?: Pick<RequestOptions, "signal">): Promise<this>;
+    delete(options?: Pick<RequestOptions, "signal">): Promise<void>;
+    private markIdle;
+}