@aexhq/sdk 0.39.0 → 0.40.0

package/README.md

@@ -19,9 +19,11 @@ The package ships:
 npm i @aexhq/sdk
 ```
 
-This installs the TypeScript SDK exports and the bundled `aex` CLI. Set both
-credentials before running the examples: `AEX_API_KEY` authenticates to aex,
-and `ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
+This installs the TypeScript SDK exports and the bundled `aex` CLI. The CLI
+ships inside the package — invoke it with `npx aex …` after a local install, or
+`npm i -g @aexhq/sdk` to put a bare `aex` on your PATH. Set both credentials
+before running the examples: `AEX_API_KEY` authenticates to aex, and
+`ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
 
 ```bash
 export AEX_API_KEY="<your-aex-api-key>"
@@ -33,7 +35,7 @@ export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
 ```ts
 import { Aex, Models, Sizes } from "@aexhq/sdk";
 
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+const aex = new Aex(process.env.AEX_API_KEY!);
 
 const session = await aex.openSession({
   model: Models.CLAUDE_HAIKU_4_5,
@@ -44,8 +46,10 @@ const session = await aex.openSession({
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 
+// done() awaits settle by default, so status is the terminal outcome
+// ("succeeded"), and costUsd/usage are populated.
 const first = await session.send("Summarize this repo.").done();
-console.log(first.status, first.text);
+console.log(first.status, first.costUsd, first.text);
 
 const resumed = await aex.openSession(session.id);
 await resumed.send("Continue with the follow-up validation.").done();
@@ -78,10 +82,10 @@ await aex.run({
 });
 ```
 
-The same request can run from the bundled CLI:
+The same request can run from the bundled CLI (`npx aex` on a local install):
 
 ```bash
-aex run \
+npx aex run \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
@@ -97,20 +101,22 @@ your default `--aex-url`) is persisted to a `0600` config file
 on Windows). An explicit `--api-key` flag always overrides the stored one.
 
 ```bash
-aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
-aex whoami            # no --api-key needed after login
-aex auth status       # show the resolved config (the token value is never printed)
-aex logout            # clear the stored token
+npx aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
+npx aex whoami            # no --api-key needed after login
+npx aex whoami --json     # machine-readable workspace + scopes + limits
+npx aex auth status       # show the resolved config (the token value is never printed)
+npx aex logout            # clear the stored token
 ```
 
 Discover the closed sets the platform accepts — no token, no network (human table
-by default, machine JSON under `--json`):
+by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
 
 ```bash
-aex models list           # canonical models + their default provider
-aex providers list        # providers + the models each serves
-aex tools list            # complete builtin tool set
-aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
+npx aex models list           # canonical models + their default provider
+npx aex providers list        # providers + the models each serves
+npx aex tools list            # complete builtin tool set
+npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
+npx aex run --help            # flags for one verb (no API key required)
 ```
 
 Errors are typed and actionable. Every `openSession()` / `run()` config-validation

package/dist/_contracts/api-key.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Self-describing API-key codec (SSoT).
+ *
+ * An aex API key is `aex_<plane>_<regionCode>_<workspaceId>_<secret>_<crc>` —
+ * it embeds its own plane and region, CRC-protected. This is the canonical
+ * client-side codec: the SDK constructor parses the key to DERIVE the target
+ * plane (zero-network) and to fail fast on a plane/baseUrl mismatch instead of
+ * surfacing a bare `token_invalid` after a full round-trip.
+ *
+ * Ported byte-for-byte from the platform codec
+ * (`aex-platform apps/dashboard/src/server/auth.ts`), which is pinned to this
+ * module by a cross-repo parity test. Parse-only: it makes NO trust decision
+ * (the server still validates the secret).
+ */
+export declare const API_KEY_PLANES: readonly ["dev", "prd"];
+export type ApiKeyPlane = (typeof API_KEY_PLANES)[number];
+/** Supported region → embedded region code. */
+export declare const API_KEY_REGION_TO_CODE: Readonly<Record<string, string>>;
+export interface ParsedApiKey {
+    readonly plane: ApiKeyPlane;
+    readonly regionCode: string;
+    readonly region: string;
+    /** The dash-free workspace id embedded in the key. */
+    readonly workspaceId: string;
+}
+/**
+ * Canonical form of a workspaceId for EMBEDDING in a key: dashes stripped so the
+ * whole key is a single double-click-selectable word (`_` is a word char, `-`
+ * is not). Kept byte-for-byte in sync with the platform codec.
+ */
+export declare function normalizeWorkspaceId(workspaceId: string): string;
+/**
+ * Parse a self-describing API key, or `null` for any legacy/opaque/tampered
+ * value. Validates the `aex_` prefix, the 6-part shape, a known plane and
+ * region code, and the CRC over the first 5 parts.
+ */
+export declare function parseApiKey(token: string): ParsedApiKey | null;
+/**
+ * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
+ * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
+ * deterministic — used by codec round-trip / cross-repo parity tests. The
+ * embedded workspace id is dash-normalized; `workspaceId` must not contain `_`.
+ */
+export declare function formatApiKey(input: {
+    readonly plane: ApiKeyPlane;
+    readonly region: string;
+    readonly workspaceId: string;
+    readonly secret: string;
+}): string;

package/dist/_contracts/api-key.js

@@ -0,0 +1,87 @@
+/**
+ * Self-describing API-key codec (SSoT).
+ *
+ * An aex API key is `aex_<plane>_<regionCode>_<workspaceId>_<secret>_<crc>` —
+ * it embeds its own plane and region, CRC-protected. This is the canonical
+ * client-side codec: the SDK constructor parses the key to DERIVE the target
+ * plane (zero-network) and to fail fast on a plane/baseUrl mismatch instead of
+ * surfacing a bare `token_invalid` after a full round-trip.
+ *
+ * Ported byte-for-byte from the platform codec
+ * (`aex-platform apps/dashboard/src/server/auth.ts`), which is pinned to this
+ * module by a cross-repo parity test. Parse-only: it makes NO trust decision
+ * (the server still validates the secret).
+ */
+export const API_KEY_PLANES = ["dev", "prd"];
+/** Supported region → embedded region code. */
+export const API_KEY_REGION_TO_CODE = {
+    "eu-west-2": "euw2",
+    "us-west-2": "usw2",
+    "ap-northeast-1": "apn1"
+};
+const CODE_TO_REGION = Object.fromEntries(Object.entries(API_KEY_REGION_TO_CODE).map(([region, code]) => [code, region]));
+const API_KEY_PLANE_SET = new Set(API_KEY_PLANES);
+/**
+ * Canonical form of a workspaceId for EMBEDDING in a key: dashes stripped so the
+ * whole key is a single double-click-selectable word (`_` is a word char, `-`
+ * is not). Kept byte-for-byte in sync with the platform codec.
+ */
+export function normalizeWorkspaceId(workspaceId) {
+    return workspaceId.replace(/-/g, "");
+}
+/**
+ * Parse a self-describing API key, or `null` for any legacy/opaque/tampered
+ * value. Validates the `aex_` prefix, the 6-part shape, a known plane and
+ * region code, and the CRC over the first 5 parts.
+ */
+export function parseApiKey(token) {
+    if (typeof token !== "string" || !token.startsWith("aex_"))
+        return null;
+    const parts = token.split("_");
+    if (parts.length !== 6)
+        return null;
+    const [prefix, plane, regionCode, workspaceId, secret, crc] = parts;
+    if (prefix !== "aex" || !API_KEY_PLANE_SET.has(plane) || !regionCode || !workspaceId || !secret || !crc) {
+        return null;
+    }
+    if (crc32Base36(parts.slice(0, 5).join("_")) !== crc)
+        return null;
+    const region = CODE_TO_REGION[regionCode];
+    if (region === undefined)
+        return null;
+    return { plane: plane, regionCode, region, workspaceId };
+}
+/**
+ * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
+ * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
+ * deterministic — used by codec round-trip / cross-repo parity tests. The
+ * embedded workspace id is dash-normalized; `workspaceId` must not contain `_`.
+ */
+export function formatApiKey(input) {
+    const code = API_KEY_REGION_TO_CODE[input.region];
+    if (code === undefined) {
+        throw new Error(`API key region is not supported: ${input.region}`);
+    }
+    if (!input.workspaceId || input.workspaceId.includes("_")) {
+        throw new Error("workspaceId must be non-empty and contain no '_'");
+    }
+    if (!input.secret || input.secret.includes("_")) {
+        throw new Error("secret must be non-empty and contain no '_'");
+    }
+    const body = ["aex", input.plane, code, normalizeWorkspaceId(input.workspaceId), input.secret].join("_");
+    return `${body}_${crc32Base36(body)}`;
+}
+function crc32Base36(input) {
+    return crc32(input).toString(36);
+}
+function crc32(input) {
+    let crc = 0xffffffff;
+    for (const byte of Buffer.from(input, "utf8")) {
+        crc ^= byte;
+        for (let i = 0; i < 8; i += 1) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+//# sourceMappingURL=api-key.js.map

package/dist/_contracts/bundle-manifest.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Bundle fidelity sidecar — the shared source of truth for the `.aexmeta.json`
+ * metadata entry that rides inside a canonical bundle zip.
+ *
+ * A canonical bundle (skill / tool / file / agentsMd) is a deterministic zip of
+ * regular files. fflate's `unzipSync` on the restore side is asymmetric: it
+ * surfaces only entry bytes, never external attributes / os field / symlink
+ * flags. So exec bits and symlinks — the metadata a local dir → zip →
+ * container-restore round-trip must preserve — cannot travel in the zip's
+ * external attributes and be read back. Instead they travel in ONE reserved
+ * entry, `.aexmeta.json`, which both the SDK (encode) and the container
+ * materializer (restore) agree on. This module is that agreement.
+ *
+ * SECURITY: {@link symlinkTargetEscapes} is a restore-time boundary — it decides
+ * whether a captured symlink target may be recreated on the container FS. It is
+ * PURELY LEXICAL (no realpath, no FS access → no TOCTOU) and is fuzzed. Both
+ * repos import it; do not fork it.
+ *
+ * Determinism: the sidecar is emitted ONLY when there is metadata to carry (exec
+ * or symlinks non-empty) and is serialized canonically (fixed field order, sorted
+ * arrays, no insignificant whitespace, no trailing newline). A pure-content
+ * bundle emits NO sidecar → its bytes stay identical to the pre-fidelity output,
+ * so existing content-addressed dedup is preserved.
+ */
+/** Reserved zip entry carrying the fidelity sidecar. Rejected as a user file path. */
+export declare const RESERVED_META_ENTRY = ".aexmeta.json";
+/** Normalised mode for an executable regular file (has any exec bit). */
+export declare const EXEC_MODE = 493;
+/** Normalised mode for an ordinary regular file. */
+export declare const DEFAULT_FILE_MODE = 420;
+/** Bundle-time cap on a captured symlink target string. */
+export declare const MAX_SYMLINK_TARGET_LENGTH = 4096;
+/** A captured symlink: `path` is the bundle-relative link name, `target` the raw `readlink()` string. */
+export interface BundleSymlink {
+    readonly path: string;
+    readonly target: string;
+}
+/**
+ * The fidelity sidecar. `exec` lists the bundle-relative paths that restore to
+ * {@link EXEC_MODE} (all other files stay {@link DEFAULT_FILE_MODE}); `symlinks`
+ * lists links to recreate (subject to {@link symlinkTargetEscapes}).
+ */
+export interface BundleManifest {
+    readonly v: 1;
+    readonly exec: readonly string[];
+    readonly symlinks: readonly BundleSymlink[];
+}
+/** True when a manifest carries no metadata worth emitting (so no sidecar is written). */
+export declare function bundleManifestIsEmpty(manifest: {
+    readonly exec?: readonly string[];
+    readonly symlinks?: readonly {
+        readonly path: string;
+    }[];
+}): boolean;
+/**
+ * Serialize a manifest to canonical, byte-stable UTF-8 bytes: fixed field order
+ * (`v`, `exec`, `symlinks`), `exec` sorted ascending, `symlinks` sorted by
+ * `path`, no insignificant whitespace (compact JSON), no trailing newline. Two
+ * equal manifests always serialize to identical bytes → the sidecar never
+ * perturbs dedup determinism.
+ */
+export declare function serializeBundleManifest(manifest: BundleManifest): Uint8Array;
+/**
+ * Parse the sidecar bytes into a validated {@link BundleManifest}, or `null` when
+ * the bytes are absent, not valid canonical JSON, or carry an unknown version.
+ * Forward-compatible: an unknown `v` yields `null` so a restore falls back to
+ * content-only (metadata is dropped, never a hard failure). Structurally-invalid
+ * entries are dropped individually; the parse never throws.
+ */
+export declare function parseBundleManifest(bytes: Uint8Array | null | undefined): BundleManifest | null;
+/**
+ * SECURITY boundary — decide whether recreating a symlink `linkRelPath` → `target`
+ * would let the link escape the bundle root. PURELY LEXICAL (no realpath / no FS
+ * access → no TOCTOU). Returns `true` (REJECT / do not create) when ANY of:
+ *
+ *   - `target` is empty or contains a NUL;
+ *   - `target` is absolute — starts with `/`, matches a Windows drive (`C:`), is a
+ *     UNC path (`\\host`), or contains any backslash;
+ *   - the lexically-resolved target (join the link's dirname with the target, then
+ *     normalise `.`/`..`) climbs at or above the bundle root (leading `..`).
+ *
+ * Otherwise the link is relative and resolves to a path inside (or at) the bundle
+ * root — safe to recreate with the ORIGINAL relative `target`. A dangling in-root
+ * target (pointing at a not-yet-existing sibling) is SAFE and allowed.
+ */
+export declare function symlinkTargetEscapes(linkRelPath: string, target: string): boolean;

package/dist/_contracts/bundle-manifest.js

@@ -0,0 +1,157 @@
+/**
+ * Bundle fidelity sidecar — the shared source of truth for the `.aexmeta.json`
+ * metadata entry that rides inside a canonical bundle zip.
+ *
+ * A canonical bundle (skill / tool / file / agentsMd) is a deterministic zip of
+ * regular files. fflate's `unzipSync` on the restore side is asymmetric: it
+ * surfaces only entry bytes, never external attributes / os field / symlink
+ * flags. So exec bits and symlinks — the metadata a local dir → zip →
+ * container-restore round-trip must preserve — cannot travel in the zip's
+ * external attributes and be read back. Instead they travel in ONE reserved
+ * entry, `.aexmeta.json`, which both the SDK (encode) and the container
+ * materializer (restore) agree on. This module is that agreement.
+ *
+ * SECURITY: {@link symlinkTargetEscapes} is a restore-time boundary — it decides
+ * whether a captured symlink target may be recreated on the container FS. It is
+ * PURELY LEXICAL (no realpath, no FS access → no TOCTOU) and is fuzzed. Both
+ * repos import it; do not fork it.
+ *
+ * Determinism: the sidecar is emitted ONLY when there is metadata to carry (exec
+ * or symlinks non-empty) and is serialized canonically (fixed field order, sorted
+ * arrays, no insignificant whitespace, no trailing newline). A pure-content
+ * bundle emits NO sidecar → its bytes stay identical to the pre-fidelity output,
+ * so existing content-addressed dedup is preserved.
+ */
+/** Reserved zip entry carrying the fidelity sidecar. Rejected as a user file path. */
+export const RESERVED_META_ENTRY = ".aexmeta.json";
+/** Normalised mode for an executable regular file (has any exec bit). */
+export const EXEC_MODE = 0o755;
+/** Normalised mode for an ordinary regular file. */
+export const DEFAULT_FILE_MODE = 0o644;
+/** Bundle-time cap on a captured symlink target string. */
+export const MAX_SYMLINK_TARGET_LENGTH = 4096;
+/** True when a manifest carries no metadata worth emitting (so no sidecar is written). */
+export function bundleManifestIsEmpty(manifest) {
+    return (manifest.exec?.length ?? 0) === 0 && (manifest.symlinks?.length ?? 0) === 0;
+}
+const META_TEXT_ENCODER = new TextEncoder();
+const META_TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+/**
+ * Serialize a manifest to canonical, byte-stable UTF-8 bytes: fixed field order
+ * (`v`, `exec`, `symlinks`), `exec` sorted ascending, `symlinks` sorted by
+ * `path`, no insignificant whitespace (compact JSON), no trailing newline. Two
+ * equal manifests always serialize to identical bytes → the sidecar never
+ * perturbs dedup determinism.
+ */
+export function serializeBundleManifest(manifest) {
+    const exec = [...manifest.exec].sort(byString);
+    const symlinks = [...manifest.symlinks]
+        .map((s) => ({ path: s.path, target: s.target }))
+        .sort((a, b) => byString(a.path, b.path));
+    // Object literal key order is the wire order under JSON.stringify (fixed).
+    const json = JSON.stringify({ v: 1, exec, symlinks });
+    return META_TEXT_ENCODER.encode(json);
+}
+/**
+ * Parse the sidecar bytes into a validated {@link BundleManifest}, or `null` when
+ * the bytes are absent, not valid canonical JSON, or carry an unknown version.
+ * Forward-compatible: an unknown `v` yields `null` so a restore falls back to
+ * content-only (metadata is dropped, never a hard failure). Structurally-invalid
+ * entries are dropped individually; the parse never throws.
+ */
+export function parseBundleManifest(bytes) {
+    if (!bytes || bytes.byteLength === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(META_TEXT_DECODER.decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    if (record.v !== 1)
+        return null;
+    const exec = [];
+    if (Array.isArray(record.exec)) {
+        for (const item of record.exec) {
+            if (typeof item === "string" && item.length > 0)
+                exec.push(item);
+        }
+    }
+    const symlinks = [];
+    if (Array.isArray(record.symlinks)) {
+        for (const item of record.symlinks) {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                continue;
+            const rec = item;
+            const path = rec.path;
+            const target = rec.target;
+            if (typeof path === "string" && path.length > 0 && typeof target === "string") {
+                symlinks.push({ path, target });
+            }
+        }
+    }
+    return { v: 1, exec, symlinks };
+}
+/**
+ * SECURITY boundary — decide whether recreating a symlink `linkRelPath` → `target`
+ * would let the link escape the bundle root. PURELY LEXICAL (no realpath / no FS
+ * access → no TOCTOU). Returns `true` (REJECT / do not create) when ANY of:
+ *
+ *   - `target` is empty or contains a NUL;
+ *   - `target` is absolute — starts with `/`, matches a Windows drive (`C:`), is a
+ *     UNC path (`\\host`), or contains any backslash;
+ *   - the lexically-resolved target (join the link's dirname with the target, then
+ *     normalise `.`/`..`) climbs at or above the bundle root (leading `..`).
+ *
+ * Otherwise the link is relative and resolves to a path inside (or at) the bundle
+ * root — safe to recreate with the ORIGINAL relative `target`. A dangling in-root
+ * target (pointing at a not-yet-existing sibling) is SAFE and allowed.
+ */
+export function symlinkTargetEscapes(linkRelPath, target) {
+    if (typeof target !== "string" || target.length === 0)
+        return true;
+    if (target.includes("\0"))
+        return true;
+    // Absolute / platform-specific targets are always rejected.
+    if (target.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(target))
+        return true;
+    if (target.includes("\\"))
+        return true;
+    // Lexically resolve relative to the link's own directory.
+    const linkDir = posixDirname(linkRelPath);
+    const joined = linkDir.length > 0 ? `${linkDir}/${target}` : target;
+    const stack = [];
+    for (const segment of joined.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            // Pop an in-root component, or record an escaping climb.
+            if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+                stack.pop();
+            }
+            else {
+                stack.push("..");
+            }
+        }
+        else {
+            stack.push(segment);
+        }
+    }
+    // A leading `..` means the resolved path is at or above the bundle root.
+    return stack.length > 0 && stack[0] === "..";
+}
+/** POSIX dirname of a forward-slash relative path ("" when there is no parent segment). */
+function posixDirname(path) {
+    const idx = path.lastIndexOf("/");
+    return idx <= 0 ? "" : path.slice(0, idx);
+}
+function byString(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=bundle-manifest.js.map

package/dist/_contracts/error-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SSoT for the platform's STABLE API error codes.
+ *
+ * The server (aex-platform `api.ts`) imports this table instead of keeping its
+ * own private copy, so a route emitting a code absent from the union fails to
+ * compile and adding a code without a message is caught. The SDK error factory
+ * ({@link import("./error-factory.js").apiErrorFromResponse}) dispatches on the
+ * code to a typed subclass; the CLI maps it to a human remedy.
+ *
+ * The code is the stable, machine-branchable identity of a failure — distinct
+ * from the human `message`. `idempotency_conflict` and `insufficient_scope`
+ * (previously message-less bare 409/403 bodies) are first-class here.
+ */
+export declare const AEX_API_ERROR_CODES: readonly ["unauthorized", "forbidden", "insufficient_scope", "token_invalid", "token_revoked", "token_expired", "malformed_token", "not_found", "idempotency_conflict", "session_busy", "run_not_terminal", "unknown_workspace", "workspace_concurrency_exceeded", "workspace_submit_rate_exceeded", "workspace_spend_cap_exceeded", "insufficient_balance", "rate_limited", "upstream_error", "internal_error"];
+export type AexApiErrorCode = (typeof AEX_API_ERROR_CODES)[number];
+/**
+ * Human message per stable code. A `Record` (not `Partial`) so a code added to
+ * {@link AEX_API_ERROR_CODES} without a message is a COMPILE error. These are
+ * the fallback messages the factory uses when the server sends a BARE code with
+ * no `message` detail.
+ */
+export declare const AEX_API_ERROR_MESSAGES: Record<AexApiErrorCode, string>;
+/** Optional per-code fix hint the CLI surfaces alongside the error message. */
+export declare const AEX_API_ERROR_REMEDIES: Partial<Record<AexApiErrorCode, string>>;
+/** Narrow an arbitrary value to a known {@link AexApiErrorCode}. */
+export declare function isAexApiErrorCode(value: unknown): value is AexApiErrorCode;

package/dist/_contracts/error-codes.js

@@ -0,0 +1,79 @@
+/**
+ * SSoT for the platform's STABLE API error codes.
+ *
+ * The server (aex-platform `api.ts`) imports this table instead of keeping its
+ * own private copy, so a route emitting a code absent from the union fails to
+ * compile and adding a code without a message is caught. The SDK error factory
+ * ({@link import("./error-factory.js").apiErrorFromResponse}) dispatches on the
+ * code to a typed subclass; the CLI maps it to a human remedy.
+ *
+ * The code is the stable, machine-branchable identity of a failure — distinct
+ * from the human `message`. `idempotency_conflict` and `insufficient_scope`
+ * (previously message-less bare 409/403 bodies) are first-class here.
+ */
+export const AEX_API_ERROR_CODES = [
+    "unauthorized",
+    "forbidden",
+    "insufficient_scope",
+    "token_invalid",
+    "token_revoked",
+    "token_expired",
+    "malformed_token",
+    "not_found",
+    "idempotency_conflict",
+    "session_busy",
+    "run_not_terminal",
+    "unknown_workspace",
+    "workspace_concurrency_exceeded",
+    "workspace_submit_rate_exceeded",
+    "workspace_spend_cap_exceeded",
+    "insufficient_balance",
+    "rate_limited",
+    "upstream_error",
+    "internal_error"
+];
+/**
+ * Human message per stable code. A `Record` (not `Partial`) so a code added to
+ * {@link AEX_API_ERROR_CODES} without a message is a COMPILE error. These are
+ * the fallback messages the factory uses when the server sends a BARE code with
+ * no `message` detail.
+ */
+export const AEX_API_ERROR_MESSAGES = {
+    unauthorized: "The request was not authenticated.",
+    forbidden: "The API key is not permitted to perform this action.",
+    insufficient_scope: "The API key is missing a scope this endpoint requires.",
+    token_invalid: "The API key is not valid.",
+    token_revoked: "The API key has been revoked.",
+    token_expired: "The API key has expired.",
+    malformed_token: "The API key is malformed.",
+    not_found: "The requested resource was not found.",
+    idempotency_conflict: "This idempotency key was already used with a different request body.",
+    session_busy: "The session is busy handling another turn.",
+    run_not_terminal: "The run has not reached a terminal state yet.",
+    unknown_workspace: "The workspace could not be resolved from the API key.",
+    workspace_concurrency_exceeded: "The workspace has reached its concurrent-run limit.",
+    workspace_submit_rate_exceeded: "The workspace submit-rate limit was exceeded.",
+    workspace_spend_cap_exceeded: "The workspace monthly spend cap was reached.",
+    insufficient_balance: "The workspace prepaid balance is insufficient to submit this run.",
+    rate_limited: "Too many requests — retry after a short backoff.",
+    upstream_error: "An upstream provider returned an error.",
+    internal_error: "The aex API encountered an internal error."
+};
+/** Optional per-code fix hint the CLI surfaces alongside the error message. */
+export const AEX_API_ERROR_REMEDIES = {
+    insufficient_scope: "Mint an API key that includes the scope this endpoint requires.",
+    idempotency_conflict: "Use a fresh idempotency key, or resubmit the byte-identical request body to replay the original result.",
+    token_invalid: "Check the API key value and that its plane matches your baseUrl.",
+    token_expired: "Mint a new API key.",
+    token_revoked: "Mint a new API key.",
+    workspace_spend_cap_exceeded: "Raise the workspace spend cap or wait for the next billing cycle.",
+    insufficient_balance: "Top up the workspace balance or add a payment method.",
+    workspace_concurrency_exceeded: "Wait for in-flight runs to finish or raise the concurrency limit.",
+    workspace_submit_rate_exceeded: "Slow the submit rate or raise the workspace submit-rate limit."
+};
+const API_ERROR_CODE_SET = new Set(AEX_API_ERROR_CODES);
+/** Narrow an arbitrary value to a known {@link AexApiErrorCode}. */
+export function isAexApiErrorCode(value) {
+    return typeof value === "string" && API_ERROR_CODE_SET.has(value);
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/_contracts/error-factory.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The SINGLE wire→exception mapping. `apiErrorFromResponse` reads a non-2xx
+ * body's stable `error` code, attaches it (typed) as `apiCode` plus the
+ * `requestId`, and dispatches to the right {@link AexApiError} subclass. Both
+ * `HttpClient.request` and `HttpClient.download` construct errors ONLY through
+ * here, so the wire→exception mapping lives in one place — no inline
+ * `new AexApiError(...)` with a hardcoded coarse code.
+ */
+import { AexApiError } from "./sdk-errors.js";
+import { type AexApiErrorCode } from "./error-codes.js";
+export interface ApiErrorFromResponseInput {
+    readonly status: number;
+    readonly body: unknown;
+    /**
+     * Precomputed human message (e.g. `HttpClient`'s `extractErrorMessage`). When
+     * absent the factory derives one from the stable code table.
+     */
+    readonly message?: string;
+    readonly requestId?: string;
+    readonly cause?: unknown;
+}
+type ApiErrorKind = "auth" | "idempotency" | "not_found" | "rate_limit" | "generic";
+/**
+ * EXHAUSTIVE stable-code → subclass-kind map. There is NO `default`: adding a
+ * code to {@link AEX_API_ERROR_CODES} without a case here fails to compile
+ * (the function would fall through and return `undefined`, which the
+ * `ApiErrorKind` return type forbids). This is the whole-class guard that a new
+ * server code can never silently collapse to the base error.
+ */
+export declare function apiErrorKindForCode(code: AexApiErrorCode): ApiErrorKind;
+export declare function apiErrorFromResponse(input: ApiErrorFromResponseInput): AexApiError;
+export {};