@aexhq/sdk 0.38.1 → 0.40.0

package/docs/errors.md

@@ -5,9 +5,56 @@ 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. The SDK
-surfaces non-2xx responses as `AexApiError` (with the parsed body attached) and
-throttling as `AexRateLimitError`.
+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 redacted parsed
+`body`, 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, run_not_terminal, insufficient_balance, 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.run(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`, `run_not_terminal`, `unknown_workspace`,
+`workspace_concurrency_exceeded`, `workspace_submit_rate_exceeded`,
+`workspace_spend_cap_exceeded`, `insufficient_balance`, `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
+`RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`) before any
+request is sent.
 
 ## 401 — authentication
 
@@ -118,7 +165,20 @@ 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).
+does not distinguish the two). The SDK raises `AexNotFoundError` (guard:
+`isNotFound(err)`).
+
+## 409 — idempotency conflict
+
+`idempotency_conflict`: the `idempotencyKey` was already used with a **different**
+request body. The SDK raises `AexIdempotencyConflictError` (guard:
+`isIdempotencyConflict(err)`).
+
+**Remedy:** 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
+`RunConfigValidationError` before the request is sent — never pass `""`.
 
 ## 5xx — server errors
 

package/docs/events.md

@@ -23,10 +23,12 @@ const events = await session.events().list();
 ```
 
 ```ts
-// Stream the RunEvent snapshot shape: yields each event once, stops when the
-// session parks. Backed by polling the aex events endpoint.
+// Stream events as guarded `AexEventView`s: yields each event once, stops when
+// the session parks. Backed by polling the aex events endpoint. Every surface —
+// list(), stream(), streamEnvelopes() — yields the same `AexEventView` with a
+// populated `sequence` and the `is*()` guard methods.
 for await (const event of session.events().stream({ intervalMs: 1000 })) {
-  if (event.type === "TEXT_MESSAGE_CONTENT") {
+  if (event.isTextMessage()) {
     // ...
   }
 }
@@ -79,8 +81,9 @@ They need a global `WebSocket` (Bun or Node ≥ 22).
 
 `aex wait` is the host mirror of `session.wait()`:
 it polls until the session parks and prints the final `Session` record. Exit `0`
-when the session parked cleanly (`idle`/`suspended`), `1` for any other park
-(`error` / a non-clean terminal status), and `3` when `--timeout` elapses first
+when the session parked cleanly (`idle`/`suspended`/`succeeded`), `1` for any
+non-clean terminal outcome (`failed`/`timed_out`/`cancelled`), and `3` when
+`--timeout` elapses first
 (a `--timeout` on `events --follow` / `run --follow` uses the same exit-`3`
 convention). Durations accept `ms`/`s`/`m`/`h` suffixes or a bare millisecond integer.
 
@@ -100,13 +103,34 @@ for await (const event of turn) {
   console.log(event.sequence, event.type);
 }
 
-const result = await turn.done(); // status is usually "idle"
+const result = await turn.done(); // status is the terminal outcome, e.g. "succeeded"
 ```
 
-The turn stream ends when it sees `aex.session.idle`, `aex.session.suspended`, or
-`aex.session.error` for that turn. `aex.run(config)` is a convenience wrapper
-over the same flow: it opens a session, sends `message` once, and returns the
-collected session turn. The returned `runId` is the session id.
+The turn stream ends on the turn's park terminal: a resumable
+`aex.session.idle` / `aex.session.suspended`, a terminal outcome
+`aex.session.succeeded` / `.failed` / `.timed_out` / `.cancelled`, or the held
+`aex.session.awaiting_approval`. (The bare `aex.session.error` park is retired —
+a failed turn is `failed`, a wall-clock kill `timed_out`, a cancel `cancelled`.)
+`aex.run(config)` is a convenience wrapper over the same flow: it opens a
+session, sends `message` once, and returns the collected session turn. The
+returned `runId` is the session id.
+
+## Per-token streaming (`outputMode: 'stream'`)
+
+Assistant-text granularity is controlled by `outputMode` on `openSession` / `run`:
+
+- **`buffered`** (the default) — the assistant text arrives coalesced as one
+  `TEXT_MESSAGE_CONTENT` event per message.
+- **`stream`** — on a **streamable** provider you also receive per-token
+  `TEXT_MESSAGE_CONTENT` **deltas** as the model produces them, and a coalesced
+  final `TEXT_MESSAGE_CONTENT` (the archived twin) always follows. Streamable
+  providers today are Anthropic and the OpenAI-chat-shaped providers (DeepSeek,
+  OpenAI, Mistral, OpenRouter, Doubao / Doubao China).
+
+Streaming is **capability-gated and fail-closed**: requesting `outputMode: 'stream'`
+on a provider that has no streaming producer (currently `gemini`) is a typed
+rejection at submission parse — **not** a silent downgrade to buffered. Choose a
+streamable provider or drop back to `buffered` explicitly.
 
 ## Terminal events vs. the run record
 
@@ -119,21 +143,30 @@ on how the turn ends:
   instead (see below). Expect `RUN_ERROR` on stream-level failures, and treat
   `RUN_FINISHED` — when it does appear — as a low-latency "stop the spinner"
   hint, not a read-consistency barrier.
-- **`aex.session.*` park terminals** — `CUSTOM` events named `aex.session.idle`,
-  `aex.session.suspended`, or `aex.session.error`. On the managed plane these
-  are what actually end a turn: the session parks with the matching status, and
-  by the time the park event is broadcast the session record has already
-  reached that status. This is the terminal you should expect from a managed
-  run's event stream.
-
-The SDK's helpers cover both families so you never have to switch on the plane:
-
-- `isRunTerminal(event)` — true for the AG-UI `RUN_FINISHED` / `RUN_ERROR` pair.
-- `isRunSettled(event)` — true for the `aex.run.settled` settle barrier **and**
+- **`aex.session.*` park terminals** — `CUSTOM` events carrying the turn's
+  OUTCOME: `aex.session.succeeded` / `aex.session.failed` / `aex.session.timed_out`
+  / `aex.session.cancelled`, or a resumable/held park `aex.session.idle` /
+  `aex.session.suspended` / `aex.session.awaiting_approval`. On the managed plane
+  these are what actually end a turn. The park event ends the RENDER; the settle
+  commit (cost + usage + the authoritative outcome) lands shortly after — which
+  is why `run()`/`done()` await settle by DEFAULT and return the outcome as
+  `result.status` with `result.costUsd`/`result.usage` always populated (never a
+  bare `idle`). Pass `await: 'park'` (on `run(...)` or `session.send(msg, {...})`)
+  to return early at the park event when you don't need cost/usage. `result.costUsd`
+  is aex runtime/storage spend and **excludes** your BYOK provider charges — price
+  those from `result.usage` token counts. Ending a raw stream on the park event is
+  fine for live UI; read the settled record (or the default await-settle result)
+  when you need cost/usage/outcome.
+
+Each event the stream yields carries method guards that cover both families so
+you never have to switch on the plane:
+
+- `event.isRunTerminal()` — true for the AG-UI `RUN_FINISHED` / `RUN_ERROR` pair.
+- `event.isRunSettled()` — true for the `aex.run.settled` settle barrier **and**
   for any `aex.session.*` park terminal. The managed plane does not broadcast a
   separate `aex.run.settled` barrier — the park event plays that role — so
-  `isRunSettled` is the one guard that reliably means "this stream is done and
-  the record is authoritative".
+  `event.isRunSettled()` is the one check that reliably means "this stream is done
+  and the record is authoritative".
 
 To read the authoritative status consistently, use one of:
 
@@ -154,8 +187,8 @@ for await (const event of session.events().streamEnvelopes({ settleConsistent: t
 const settled = await aex.sessions.get(session.id); // parked/terminal here
 ```
 
-`settleConsistent: true` makes the iterator end exactly when `isRunSettled(event)`
-first fires; on a raw stream, apply `isRunSettled(event)` yourself. What it
+`settleConsistent: true` makes the iterator end exactly when `event.isRunSettled()`
+first fires; on a raw stream, call `event.isRunSettled()` yourself. What it
 guarantees: when the stream ends, a subsequent `aex.sessions.get(id)` reads a
 parked/terminal status and `session.outputs().list()` is complete. Outputs are
 uploaded before the terminal is broadcast, so they are readable the moment the
@@ -175,34 +208,36 @@ const jsonl = await response.text();
 
 ## Event shape
 
-Events are typed as the discriminated `RunEvent` union for compatibility and as the versioned coordinator envelope for live consumers. aex records raw runtime/provider payloads **after** secret redaction and structural sanitization, so the bytes you see never contain provider keys, MCP credentials, or runtime secrets supplied when the session was opened.
+Every read and stream surface yields one canonical shape — the versioned coordinator envelope, wrapped as an `AexEventView` with a populated non-optional `sequence` and the `is*()` guard methods. `sequence` is **sparse by design** (it encodes journal position, not a dense 0..N counter), so resume by cursor VALUE (`from: lastSequence`), never by integer adjacency. Tool-call START and RESULT events share a `data.id` join key, exposed as `event.toolCallId()` on those views. aex records raw runtime/provider payloads **after** secret redaction and structural sanitization, so the bytes you see never contain provider keys, MCP credentials, or runtime secrets supplied when the session was opened.
 
 ## Typed helpers
 
-The package exports conservative type guards over run events:
+Every event the SDK yields — the turn stream (`session.send()`),
+`session.events().list()`, `session.events().streamEnvelopes()`, and
+`RunResult.events` — carries a type-guard **method** for each standardized event
+type, so you branch on the event without importing a free function or writing a
+raw `event.type === "…"` compare:
 
 ```ts
-import {
-  isRunStarted,
-  isRunFinished,
-  isRunError,
-  isRunTerminal,
-  isRunSettled,
-  isTextMessage,
-  isToolCallStart,
-  isToolCallResult,
-  isCustom,
-  isLog,
-  isEventChannel
-} from "@aexhq/sdk";
+for await (const event of session.send("Continue the task.")) {
+  if (event.isTextMessage()) {
+    process.stdout.write(event.data.text); // `data.text` is typed `string` here
+  } else if (event.isToolCallStart()) {
+    console.log("tool:", event.data.name); // `data.name` is typed `string` here
+  } else if (event.isRunError()) {
+    console.error("run error");
+  }
+}
 ```
 
-All guards test the `type` discriminant at runtime. `isTextMessage`,
-`isToolCallStart`, `isToolCallResult`, and `isRunFinished` operate on the loose
-`RunEvent` snapshot (`session.events().list()` / `RunResult.events`) and additionally NARROW
-`event.data` to the fields that event type carries — e.g. inside
-`if (isTextMessage(e))`, `e.data.text` is typed `string`. The lifecycle/channel
-guards (`isRunStarted`, `isRunError`, `isCustom`, `isLog`, …) operate on the
-coordinator envelope and narrow only the discriminant. Use `result.text` or
-`session.messages.all()` when you need assistant text without inspecting the
-event stream directly.
+The full method set: `isRunStarted()`, `isRunFinished()`, `isRunError()`,
+`isRunTerminal()`, `isTextMessage()`, `isToolCallStart()`, `isToolCallResult()`,
+`isCustom()`, `isLog()`, `isEventChannel()`, `isRunSettled()`, and
+`isFromSource(source)`. All test the `type` (or `channel`/`source`) discriminant
+at runtime. `isTextMessage()`, `isToolCallStart()`, and `isToolCallResult()` are
+TS type predicates: inside the guarded branch `event.data` NARROWS to that event
+type's payload fields (e.g. `event.data.text` is typed `string`). Annotate a
+narrowed event with the exported `TextMessageEventView` / `ToolCallStartEventView`
+/ `ToolCallResultEventView` types, or a raw event with `AexEventView`. Use
+`result.text` or `session.messages.all()` when you need assistant text without
+inspecting the event stream directly.

package/docs/limits-and-quotas.md

@@ -31,6 +31,7 @@ And whether you can **raise** it: per-run option, per-plan, or no.
 | MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
 | MCP call timeout (default) | 30 minutes | aex policy | Per-port via `callTimeoutMs` | `RUN_DEFAULT_MCP_CALL_TIMEOUT_MS` |
 | Per-session spend cap | None by default; when set, the session is stopped once its spend would exceed the cap | aex policy | Per-session via `overrides.maxSpendUsd` (a positive USD amount) | — |
+| Max agent iterations (turns) per run | 20 by default; hard ceiling 200 | aex policy | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling) | `RUN_DEFAULT_MAX_TURNS` / `RUN_MAX_TURNS_CEILING` |
 
 ### Output capture (per run)
 
@@ -69,6 +70,29 @@ silently lost.
 | Per-run metadata record TTL | 24 hours | aex policy | No (hard ceiling) | `RUN_KV_RECORD_TTL_SECONDS` |
 | Per-run secret-envelope TTL | 24 hours | aex policy | No (hard ceiling) | `RUN_KV_SECRET_TTL_SECONDS` |
 
+## Sandbox (managed runtime)
+
+Each run executes in an ephemeral Linux container sized by the `runtime` preset.
+A few behaviours are worth knowing before you rely on the filesystem or RAM:
+
+- **Only `/workspace` persists across turns** of the same session. Everything
+  outside `/workspace` is reset between turns and is gone when the session ends —
+  write deliverables and any state you want to survive a turn under `/workspace`.
+- **The image is minimal.** Declare OS/language packages with
+  `environment.packages` so they are present deterministically at boot. A runtime
+  install inside the agent (`pip install`, `apt-get`) is best-effort and
+  **non-persistent** (reset next turn), and `pip` is subject to PEP 668
+  (`externally-managed-environment`) — prefer `environment.packages`, or a
+  virtualenv you create under `/workspace`.
+- **`/proc/meminfo` reports the HOST's RAM, not your preset's.** Your actual
+  memory ceiling is the preset's `memoryMb` (e.g. `shared-0.25x-1gb` = 1 GB, the
+  default; `shared-4x-12gb` = 12 GB). The presets are the SSoT in
+  [`packages/contracts/src/runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts);
+  see [Defaults](defaults.md).
+- **The agent loop is bounded** by `maxTurns` (default 20, ceiling 200) — a
+  documented, per-run-overridable limit (see the Run scope table above and
+  `overrides.maxTurns`), not a silent cutoff.
+
 ## Workspace scope
 
 | Limit | Value | Source | Raisable? | Constant |

package/docs/mcp.md

@@ -29,8 +29,9 @@ For ingestion-style MCP servers that return large JSON blobs (search results,
 catalogue dumps, bulk reads), prefer a skill that writes files instead of
 putting the whole response in model context:
 
-1. Package the upstream as a skill-tool (`Tools.fromSkillDir` /
-   `Tools.fromSkillUrl`) — a CLI binary the agent invokes with its bash tool.
+1. Package the upstream helper as a Skill (`Skill.fromDir` / `Skill.fromUrl`)
+   and pass it via the top-level `skills` option. The skill can include a CLI
+   binary or script that the agent invokes with its bash tool.
 2. Keep any upstream HTTPS credentials in `environment.secrets`.
 3. Have the CLI write the full payload to the session filesystem. By default,
    files it creates or modifies are captured automatically; pass

package/docs/networking.md

@@ -15,7 +15,13 @@ internet**. Outbound traffic is governed by **two layers**:
    (model providers, built-in tool endpoints, package registries, and related
    well-known development hosts such as `github.com`) and enforces a fixed SSRF
    deny-list: loopback, link-local, cloud-metadata, and other private ranges are
-   always blocked, including hostnames that resolve to those ranges.
+   blocked on the standard proxy path every normal HTTP client uses, including
+   hostnames that resolve to those ranges. Note: on the current managed (Fargate)
+   plane a subprocess that deliberately bypasses the proxy with a **raw socket**
+   can still reach the on-link task-metadata IP (`169.254.170.2`), which exposes
+   non-secret task identity (AWS account id via the task ARN, cluster/image ref)
+   — but **never IAM credentials** (the run's task role is unset, so the metadata
+   credential endpoint serves nothing) and never another tenant's data.
 
 Honest boundary statement: the per-run `allowedHosts` policy is enforced by the
 run's own runtime on the standard proxy path — it is **not** yet enforced at

package/docs/outputs.md

@@ -4,7 +4,7 @@ title: Outputs
 
 # Outputs
 
-Every session produces durable metadata (status, events, snapshots, cleanup state) and an outputs namespace. By default, managed runs capture every regular file the agent creates or modifies in the container: the runner snapshots the filesystem just before the agent starts, rescans it when the agent exits, and uploads the delta. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `session.download()` returns the public session record — metadata, typed events, and captured output bytes — as a zip; the per-namespace verbs (`session.outputs().download()` / `session.events().download()` / `session.downloadMetadata()`) return one slice each.
+Every session produces durable metadata (status, events, cleanup state) and an outputs namespace. By default, managed runs capture the regular files present in the container when the agent exits, EXCLUDING the inputs the platform itself materialized for you (your mounted `files`/`skills`) — those are excluded by IDENTITY (their exact destination paths and skill-dir prefixes), not by any before/after timing comparison. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `session.download()` returns the public session record — metadata, typed events, and captured output bytes — as a zip; the per-namespace verbs (`session.outputs().download()` / `session.events().download()` / `session.downloadMetadata()`) return one slice each.
 
 The output verbs below hang off the session's `outputs()` accessor
 (`session.outputs().list()`, `.read()`, `.download()`, …). Reach a handle from a
@@ -28,7 +28,7 @@ await session.download({ to: "./session.zip" });
 ```
 
 ```bash
-aex download <session-id> --out ./session.zip --api-key …
+npx aex download <session-id> --out ./session.zip --api-key …
 ```
 
 ## The three namespaces
@@ -133,6 +133,35 @@ Query fields compose with AND semantics:
 
 `session.outputs().findOne(query)` returns `null` when nothing matches and throws `RunStateError` when the query matches more than one output.
 
+## Searching outputs
+
+Search is metadata-only (reference hits — filename / extension / content type — no bytes). `filename` accepts a `string` (case-insensitive substring) or a `RegExp`. A content-shaped query (`content`/`text`/…) throws a typed "content search unsupported" rather than silently returning zero hits.
+
+```ts
+// One session's outputs:
+const hits = await session.outputs().search({ filename: /report/i });
+
+// Across every run in the workspace (or scope with runIds):
+const all = await aex.outputs.search({ extension: "md", runIds: ["run-a", "run-b"] });
+```
+
+Each hit is `{ runId, outputId, filename?, sizeBytes?, contentType? }`; read the bytes with `session.outputs().read(...)` / `.download(...)`.
+
+## CLI
+
+The `aex outputs` verb is a thin pass-through over the same SDK accessor, so every per-file operation has a subcommand (`npx aex` on a local install):
+
+```bash
+npx aex outputs <session-id>                          # list captured outputs (NDJSON)
+npx aex outputs read <session-id> <path>              # read one file as capped text (JSON)
+npx aex outputs download <session-id> <path> --out f  # download one file's raw bytes
+npx aex outputs link <session-id> <path>              # mint a temporary download URL (JSON)
+npx aex outputs find <session-id> --name S --ext E --type T
+npx aex outputs search --query S --ext E --run-id ID  # cross-run metadata search
+```
+
+`aex outputs search` (no session id) is the cross-run search (`aex.outputs.search`); the whole-namespace zip stays `aex download <session-id>`.
+
 ## Temporary output links
 
 Use `session.outputs().link(selectorOrQuery, options?)` when another process, browser, media tag, or downloader needs a direct artifact URL instead of bytes buffered through the SDK.
@@ -190,7 +219,7 @@ Validation:
 
 Runtime notes:
 
-- The managed runtime captures files by diffing the filesystem against a baseline snapshot taken just before the agent starts. Platform setup files, installed packages, and materialized inputs are already present before the baseline, so they are excluded by timing.
+- The managed runtime captures the regular files under the capture roots at terminal time, EXCLUDING the inputs the platform itself materialized (your mounted `files`/`skills`) by IDENTITY — their exact destination paths and skill-dir prefixes are threaded into the capture filter, so an untouched mounted input is never re-emitted as an output regardless of path policy or timing.
 - If you pass an explicit root that does not exist by terminal time, that root contributes no files.
 
 ## `outputs.deniedDirs` — subtract noise
@@ -208,10 +237,10 @@ aex.openSession({
 
 Mechanism (no platform-magical paths — this is honest):
 
-1. The hosted platform materializes the workspace, opens runtime logs, and records a filesystem baseline across the capture roots.
+1. The hosted platform materializes the workspace (your mounted `files`/`skills`) and records the exact destination paths + skill-dir prefixes it wrote.
 2. The agent runs normally. There is no extra model turn and no synthetic sync instruction.
-3. When the agent exits, the runner rescans the capture roots and finds files that are new or whose metadata changed.
-4. The runner uploads changed regular files to durable run artifact storage. Diagnostic log paths are routed to internal diagnostics under `runs/<runId>/internal/logs/`; other paths are routed to `outputs`.
+3. When the agent exits, the runner scans the capture roots and drops any file whose path is a materialized INPUT (exact path or under a materialized skill dir) — inputs are excluded by WHO PUT THEM THERE (the platform), not by timing.
+4. The runner uploads the remaining regular files to durable run artifact storage. Diagnostic log paths are routed to internal diagnostics under `runs/<runId>/internal/logs/`; other paths are routed to `outputs`.
 
 Cost: output capture does not add a model turn. The runner pays a filesystem scan and upload cost near the end of the run.
 
@@ -228,7 +257,7 @@ Metadata still gets the full treatment. aex captures every regular file the run
 
 ## Mid-session download semantics
 
-Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the filesystem diff. If you need the full output set, wait for the session to park and call `session.download()` again.
+Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the runner scans the capture roots. If you need the full output set, wait for the session to park and call `session.download()` again.
 
 ## Safety
 

package/docs/provider-runtime-capabilities.md

@@ -40,7 +40,7 @@ All new submissions run on the managed runtime. Public support is expressed as s
 
 ## Skills
 
-Skills are supplied as load-tools in the `tools` array. Build one with `Tools.fromSkillDir` or `Tools.fromSkillUrl`; each normalizes to an asset that the platform snapshots into durable run asset storage.
+Skills are supplied through the top-level `skills` option. Build one with `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles`, `Skill.fromContent`, or `Skill.fromBytes`; each normalizes to a named workspace skill that the platform snapshots into durable run asset storage.
 
 Notes:
 

package/docs/quickstart.md

@@ -16,9 +16,10 @@ This installs the TypeScript SDK exports and the bundled `aex` CLI.
 
 aex is currently in **invite-only beta**: workspaces and API keys are issued
 by the aex team — contact <support@aex.dev> for beta access. Once you have
-access, create a quickstart SDK token with `runs:read`, `runs:write`, and
-`outputs:read` in the dashboard at <https://aex.dev>. The examples also need
-your BYOK provider key for the model you choose. For the Claude examples below:
+access, create a quickstart SDK token with `runs:read`, `runs:write`,
+`outputs:read`, and `billing:read` in the dashboard at <https://aex.dev>. The
+examples also need your BYOK provider key for the model you choose. For the
+Claude examples below:
 
 ```bash
 export AEX_API_KEY="<your-aex-api-key>"
@@ -41,9 +42,16 @@ const session = await aex.openSession({
 });
 
 const first = await session.send("Write a short report and save it as a file.").done();
-console.log(first.status, first.text);
+console.log(first.status, first.costUsd, first.text);
 ```
 
+`send().done()` (and `run()`) **await settle by default**, so the result always
+carries a terminal `status` (`succeeded` / `failed` / `timed_out` / `cancelled`
+— never a bare `idle`) plus `costUsd` and `usage`. Pass `await: 'park'` to
+return early at the render-complete park event when you don't need cost/usage.
+`costUsd` is aex runtime/storage spend and **excludes** your BYOK provider
+charges — price those from `usage` token counts against your provider's rates.
+
 The session parks as `idle` between turns and automatically moves to
 `suspended` after the idle window. Keep the session id and resume later:
 
@@ -88,7 +96,8 @@ await turn.done();
 const messages = await session.messages().list();
 console.log(messages.at(-1)?.text);
 
-// Poll the record until the session parks (idle / suspended / error).
+// Poll the record until the session parks: a resumable `idle` / `suspended`,
+// or a terminal outcome (`succeeded` / `failed` / `timed_out` / `cancelled`).
 const record = await session.wait();
 console.log(record.status);
 
@@ -96,10 +105,11 @@ console.log(record.status);
 await session.download({ to: "./session.zip" });
 ```
 
-The same run from the bundled CLI:
+The same run from the bundled CLI (`npx aex` on a local install; or
+`npm i -g @aexhq/sdk` for a bare `aex`):
 
 ```bash
-aex run \
+npx aex run \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \

package/docs/run-config.md

@@ -14,9 +14,9 @@ Allowed fields:
 - `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? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap (see [Limits & quotas](limits-and-quotas.md)).
+- `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`, `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 `tools` entries built with `Tools.fromSkillDir(...)` / `Tools.fromSkillUrl(...)`, 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`), but the session surface exposes only its spend dial — set it with `overrides.maxSpendUsd`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
+`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
@@ -55,4 +55,4 @@ aex run --config ./run.json \
   --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.
+...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/secrets.md

@@ -118,3 +118,17 @@ await aex.secrets.delete("serper-api-key");
 
 The CLI supports per-run provider and MCP credentials. Workspace secret
 administration is exposed through the SDK.
+
+## Redaction Scope And Output Files
+
+Registered secret values are redacted from the run's **event stream** (both tool
+output and model-authored surfaces) — a value you inject via `environment.secrets`
+is masked regardless of its shape. Two surfaces are intentionally *not* scrubbed:
+
+- **Captured output files** (`outputs().download()` / `read()` / the `aex download`
+  zip) are returned **verbatim**. They are your run's own artifacts, so the platform
+  does not rewrite their bytes — if the agent writes a secret into a deliverable file,
+  that file contains it. Treat downloaded outputs as unredacted.
+- An **unregistered** secret (a credential the run produces itself and never declared
+  via `environment.secrets`) can only be masked heuristically by shape; register the
+  values you care about so they are masked by value.