@aexhq/sdk 0.46.4-canary → 0.50.0

package/docs/concepts/providers-and-runtimes.md

@@ -1,121 +0,0 @@
----
-title: Models & runtimes
-description: How gateway model slugs map to managed runtime execution.
-icon: Network
----
-
-aex routes every model through the managed Vercel AI Gateway. You name a model
-by its gateway `creator/model` **slug** and the platform's single managed key
-handles the upstream provider relationship — there is no `provider` selector and
-you never supply a provider API key.
-
-```ts
-model: "anthropic/claude-haiku-4-5"   // creator/model gateway slug
-```
-
-The slug is validated at the boundary by `parseModelSlug` (shape only). The
-catalog is OPEN: a well-formed slug the gateway serves just works with zero code
-changes; a slug this SDK does not recognize is still accepted and arbitrated by
-the gateway at submit time.
-
-All submissions run on a managed runtime. The optional `runtime` object has two
-independent selectors:
-
-- `runtime.kind` selects the execution backend: `RuntimeKinds.SPOT_CONTAINER`
-  (the default, `"spot_container"`), `RuntimeKinds.CONTAINER`
-  (`"container"`), or `RuntimeKinds.LAMBDA` (`"lambda"`).
-- `runtime.size` selects a managed machine-size preset; use `Sizes.*` in
-  TypeScript.
-
-Omit either field to use its default (`spot_container` for `kind` and
-`0.25cpu-1gb` for `size`). The CLI equivalents are `--runtime <kind>` and
-`--runtime-size <size>`.
-
-An explicit runtime request is never silently replaced with another runtime. If
-the requested runtime cannot do what the submission asks — a capability it does
-not support, a session deadline past its lifetime, a workspace larger than it
-provisions — the submission fails before execution rather than running in a
-degraded mode.
-
-## What each runtime can actually do
-
-Runtime choice is not free of behavioral consequences, and this SDK does not
-claim otherwise. Every runtime publishes a **profile**: the capabilities it
-performs, the limits it enforces, and the delivery semantics it guarantees. Read
-it at runtime with `aex.whoami().runtimeCapabilities.profilesByRuntimeKind`
-(CLI: `aex whoami --json`); the capability hash identifies the exact document
-the service used.
-
-Four differences are real, permanent, and cannot be equalized:
-
-| Difference | Where it is published | What it means for you |
-| --- | --- | --- |
-| **Idle billing and cold start** | `profile.delivery.idleBilling`, `profile.delivery.coldStartClass` | This is the product reason the runtimes exist. `lambda` bills **zero** while a session is parked or waiting and cold-starts in seconds; the container runtimes bill **wall clock** for the whole session and cold-start in tens of seconds. |
-| **`spot_container` runs side-effecting tools at least once** | `profile.delivery.toolExecution` | A Spot reclaim replays the interrupted step, so a tool with an external side effect may run more than once. `container` and `lambda` are `exactly-once`. If your tools are not idempotent, choose `container`. |
-| **MicroVM disk and lifetime** | `profile.limits.maxWorkspaceBytes`, `profile.limits.maxSessionMs` | `lambda` runs in a MicroVM with a 32 GiB disk and an 8-hour hard lifetime. These are host limits, not policy, and admission rejects a submission that exceeds them. |
-| **One atomic effect is capped** | `profile.limits.maxSingleEffectMs` | A single LLM call or tool call may run for at most 14 minutes on **every** runtime. On `lambda` the live budget can be shorter still, bounded by the remaining invocation time. An overrun fails that tool call with a typed error; it never silently drops the turn. |
-
-Capabilities are declared per runtime and are either `supported` or
-`unsupported` — there is no partial state. A capability the selected runtime
-does not support is refused at admission, so a runtime can never advertise a
-tool it cannot execute.
-
-> **Availability today.** `lambda` is not generally available. It can finish an
-> LLM turn but cannot yet execute a tool call, and its profile says so:
-> `toolExecution`, `workspaceCheckpoint`, `workspaceFileCapture`,
-> `streamingDeltas`, `approvalGate`, `postHook`, `mcpTools`, `scheduledWait`,
-> `customerSecrets`, and `containedEgress` are all `unsupported`. The default is
-> `spot_container` because it is the cheapest runtime that executes every tool.
-> Check `availableRuntimeKinds` before naming a runtime: during a staged rollout
-> a runtime may be part of the SDK vocabulary without appearing in your
-> workspace's available set.
-
-Subagents behave identically on every runtime: a subagent shares its parent's
-workspace and sees the files the parent just wrote.
-
-## Selection
-
-### TypeScript
-
-```ts
-import { RuntimeKinds, Sizes } from "@aexhq/sdk";
-
-const capabilities = (await aex.whoami()).runtimeCapabilities;
-if (!capabilities?.availableRuntimeKinds.includes(RuntimeKinds.CONTAINER)) {
-  throw new Error("Container runtime is not available for this workspace");
-}
-
-// Tools with external side effects should not run on interruption-tolerant
-// capacity: check the published delivery semantics rather than assuming.
-const profile = capabilities.profilesByRuntimeKind[RuntimeKinds.CONTAINER];
-if (profile.delivery.toolExecution !== "exactly-once") {
-  throw new Error("this workload needs exactly-once tool execution");
-}
-
-await aex.start({
-  model: "openai/gpt-4.1",
-  message: "Summarise the attached files.",
-  runtime: {
-    kind: RuntimeKinds.CONTAINER,
-    size: Sizes.CPU_0_25_1GB
-  }
-});
-```
-
-### CLI
-
-```bash
-aex start \
-  --api-key "$AEX_API_KEY" \
-  --model openai/gpt-4.1 \
-  --runtime container \
-  --runtime-size 0.25cpu-1gb \
-  --prompt "Summarise the attached files." \
-  --follow
-```
-
-Events, files, streaming/replay, controls, cleanup, and downloads use the same
-SDK and CLI **surface** for every runtime and model — the same calls, the same
-shapes, the same stable error codes. What a given runtime will actually perform
-behind that surface is the profile above. For the model-access contract, see the
-generated [model access reference](../provider-runtime-capabilities.md).

package/docs/concepts/sessions.md

@@ -1,51 +0,0 @@
----
-title: Sessions
-description: Resumable threads, explicit runs, and committed checkpoints.
-icon: Play
----
-
-A session is a resumable thread. Its `status` describes whether that thread can
-progress, not whether the previous run succeeded. Typical resumable states are
-`running`, `idle`, `suspended`, `awaiting_approval`, and recoverable `error`.
-The previous run verdict is available as `lastRun.outcome` and on its terminal
-RUN event.
-
-```ts
-const session = await aex.sessions.create({ model });
-
-const run = session.messages.send("Write the report and save it as a file.");
-for await (const event of run) console.log(event.type);
-const result = await run.finished();
-
-console.log(result.status); // succeeded | failed | timed_out | cancelled | interrupted
-console.log(result.session.status); // usually idle after a successful run
-```
-
-`finished()` resolves only after `RUN_FINISHED` or `RUN_ERROR`. A
-`RUN_FINISHED` is the consistency barrier: session state, usage, checkpoint,
-and checkpoint-backed files are committed before it is emitted. This release does not
-expose a separate pre-checkpoint "brain idle" wait. The committed session
-projection must identify that exact run in `lastRun`; an idle projection with a
-missing or older `lastRun` is treated as inconsistent and `finished()` fails.
-
-The three common namespaces are stable properties:
-
-```ts
-const messages = await session.messages.list();
-const snapshot = await session.files.list();
-
-for await (const event of session.events.iterate()) {
-  console.log(event.type);
-}
-
-console.log(snapshot.revision.checkpointId);
-console.log(snapshot.files);
-```
-
-Reopen a durable session with `aex.sessions.open(id)`. Use a stable
-`idempotencyKey` for create and message mutations that your application may
-repeat. Reads and explicitly idempotent mutations receive bounded transport
-retries; a user run is never replayed as a whole by the SDK.
-
-`aex.start(...)` is the one-shot create, send, and finish convenience. It
-returns the same five-value run outcome and committed file snapshot.

package/docs/concepts/subagents.md

@@ -1,35 +0,0 @@
----
-title: Subagents
-description: Delegate bounded work to child sessions and inspect their lineage.
-icon: GitFork
----
-
-The builtin `subagent` capability lets an agent delegate work to child sessions.
-Enable it with the default builtin set or include it explicitly in
-`builtinTools`. Use `builtinTools: "none"` to disable agent-driven delegation.
-
-Children are durable session records with their own events and checkpointed
-files. Discover them from the parent handle:
-
-```ts
-const children = await session.children();
-
-for (const child of children) {
-  console.log(child.id, child.parentSessionId, child.depth, child.status);
-  const events = await child.events.list();
-  const snapshot = await child.files.list();
-  const descendants = await child.children();
-  console.log(child.ref.lastRun?.outcome, events.length, snapshot.files.length, descendants.length);
-}
-```
-
-Child `status` is a session lifecycle state. Inspect `lastRun.outcome` or the
-child's terminal RUN event for its run verdict. Child handles are read-only:
-they expose events, checkpointed files, and recursive lineage, but not top-level
-session controls such as send, cancel, suspend, resume, or delete.
-
-Provider credentials are inherited through the hosted runtime's vaulted
-channel; they are not copied into public child submissions or event payloads.
-Depth, breadth, and spend limits are enforced server-side. Use
-`overrides.maxSpendUsd` and a deliberate builtin selection to bound a parent
-workflow.

package/docs/credentials.md

@@ -1,116 +0,0 @@
----
-title: Credentials
----
-
-# Credentials
-
-aex uses explicit, per-session credentials:
-
-- `AEX_API_KEY` authenticates the SDK or CLI to aex.
-- `McpServer.remote(..., { headers })` carries MCP auth when a remote MCP server needs it.
-- `environment.secrets` carries runtime secrets for your own code.
-
-Model access needs **no** provider API key: aex routes every model through the
-managed Vercel AI Gateway with its own key. You name a model by its
-`creator/model` gateway slug and nothing else.
-
-Secrets never belong in reusable session config, files, prompts, or examples.
-
-## The client credential
-
-Pass your aex API key directly to the constructor — `new Aex(apiKey)` — or as
-the `apiKey` option:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);          // preferred shorthand
-// equivalently:
-// const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-```
-
-See [Authentication](authentication.md) for how keys are scoped, rotated, and
-issued during the beta.
-
-## Choosing a model
-
-Name the model by its Vercel AI Gateway `creator/model` slug. There is no
-`provider` field and no provider key — the platform's managed gateway key routes
-the call.
-
-```ts
-const result = await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Write a short report and save it as a file.",
-});
-```
-
-## Runtime secrets
-
-Use `environment.secrets` for credentials your code needs at runtime. The value
-can be ephemeral with `Secret.value(...)` or a workspace secret reference with
-`Secret.ref(...)`.
-
-```ts
-import { Aex, Secret } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Call https://api.example.com/v1/status with INTERNAL_API_TOKEN and summarize it.",
-  environment: {
-    secrets: {
-      INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!)
-    },
-    networking: {
-      mode: "limited",
-      allowedHosts: ["api.example.com"]
-    }
-  },
-});
-```
-
-Inside the session, use normal HTTP code for the service:
-
-```bash
-curl -sS \
-  -H "Authorization: Bearer $INTERNAL_API_TOKEN" \
-  https://api.example.com/v1/status
-```
-
-## Workspace secrets
-
-Store reusable values once, then reference them by name:
-
-```ts
-await aex.workspace.secrets.set({
-  name: "internal-api-token",
-  value: process.env.INTERNAL_API_TOKEN!
-});
-
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Use INTERNAL_API_TOKEN for the status request.",
-  environment: {
-    secrets: {
-      INTERNAL_API_TOKEN: Secret.ref("internal-api-token")
-    }
-  },
-});
-```
-
-Secret reads return metadata only; they never return the stored value.
-
-## Networking
-
-Networking is open by default within the platform's managed egress ceiling. Use
-`environment.networking.mode: "limited"` with `allowedHosts` when you want a
-session's own code to reach only named hosts. See [Networking](networking.md) for
-the two-layer enforcement model.
-
-## Explicit call-site rule
-
-There is no `defaultSecrets` and no client-held secret state. Each
-`aex.sessions.create(...)` or `aex.start(...)` call should show the MCP auth and
-runtime secrets needed for that call.

package/docs/defaults.md

@@ -1,51 +0,0 @@
----
-title: Defaults
----
-
-# Defaults
-
-These are the public values aex applies when you omit the corresponding option.
-Runtime-size presets are defined in public
-[`runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts).
-For hard ceilings and adjustable limits, see
-[Limits & quotas](limits-and-quotas.md).
-
-## Session
-
-| Option | Default | How to override |
-| --- | --- | --- |
-| `timeout` | 8 hours | `overrides.timeout` (minimum 1 minute, maximum 8 hours) |
-| `runtime` | `0.25cpu-1gb` (0.25 vCPU, 1 GB) | `runtime` or `Sizes.*` |
-| `overrides.maxSpendUsd` | No per-session spend cap | A positive USD amount |
-| `overrides.maxTurns` | 20 iterations | A positive integer, up to 200 |
-
-## Tools and MCP
-
-| Option | Default | How to override |
-| --- | --- | --- |
-| Per-call exec timeout | 30 minutes | Tool call `timeoutMs` |
-| `web_fetch` returned body | 500 KB (UTF-8) | Tool argument `max_bytes` |
-| MCP connect timeout | 30 seconds | MCP server `connectTimeoutMs` |
-| MCP `tools/call` timeout | 30 minutes | MCP server `callTimeoutMs` |
-
-## Links and tickets
-
-| Option | Default | How to override |
-| --- | --- | --- |
-| Signed URL TTL | 300 seconds at the API layer; `session.files.link(...)` defaults to `"1h"` | `expiresSeconds` or the SDK's `expiresIn` |
-| Event-stream ticket TTL | 60 seconds | `ttlMs` |
-
-## Subagents
-
-Subagent breadth and depth use managed budgets rather than fixed public numeric
-entitlements. The service supports high recursive depth and large fan-out;
-contact support before relying on unusually large workloads.
-
-## Workspace
-
-Workspace storage is bounded by your plan's monthly storage grant, not by a
-fixed per-workspace number. The Free plan includes 5 GB; paid plans have no
-per-dimension storage quota and bill usage beyond the included allowance once
-you add a payment method and enable overage. Admission, concurrency, and other
-adjustable workspace limits are returned by `aex.whoami()` (CLI: `aex whoami`);
-contact support when the effective value does not fit your workload.

package/docs/errors.md

@@ -1,258 +0,0 @@
----
-title: Errors
----
-
-# Errors
-
-Every API error is a JSON body with a machine-readable `error` code; most also
-carry a human `message` and the self-describing fields named below.
-
-## Typed errors in the SDK
-
-The SDK maps every non-2xx response through one factory to a typed exception. All
-inherit `AexApiError`, which carries the HTTP `status`, the parsed `body`
-(secret-shape-scanned client-side, in your process, when the error is
-constructed), the server's stable `apiCode` (a machine-branchable identity distinct
-from the human `message`), and a `requestId` for support correlation. The
-factory dispatches to a subclass by code/status:
-
-| Class | Fires for | Extra fields |
-| --- | --- | --- |
-| `AexAuthError` | `401` / `403` (unauthorized, forbidden, insufficient_scope, token_invalid/revoked/expired, malformed_token) | `requiredScope` (on `insufficient_scope`) |
-| `AexIdempotencyConflictError` | `409` `idempotency_conflict` | — |
-| `AexNotFoundError` | `404` `not_found` | — |
-| `AexRateLimitError` | `429` (rate_limited, workspace_concurrency_exceeded, workspace_submit_rate_exceeded) | `retryAfterMs` (when advertised) |
-| `AexApiError` (base) | every other stable code (session_busy, checkpoint_not_available, session_not_terminal, session_terminal, event_archive_too_large, event_archive_deadline_exceeded, workspace_inactive, insufficient_credits, account_blocked, workspace_spend_cap_exceeded, upstream_error, internal_error, …) | — |
-
-Branch with the exported guards instead of parsing bodies or matching status
-codes: `isAuthError`, `isInsufficientScope`, `isIdempotencyConflict`,
-`isNotFound`, and `isRateLimited`.
-
-```ts
-import { isInsufficientScope, isIdempotencyConflict } from "@aexhq/sdk";
-
-try {
-  await aex.start(config);
-} catch (err) {
-  if (isInsufficientScope(err)) {
-    // err.requiredScope names the missing scope; mint a key that includes it.
-  } else if (isIdempotencyConflict(err)) {
-    // same key, different body — use a fresh key or resend the byte-identical body.
-  }
-}
-```
-
-The **stable** `apiCode` set the SDK types and dispatches on is: `unauthorized`,
-`forbidden`, `insufficient_scope`, `token_invalid`, `token_revoked`,
-`token_expired`, `malformed_token`, `not_found`, `idempotency_conflict`,
-`session_busy`, `checkpoint_not_available`, `session_not_terminal`, `session_terminal`,
-`event_archive_too_large`, `event_archive_deadline_exceeded`, `unknown_workspace`,
-`workspace_inactive`, `workspace_concurrency_exceeded`, `workspace_submit_rate_exceeded`,
-`workspace_spend_cap_exceeded`, `insufficient_credits`, `account_blocked`,
-`rate_limited`, `upstream_error`, `internal_error`. A code outside this set (e.g. a validation
-`error` a route reports) still surfaces as an `AexApiError` with the `status` and
-`body.error` preserved; `apiCode` is then `undefined`.
-
-Transport failures with no HTTP response (DNS, connection refused, TLS reset)
-surface as `AexNetworkError`; client-side config validation surfaces as
-`SessionConfigValidationError` (`err.code === "SESSION_CONFIG_INVALID"`) before any
-request is sent. Its stable machine-readable payload is exactly
-`err.details = { field }`, where `field` is the rejected public option path such
-as `overrides.timeout`. Branch on `details.field`; the human `message` may change
-and never includes the rejected value.
-
-Strict public contract parsers throw their existing error classes and messages,
-with non-enumerable metadata that can be narrowed through
-`isContractParseError(err)`. The guard preserves the original error object and
-specialized class; `err.code === CONTRACT_PARSE_ERROR` and `err.parser` identify
-the nearest strict parser that rejected the input.
-
-Parser names describe behavior: `parse*` is strict and throws for malformed
-present input, while `tryParse*` is a non-throwing recognizer that returns
-`null` or `undefined`. The older `parseApiKey`, `parseBundleManifest`, and
-internal retry-header names, plus `validateSkillBundleEntry` and
-`validateSkillBundleManifest`, remain callable compatibility wrappers. New code
-should use `tryParseApiKey`, `tryParseBundleManifest`,
-`parseSkillBundleEntry`, and `parseSkillBundleManifest`.
-
-## 401 — authentication
-
-| Code | Meaning |
-| --- | --- |
-| `unauthorized` | Missing or empty bearer token. |
-| `token_invalid` | Bearer token is structurally valid but does not match a live credential, has a bad signature, or belongs to an inactive workspace. |
-| `token_revoked` | Bearer token matched a revoked credential. |
-| `token_expired` | Short-lived internal writer token is past its expiry. |
-
-Check the token value and that it has not been deleted or revoked. `aex whoami`
-is the cheapest way to validate a credential. See
-[Authentication](authentication.md).
-
-## 403 — authorization
-
-| Code | Meaning |
-| --- | --- |
-| `insufficient_scope` | The token is valid but lacks the route's required scope. The body's `requiredScope` field names the missing scope. |
-| `unknown_workspace` | The token does not route to a known workspace. |
-| `forbidden` | The authenticated workspace does not own the addressed resource. |
-
-```json
-{ "error": "insufficient_scope", "requiredScope": "sessions:write" }
-```
-
-## 400 — validation
-
-| Code | Meaning |
-| --- | --- |
-| `bad_request` | Missing or unparseable request body. |
-| `invalid_submission` | The submission failed shape validation; `message` names the offending field. |
-| `invalid_model` | `model` is not a `creator/model` gateway slug (for example `anthropic/claude-haiku-4-5`). |
-| `malformed_token` | The bearer value is not a structurally valid aex token. |
-
-400s are permanent for that request — fix the input rather than retrying.
-The SDK's client-side validation (`SessionConfigValidationError`) catches most of
-these before the request is sent.
-
-## 402 — payment required
-
-Three distinct submit gates return 402; every body is self-describing.
-
-**`insufficient_credits`** — the free model-usage allowance for this UTC month
-AND the prepaid balance are both empty. A submit is admitted while either one is
-positive, so this fires only when both are gone.
-
-```json
-{
-  "error": "insufficient_credits",
-  "message": "Free model-usage allowance exhausted ($0.00 of $2.00 left this month) and the prepaid balance is $0.00. Add a payment method and buy credits to continue running.",
-  "balanceUsd": 0,
-  "balanceGraceFloorUsd": 0,
-  "paymentMethodStatus": "none",
-  "admissionState": "free",
-  "exhaustedDimension": "llm_token_usd",
-  "allowanceRemaining": { "llm_token_usd": 0, "egress_gb": 4.2, "web_search_calls": 36 }
-}
-```
-
-`allowanceRemaining` covers **every** dimension, not just the exhausted one, so
-a client can render the whole allowance panel from the error alone.
-`admissionState` (`free` / `carded_manual` / `carded_auto`) is what the remedy in
-`message` follows: add a card, top up, or find out why the automatic recharge did
-not land.
-
-**`account_blocked`** — the organization is blocked (for example a disputed
-payment under review). This is a **separate code on purpose**: buying credit does
-not lift a block, so a client must not offer a top-up here.
-
-```json
-{
-  "error": "account_blocked",
-  "message": "This organization cannot start new work because a disputed payment is under review (blocked 2026-07-24). Adding credit will not restore access — contact support to resolve it.",
-  "reason": "dispute",
-  "blockedAt": "2026-07-24T09:00:00.000Z",
-  "admissionState": "carded_manual"
-}
-```
-
-**`workspace_spend_cap_exceeded`** — the workspace's monthly spend cap is
-reached. The cap resets at the start of the next UTC month; contact support to
-raise it.
-
-```json
-{
-  "error": "workspace_spend_cap_exceeded",
-  "message": "Monthly spend cap of $250 reached ($251.13 accrued this month). The cap resets at the start of the next UTC month; contact support to raise it.",
-  "capUsd": 250,
-  "accruedUsd": 251.13
-}
-```
-
-## 429 — rate limits
-
-**`workspace_concurrency_exceeded`** — admitting one more live run would exceed
-the workspace's concurrent-run cap. Wait for a session to finish, or contact
-support to raise the cap.
-
-```json
-{
-  "error": "workspace_concurrency_exceeded",
-  "message": "Workspace concurrency limit reached: 50 live sessions at the cap of 50. Wait for a session to finish, or contact support to raise your workspace limit.",
-  "cap": 50,
-  "observed": 50
-}
-```
-
-**`workspace_submit_rate_exceeded`** — too many submits in the current
-one-minute window. Retry shortly.
-
-```json
-{
-  "error": "workspace_submit_rate_exceeded",
-  "message": "Submit rate limit of 120/minute exceeded. Retry shortly, or contact support to raise your workspace limit.",
-  "perMin": 120,
-  "observed": 121
-}
-```
-
-The `limit`-naming fields (`cap`/`perMin`) and the `observed` window value make
-each deny self-describing, so a client can back off proportionally. To
-anticipate both 429s and both 402s *before* submitting, read the effective caps
-from `aex.whoami().limits` — the values come from the same resolution code the
-gates enforce. See [Limits & quotas](limits-and-quotas.md).
-
-## 404 — not found
-
-`not_found`: the id does not exist **or** belongs to another workspace (aex
-does not distinguish the two). The SDK raises `AexNotFoundError` (guard:
-`isNotFound(err)`).
-
-## 409 — conflicts and inactive workspaces
-
-| Code | Meaning |
-| --- | --- |
-| `idempotency_conflict` | The `idempotencyKey` was already used with a different request body. The SDK raises `AexIdempotencyConflictError` (guard: `isIdempotencyConflict(err)`). |
-| `session_busy` | The session is handling another turn or lifecycle transition. Wait for its current operation to finish. |
-| `checkpoint_not_available` | No committed checkpoint exists yet for a checkpoint-backed read such as `session.files.list()`. Wait for the current run to finish. This remains a base `AexApiError`, not an idempotency conflict. |
-| `session_not_terminal` | The requested operation requires a terminal session state. |
-| `session_terminal` | The session has ended and cannot perform the requested action. |
-| `workspace_inactive` | A workspace deletion fence won the admission race, so the workspace no longer accepts new session work. The body carries `workspaceStatus` (normally `deleting`). Use an active workspace. |
-
-For `idempotency_conflict`, use a fresh idempotency key for a genuinely new request, or resubmit
-the byte-identical body to replay the original result (a matching retry returns
-the existing session rather than conflicting). Note that the SDK validates the
-key client-side first: an empty or whitespace-only `idempotencyKey` throws
-`SessionConfigValidationError` before the request is sent, as does a key longer
-than 255 characters. Never pass `""`.
-
-`workspace_inactive` is not an idempotency conflict and is not transient for
-that workspace. It remains a base `AexApiError`; branch on
-`err.apiCode === "workspace_inactive"` and inspect `err.body.workspaceStatus`
-when the current lifecycle state matters.
-
-## 413/503 — synchronous event archive limits
-
-| Code | Meaning |
-| --- | --- |
-| `event_archive_too_large` (413) | The history exceeds the synchronous archive's source, candidate, or estimated-output limit. |
-| `event_archive_deadline_exceeded` (503) | The synchronous archive could not finish inside its server request budget. |
-
-Both are stable base `AexApiError` codes with `retryable: false`. The SDK does
-not retry `session.events.archiveLink()` automatically. Traverse the history
-with `session.events.iterate()` instead of repeating the bulk export.
-
-## 5xx — server errors
-
-| Code | Meaning |
-| --- | --- |
-| `internal_error` (500) | Unexpected server fault. Retry with backoff; report persistent cases. |
-| `db_resuming` (503) | The database tier is resuming from idle. Transient — retry. |
-
-The SDK retries transient failures automatically: HTTP `429`, `5xx`, `529`, and
-network errors get bounded exponential backoff with full jitter, honoring any
-`Retry-After` header. Tune or disable this with the client `retry` option; use
-`isRateLimited(err)` / `AexRateLimitError` to handle persistent throttling
-without parsing raw bodies. Automatic retries are limited to reads and other
-idempotent HTTP methods, or mutations carrying a stable `Idempotency-Key`.
-Session create/send requests always carry one stable key across transport
-attempts, so a retried request cannot create a second billable run. The SDK
-never retries an entire user scenario or a failed application run.