@aexhq/sdk 0.54.1 → 0.55.0

package/README.md

@@ -1,131 +1,24 @@
 # @aexhq/sdk
 
-The TypeScript SDK for Aex, with no dependencies of its own.
-
-```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.",
+);
 ```
 
-Creating a session takes the exact provider and model you want plus your own
-`providerApiKey`, which is write only. That key is encrypted for the session,
-never returned, and never shared with another one. You can use OpenAI,
-Anthropic, DeepSeek, xAI, Meta, Moonshot AI, and Alibaba.
-
-## The client
-
-Session and file calls use a workspace `apiKey`. Account, API key, and billing
-calls use a `dashboardSession` from signing in with GitHub. One client can hold
-both, and it only ever sends each one to the service it belongs to.
-
-```ts
-const aex = new Aex({
-  apiKey: process.env.AEX_WORKSPACE_API_KEY!,
-  dashboardSession: process.env.AEX_DASHBOARD_SESSION!,
-});
-```
-
-The namespaces are `apiKeys`, `auth`, `billing`, `bootstrap`, `registry`,
-`sessions`, and `uploads`. `aex.workspaceFiles` adds friendlier helpers for
-working with files. `ROUTES` and `aex.execute(...)` give you the same generated
-contract directly, so there is no second route table to keep in step.
-
-## Sessions and machines
-
-A session is the only thing you create. It holds the conversation, the work in
-flight, the tools it has used, its helper agents, its mounted files, its
-machine, and its telemetry.
-
-Every session gets a Linux machine unless you turn it off. It starts warming up
-as soon as the session is created and goes to sleep when nothing is running.
-The next tool call waits for it and wakes it if needed. Set `sandbox.enabled`
-to `false` to get no machine at all; tools that need one then return a clear
-error the model can handle.
-
-Cancel ends the current work and leaves the session idle. Terminate destroys
-the machine but keeps the messages and telemetry. Delete removes everything the
-session owns; files you uploaded to the workspace survive.
-
-## Files, tools, and MCP
-
-`aex.workspaceFiles` gives you `put`, `upload`, `get`, `list`, `download`, and
-`delete`. Each name has one current value, which you can set from text or
-bytes, an HTTPS link, or a direct upload. Creating a session pins the names and
-paths it uses, so replacing a file later cannot change a session already
-running.
-
-Messages are text only. Upload images, PDFs, video, archives, or source, then
-tell the model which path under `/workspace` to look at.
-
-Out of the box the model gets Bash, file read, edit, and write, MCP,
-`storage.persist`, and tools to start, wait for, and stop helper agents. Attach
-MCP servers per session, either over HTTP or as a process on the machine. A
-large tool result leaves a short preview in the transcript and keeps the full
-bytes on the machine, and `storage.persist` saves a chosen file back to your
-workspace. A session can start at most 12 helper agents, nested no more than
-three deep.
-
-`sessionMessageSend` takes an optional `responseFormat` for JSON Schema output.
-Aex allows it only when the provider and model support it natively, and will
-not pass prompting off as the real thing.
-
-## Streaming, telemetry, and billing
-
-`sessionMessagesStream` sends preview, gap, committed, reconcile, and heartbeat
-frames. Committed messages keep text, tool calls, and tool results in the same
-shape whichever provider you use.
-
-Telemetry comes as a live stream, a replay, and a verified compressed download.
-The billing methods cover your prepaid balance, saved card details, hosted card
-setup and top up, a permanent record of transactions, and usage. Billing needs
-`dashboardSession`; sessions and files need `apiKey`.
-
-See the [Aex documentation](https://aex.dev/docs) for fuller 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;
+}