@aexhq/sdk 0.40.6 → 0.40.8

package/docs/retries.md

@@ -1,129 +1,129 @@
----
-title: Retries and throttling
----
-
-# Retries and throttling
-
-The SDK ships with built-in transport resilience. Every request it makes to the
-aex API is automatically retried on **transient** failures with bounded
-exponential backoff and jitter, honoring the server's `Retry-After` header. You
-get this by default — no wrapper code — and it is safe to leave on because the
-billable submits carry a stable idempotency key, so a retry never creates a
-duplicate run.
-
-## What gets retried
-
-Retried automatically:
-
-- HTTP `429` (rate limited)
-- HTTP `500`, `502`, `503`, `504` (server hiccups)
-- HTTP `529` (upstream provider overloaded)
-- Network errors (connection reset, DNS failure, timeout)
-
-Never retried — these fail fast so you see the real problem immediately:
-
-- `400` / `422` (bad request), `401` / `403` (auth), `404` (not found),
-  `409` (conflict), and every other non-transient `4xx`.
-- A request you aborted yourself (via an `AbortSignal`).
-
-## Tuning or disabling
-
-Pass a `retry` option when you construct the client:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex({
-  apiKey: process.env.AEX_API_KEY!,
-  retry: {
-    maxAttempts: 4,        // total tries incl. the first (default 4)
-    initialDelayMs: 500,   // base backoff, doubles per retry (default 500)
-    maxDelayMs: 20_000,    // cap on any single wait (default 20s)
-    maxElapsedMs: 120_000  // overall wall-clock budget (default 2m)
-  }
-});
-```
-
-Turn it off entirely with `retry: false`, or make a single attempt with
-`retry: { maxAttempts: 1 }`.
-
-## Idempotent by construction
-
-Retries — whether the built-in transport retry or your own re-invocation of
-`run(...)` — never double-bill. The one-shot `run(...)` and `sessions.run(...)`
-derive the turn's idempotency key from the session-create key, so re-invoking
-either with the same `idempotencyKey` de-duplicates **both** the session create
-and the billable turn server-side:
-
-```ts
-// A retried call with the same idempotencyKey resolves to the same run,
-// not a second billable one.
-const result = await aex.run({
-  model: "claude-haiku-4-5",
-  message: "Write a short report and save it as a file.",
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-  idempotencyKey: "report-2026-07-01"
-});
-```
-
-## Replaying a throttled turn
-
-When a turn on a live session is interrupted by a throttle, replay the last
-message with `session.replayLast()`. It reuses the previous message's idempotency
-key by default, so if the original turn actually landed it de-duplicates instead
-of billing twice:
-
-```ts
-const session = await aex.openSession({
-  model: "claude-haiku-4-5",
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-try {
-  await session.send("Summarize the attached dataset.").done();
-} catch (err) {
-  const { isRateLimited } = await import("@aexhq/sdk");
-  if (isRateLimited(err)) {
-    // Wait out the throttle, then replay the same message.
-    await new Promise((r) => setTimeout(r, err.retryAfterMs ?? 2_000));
-    await session.replayLast().done();
-  } else {
-    throw err;
-  }
-}
-```
-
-Pass a fresh key (`session.replayLast({ idempotencyKey: "..." })`) when you
-deliberately want a brand-new turn instead of a de-duplicated replay.
-
-## The throttle error
-
-When retries are exhausted on a rate-limit / overloaded status, the SDK throws an
-`AexRateLimitError`. It extends `AexApiError`, so existing `catch` sites keep
-working, and it carries structured, non-leaky detail:
-
-```ts
-import { isRateLimited } from "@aexhq/sdk";
-
-try {
-  await aex.run({ /* … */ });
-} catch (err) {
-  if (isRateLimited(err)) {
-    err.status;         // 429 | 503 | 529
-    err.attempts;       // how many tries were made
-    err.retryAfterMs;   // suggested wait, when the server supplied one
-    err.source;         // "api" (aex plane) or "provider" (upstream model)
-    err.providerFault;  // upstream fault detail, when the model provider throttled
-  }
-}
-```
-
-The `message` is a fixed summary (e.g. `aex API rate limit reached (HTTP 429)
-after 4 attempts; retry after ~2s`) — it never echoes the raw response body,
-which stays available, redacted, on `err.body`.
-
-When the throttle originated at the upstream model provider (rather than the aex
-API plane), `err.source` is `"provider"` and `err.providerFault` describes it:
-its `kind` (`rate_limit` / `overloaded` / `quota_exceeded` / `provider_error`),
-the upstream `status`, and a suggested `retryAfterMs`. Use `parseProviderFault`
-to read the same shape off a raw fault value yourself.
+---
+title: Retries and throttling
+---
+
+# Retries and throttling
+
+The SDK ships with built-in transport resilience. Every request it makes to the
+aex API is automatically retried on **transient** failures with bounded
+exponential backoff and jitter, honoring the server's `Retry-After` header. You
+get this by default — no wrapper code — and it is safe to leave on because the
+billable submits carry a stable idempotency key, so a retry never creates a
+duplicate run.
+
+## What gets retried
+
+Retried automatically:
+
+- HTTP `429` (rate limited)
+- HTTP `500`, `502`, `503`, `504` (server hiccups)
+- HTTP `529` (upstream provider overloaded)
+- Network errors (connection reset, DNS failure, timeout)
+
+Never retried — these fail fast so you see the real problem immediately:
+
+- `400` / `422` (bad request), `401` / `403` (auth), `404` (not found),
+  `409` (conflict), and every other non-transient `4xx`.
+- A request you aborted yourself (via an `AbortSignal`).
+
+## Tuning or disabling
+
+Pass a `retry` option when you construct the client:
+
+```ts
+import { Aex } from "@aexhq/sdk";
+
+const aex = new Aex({
+  apiKey: process.env.AEX_API_KEY!,
+  retry: {
+    maxAttempts: 4,        // total tries incl. the first (default 4)
+    initialDelayMs: 500,   // base backoff, doubles per retry (default 500)
+    maxDelayMs: 20_000,    // cap on any single wait (default 20s)
+    maxElapsedMs: 120_000  // overall wall-clock budget (default 2m)
+  }
+});
+```
+
+Turn it off entirely with `retry: false`, or make a single attempt with
+`retry: { maxAttempts: 1 }`.
+
+## Idempotent by construction
+
+Retries — whether the built-in transport retry or your own re-invocation of
+`run(...)` — never double-bill. The one-shot `run(...)` and `sessions.run(...)`
+derive the turn's idempotency key from the session-create key, so re-invoking
+either with the same `idempotencyKey` de-duplicates **both** the session create
+and the billable turn server-side:
+
+```ts
+// A retried call with the same idempotencyKey resolves to the same run,
+// not a second billable one.
+const result = await aex.run({
+  model: "claude-haiku-4-5",
+  message: "Write a short report and save it as a file.",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
+  idempotencyKey: "report-2026-07-01"
+});
+```
+
+## Replaying a throttled turn
+
+When a turn on a live session is interrupted by a throttle, replay the last
+message with `session.replayLast()`. It reuses the previous message's idempotency
+key by default, so if the original turn actually landed it de-duplicates instead
+of billing twice:
+
+```ts
+const session = await aex.openSession({
+  model: "claude-haiku-4-5",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+try {
+  await session.send("Summarize the attached dataset.").done();
+} catch (err) {
+  const { isRateLimited } = await import("@aexhq/sdk");
+  if (isRateLimited(err)) {
+    // Wait out the throttle, then replay the same message.
+    await new Promise((r) => setTimeout(r, err.retryAfterMs ?? 2_000));
+    await session.replayLast().done();
+  } else {
+    throw err;
+  }
+}
+```
+
+Pass a fresh key (`session.replayLast({ idempotencyKey: "..." })`) when you
+deliberately want a brand-new turn instead of a de-duplicated replay.
+
+## The throttle error
+
+When retries are exhausted on a rate-limit / overloaded status, the SDK throws an
+`AexRateLimitError`. It extends `AexApiError`, so existing `catch` sites keep
+working, and it carries structured, non-leaky detail:
+
+```ts
+import { isRateLimited } from "@aexhq/sdk";
+
+try {
+  await aex.run({ /* … */ });
+} catch (err) {
+  if (isRateLimited(err)) {
+    err.status;         // 429 | 503 | 529
+    err.attempts;       // how many tries were made
+    err.retryAfterMs;   // suggested wait, when the server supplied one
+    err.source;         // "api" (aex plane) or "provider" (upstream model)
+    err.providerFault;  // upstream fault detail, when the model provider throttled
+  }
+}
+```
+
+The `message` is a fixed summary (e.g. `aex API rate limit reached (HTTP 429)
+after 4 attempts; retry after ~2s`) — it never echoes the raw response body,
+which stays available, redacted, on `err.body`.
+
+When the throttle originated at the upstream model provider (rather than the aex
+API plane), `err.source` is `"provider"` and `err.providerFault` describes it:
+its `kind` (`rate_limit` / `overloaded` / `quota_exceeded` / `provider_error`),
+the upstream `status`, and a suggested `retryAfterMs`. Use `parseProviderFault`
+to read the same shape off a raw fault value yourself.

package/docs/run-config.md

@@ -1,58 +1,58 @@
----
-title: Run configuration
----
-
-# Run configuration
-
-A run config is the credential-free subset of the session options (`openSession` / `run`) that you can keep in code or load from a JSON file. It is not a platform object, saved definition, DSL, trigger, or persistent agent profile. aex only stores the immutable session record created when the session lands.
-
-Allowed fields:
-
-- `model` - required.
-- `system` - optional system message.
-- `mcpServers` - array of `McpServerRef`; headers are split into the vaulted secrets channel server-side.
-- `environment` - `{ networking?, packages?, variables? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `variables` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts. (Run secrets go in `environment.secrets`, which carries live `Secret` instances and is not part of a shareable config.)
-- `runtime` - optional managed-runtime preset. Prefer `Sizes` in TypeScript.
-- `metadata` - non-secret structured metadata.
-- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd?, maxTurns? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap; `maxTurns` caps the agent's iteration count for the turn (a positive integer — omit to accept the platform default of 20, clamped to the ceiling). See [Limits & quotas](limits-and-quotas.md).
-
-`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `skills`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `skills` entries built with `Skill.fromDir(...)`, `Skill.fromUrl(...)`, or the other `Skill.from*` factories, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentRunId` option. The wire contract carries a per-run `limits` object (the exported `RunLimits` type: `maxConcurrentChildRuns`, `maxSubagentDepth`, `maxSpendUsd`, `maxTurns`), and the session surface exposes its spend and iteration dials via `overrides.maxSpendUsd` and `overrides.maxTurns`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
-
-Secrets never live in run config. Pass provider keys through the top-level
-`apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or
-the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`) in the CLI.
-See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md)
-for credential handling.
-
-## Reuse in code
-
-Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the parameters you pass.
-
-```ts
-import { Models } from "@aexhq/sdk";
-
-function summarise(topic: string) {
-  return {
-    model: Models.CLAUDE_HAIKU_4_5,
-    system: "You are a concise automation agent.",
-    message: `Write a short answer about ${topic}.`
-  };
-}
-
-await aex.run({
-  ...summarise("agent-first SDK design"),
-  apiKeys: { anthropic: apiKey }
-});
-```
-
-## CLI
-
-The `aex run` host subcommand accepts the same run config either as a JSON file:
-
-```bash
-aex run --config ./run.json \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY"
-```
-
-...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--runtime-size`, `--run-timeout`, `--metadata`). The two modes are mutually exclusive. Composition inputs attach with repeatable flags that map onto the SDK's `Skill`/`Tool`/`AgentsMd`/`File` factories: `--skill @bundle` (workspace skill), `--tool @tool.js` (custom tool module), `--agents-md @AGENTS.md`, and `--file @path` (mount a file into `/workspace`).
+---
+title: Run configuration
+---
+
+# Run configuration
+
+A run config is the credential-free subset of the session options (`openSession` / `run`) that you can keep in code or load from a JSON file. It is not a platform object, saved definition, DSL, trigger, or persistent agent profile. aex only stores the immutable session record created when the session lands.
+
+Allowed fields:
+
+- `model` - required.
+- `system` - optional system message.
+- `mcpServers` - array of `McpServerRef`; headers are split into the vaulted secrets channel server-side.
+- `environment` - `{ networking?, packages?, variables? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `variables` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts. (Run secrets go in `environment.secrets`, which carries live `Secret` instances and is not part of a shareable config.)
+- `runtime` - optional managed-runtime preset. Prefer `Sizes` in TypeScript.
+- `metadata` - non-secret structured metadata.
+- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd?, maxTurns? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap; `maxTurns` caps the agent's iteration count for the turn (a positive integer — omit to accept the platform default of 20, clamped to the ceiling). See [Limits & quotas](limits-and-quotas.md).
+
+`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `skills`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `skills` entries built with `Skill.fromDir(...)`, `Skill.fromUrl(...)`, or the other `Skill.from*` factories, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentRunId` option. The wire contract carries a per-run `limits` object (the exported `RunLimits` type: `maxConcurrentChildRuns`, `maxSubagentDepth`, `maxSpendUsd`, `maxTurns`), and the session surface exposes its spend and iteration dials via `overrides.maxSpendUsd` and `overrides.maxTurns`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
+
+Secrets never live in run config. Pass provider keys through the top-level
+`apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or
+the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`) in the CLI.
+See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md)
+for credential handling.
+
+## Reuse in code
+
+Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the parameters you pass.
+
+```ts
+import { Models } from "@aexhq/sdk";
+
+function summarise(topic: string) {
+  return {
+    model: Models.CLAUDE_HAIKU_4_5,
+    system: "You are a concise automation agent.",
+    message: `Write a short answer about ${topic}.`
+  };
+}
+
+await aex.run({
+  ...summarise("agent-first SDK design"),
+  apiKeys: { anthropic: apiKey }
+});
+```
+
+## CLI
+
+The `aex run` host subcommand accepts the same run config either as a JSON file:
+
+```bash
+aex run --config ./run.json \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--runtime-size`, `--run-timeout`, `--metadata`). The two modes are mutually exclusive. Composition inputs attach with repeatable flags that map onto the SDK's `Skill`/`Tool`/`AgentsMd`/`File` factories: `--skill @bundle` (workspace skill), `--tool @tool.js` (custom tool module), `--agents-md @AGENTS.md`, and `--file @path` (mount a file into `/workspace`).

package/docs/run-record.md

@@ -1,55 +1,55 @@
----
-title: Run record
----
-
-# Run record
-
-The run record is the durable product primitive for one session. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured outputs, and manifest entries for custody and cost telemetry.
-
-## Listing sessions
-
-`aex.sessions.list(query?)` enumerates the sessions in this workspace, most-recent first, one page at a time. The workspace is derived server-side from the API key, so this only ever returns your own sessions. It is the workspace-wide discovery entry point: combine it with `aex.sessions.outputs(id).list()` / `.read(...)` (see [Outputs](outputs.md)) to reach any session's deliverables.
-
-```ts
-let cursor: string | undefined;
-do {
-  const page = await aex.sessions.list({ status: "idle", limit: 25, cursor });
-  for (const session of page.sessions) {
-    console.log(session.id, session.status, session.createdAt, session.costUsd);
-  }
-  cursor = page.nextCursor;
-} while (cursor);
-```
-
-`query` fields are all optional: `status` (single session status, e.g. `"idle"`), `since` (ISO-8601 lower bound on `createdAt`), `limit` (defaults to 25, clamped to `[1, 100]`), and `cursor` (the opaque keyset cursor from a prior page's `nextCursor` — absent on the last page). Each page row is a public-safe `SessionSummary` (`id`, `status`, `createdAt`, `updatedAt`, and `costUsd` once settled); it deliberately omits the submission snapshot (model / system / env). Use `aex.sessions.get(id)` for status / timing / cost on one session, or `session.unit()` on a handle for the full self-contained record including the parsed submission.
-
-## Downloading a run record
-
-`session.download()` and `aex download <session-id>` return a zip with this layout:
-
-```text
-manifest.json
-metadata/run.json
-metadata/submission.json      # when a public-safe submission snapshot is returned by the read API
-metadata/cost.json            # when public cost telemetry is returned by the read API
-events/events.jsonl
-outputs/<captured deliverable files>
-```
-
-`manifest.json` is versioned as `RunRecordManifestV1`:
-
-| Field | Meaning |
-| --- | --- |
-| `schemaVersion` | `aex.run-record.manifest.v1`. |
-| `runRecordSchemaVersion` | `aex.run-record.v1`. |
-| `runId` | The run the archive was assembled for. |
-| `namespaces[]` | The documented top-level namespaces: `metadata`, `events`, `outputs`. |
-| `files[]` | Inventory of expected and present files with `namespace`, `path`, `role`, and `status`. |
-| `outputs[]` | Compatibility alias for present captured output artifacts. |
-| `errors[]` | Per-artifact byte fetch failures during archive assembly. |
-
-Current v1 downloads always include `metadata/run.json` and `events/events.jsonl`. `events/events.jsonl` contains typed event-channel records only; internal diagnostics and full internal streams are not mixed into that file.
-
-`metadata/submission.json` is present only when the run read shape includes a public-safe submission snapshot. `metadata/cost.json` is present only when the run read shape includes public `costTelemetry`; otherwise cost stays `pending`. `metadata/custody.json` remains `pending` until the custody manifest writer and public read surface land. `events/manifest.json` remains `unavailable` in this client-side slice because there is no public coordinator-manifest download route.
-
-The record boundary is public-safe. It must not contain provider API keys, runner bearers, workspace tokens, signed URLs, raw provider response bodies, object-store keys, Vault ids, raw query strings, secret-shaped values, or internal diagnostic files. Credentials are supplied per run and vaulted separately for the run lifetime.
+---
+title: Run record
+---
+
+# Run record
+
+The run record is the durable product primitive for one session. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured outputs, and manifest entries for custody and cost telemetry.
+
+## Listing sessions
+
+`aex.sessions.list(query?)` enumerates the sessions in this workspace, most-recent first, one page at a time. The workspace is derived server-side from the API key, so this only ever returns your own sessions. It is the workspace-wide discovery entry point: combine it with `aex.sessions.outputs(id).list()` / `.read(...)` (see [Outputs](outputs.md)) to reach any session's deliverables.
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await aex.sessions.list({ status: "idle", limit: 25, cursor });
+  for (const session of page.sessions) {
+    console.log(session.id, session.status, session.createdAt, session.costUsd);
+  }
+  cursor = page.nextCursor;
+} while (cursor);
+```
+
+`query` fields are all optional: `status` (single session status, e.g. `"idle"`), `since` (ISO-8601 lower bound on `createdAt`), `limit` (defaults to 25, clamped to `[1, 100]`), and `cursor` (the opaque keyset cursor from a prior page's `nextCursor` — absent on the last page). Each page row is a public-safe `SessionSummary` (`id`, `status`, `createdAt`, `updatedAt`, and `costUsd` once settled); it deliberately omits the submission snapshot (model / system / env). Use `aex.sessions.get(id)` for status / timing / cost on one session, or `session.unit()` on a handle for the full self-contained record including the parsed submission.
+
+## Downloading a run record
+
+`session.download()` and `aex download <session-id>` return a zip with this layout:
+
+```text
+manifest.json
+metadata/run.json
+metadata/submission.json      # when a public-safe submission snapshot is returned by the read API
+metadata/cost.json            # when public cost telemetry is returned by the read API
+events/events.jsonl
+outputs/<captured deliverable files>
+```
+
+`manifest.json` is versioned as `RunRecordManifestV1`:
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` | `aex.run-record.manifest.v1`. |
+| `runRecordSchemaVersion` | `aex.run-record.v1`. |
+| `runId` | The run the archive was assembled for. |
+| `namespaces[]` | The documented top-level namespaces: `metadata`, `events`, `outputs`. |
+| `files[]` | Inventory of expected and present files with `namespace`, `path`, `role`, and `status`. |
+| `outputs[]` | Compatibility alias for present captured output artifacts. |
+| `errors[]` | Per-artifact byte fetch failures during archive assembly. |
+
+Current v1 downloads always include `metadata/run.json` and `events/events.jsonl`. `events/events.jsonl` contains typed event-channel records only; internal diagnostics and full internal streams are not mixed into that file.
+
+`metadata/submission.json` is present only when the run read shape includes a public-safe submission snapshot. `metadata/cost.json` is present only when the run read shape includes public `costTelemetry`; otherwise cost stays `pending`. `metadata/custody.json` remains `pending` until the custody manifest writer and public read surface land. `events/manifest.json` remains `unavailable` in this client-side slice because there is no public coordinator-manifest download route.
+
+The record boundary is public-safe. It must not contain provider API keys, runner bearers, workspace tokens, signed URLs, raw provider response bodies, object-store keys, Vault ids, raw query strings, secret-shaped values, or internal diagnostic files. Credentials are supplied per run and vaulted separately for the run lifetime.