@aexhq/sdk 0.40.16 → 0.41.0

package/docs/concepts/subagents.md

@@ -1,12 +1,12 @@
 ---
 title: Subagents
-description: Delegate bounded sub-tasks to child agent runs with the subagent tool.
+description: Delegate bounded sub-tasks to child agent sessions with the subagent tool.
 icon: GitFork
 ---
 
-A run can delegate bounded sub-tasks to **child agent runs** with the built-in
+A session can delegate bounded sub-tasks to **child agent sessions** with the built-in
 `subagent` tool. Delegation is agent-driven: the model decides to fan work out,
-each child is a real run with its own record, and the parent collects results
+each child is a real session with its own record, and the parent collects results
 as the children finish. There is no client-side parent/child API — lineage is
 session-internal.
 
@@ -16,9 +16,9 @@ The agent calls `subagent` with a `prompt` and a `model` (both required), plus
 optional `system`, `provider`, `runtimeSize`, `timeout`,
 `includeBuiltinTools`, `tools` (builtin-tool names for the child), `skills`,
 and `files`. The call is **always async**: on a successful spawn it returns
-immediately with the child run id, and the parent keeps working while the child
-runs. When a child settles, the parent is notified in its loop, and it reads
-the child's status and captured outputs on demand with the companion
+immediately with the child session id, and the parent keeps working while the child
+sessions. When a child settles, the parent is notified in its loop, and it reads
+the child's status and captured files on demand with the companion
 `subagent_result` tool.
 
 Children inherit the parent's vaulted BYOK provider keys server-side — the
@@ -46,7 +46,7 @@ dials today.
 
 ## Where children run: `in-process` vs `container`
 
-By default a child runs **in-process**: it executes as a sibling agent process
+By default a child sessions **in-process**: it executes as a sibling agent process
 inside the parent's own machine, sharing the parent's CPU, memory, and
 lifetime. This is the platform default shipped today.
 
@@ -60,7 +60,7 @@ lifetime. This is the platform default shipped today.
 - **Joined lifecycle.** The parent's terminal waits for its in-process children,
   and their results are folded into the parent's per-child accounting. Platform
   recovery re-spawns in-process children exactly once if the parent's machine
-  is replaced mid-run — settled children are never re-run.
+  is replaced mid-session — settled children are never retry.
 
 The escape valve is `host: "container"`: the child is dispatched to its **own
 isolated machine** with its own runtime size and its own runtime billing, and
@@ -70,21 +70,21 @@ the parent can share.
 
 ## Lineage and observability
 
-Every child — in-process or container — is a first-class run record:
+Every child — in-process or container — is a first-class session record:
 
-- The parent's transcript logs each spawn with the child's run id.
-- Each child has its own status, typed event timeline, and captured outputs.
-  The child's events and outputs are readable by id
-  (`aex.sessions.outputs(id)` in the SDK, or the CLI's `aex events` /
-  `aex outputs`). Child runs are not served by the session read surface
+- The parent's transcript logs each spawn with the child's session id.
+- Each child has its own status, typed event timeline, and captured files.
+  The child's events and files are readable by id
+  (`aex.sessions.files(id)` in the SDK, or the CLI's `aex events` /
+  `aex files`). Child sessions are not served by the session read surface
   today — `aex.sessions.get(id)` / `aex sessions` / the CLI's `aex status`
   answer `not_found` for a child id.
-- The child's outputs are handed back to the parent via `subagent_result`, and
+- The child's files are handed back to the parent via `subagent_result`, and
   they remain independently downloadable after the lineage finishes.
 
 ## Bounding delegation
 
-- Turn delegation off for a run by cherry-picking builtins without `subagent`
+- Turn delegation off for a session by cherry-picking builtins without `subagent`
   (see [Agent tools](agent-tools.md)) or setting `includeBuiltinTools: false`.
 - A per-session spend cap (`overrides.maxSpendUsd`) bounds the parent's spend.
 - The depth/breadth budgets above are platform-managed and are not settable

package/docs/credentials.md

@@ -11,7 +11,7 @@ aex uses explicit, per-session credentials:
 - `McpServer.remote(..., { headers })` carries MCP auth when a remote MCP server needs it.
 - `environment.secrets` carries runtime secrets for your own code.
 
-Secrets never belong in reusable run config, files, prompts, or examples.
+Secrets never belong in reusable session config, files, prompts, or examples.
 
 ## The client credential
 
@@ -35,7 +35,7 @@ A session selects one upstream provider and must carry a BYOK key for it. Includ
 additional provider keys only when subagents may use those providers.
 
 ```ts
-const result = await aex.run({
+const result = await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Write a short report and save it as a file.",
   apiKeys: {
@@ -58,7 +58,7 @@ import { Aex, Models, Secret } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Call https://api.example.com/v1/status with INTERNAL_API_TOKEN and summarize it.",
   environment: {
@@ -74,7 +74,7 @@ await aex.run({
 });
 ```
 
-Inside the run, use normal HTTP code for the service:
+Inside the session, use normal HTTP code for the service:
 
 ```bash
 curl -sS \
@@ -86,7 +86,7 @@ curl -sS \
 
 > **Availability note:** workspace-secret `Secret.ref(...)` injection requires
 > the next platform deploy — on the current hosted plane the referenced
-> variable can resolve empty inside the run. Per-run `Secret.value(...)`
+> variable can resolve empty inside the session. Per-session `Secret.value(...)`
 > secrets are unaffected.
 
 Store reusable values once, then reference them by name:
@@ -97,7 +97,7 @@ await aex.secrets.set({
   value: process.env.INTERNAL_API_TOKEN!
 });
 
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Use INTERNAL_API_TOKEN for the status request.",
   environment: {
@@ -115,7 +115,7 @@ Secret reads return metadata only; they never return the stored value.
 
 Networking is open by default within the platform's managed egress ceiling. Use
 `environment.networking.mode: "limited"` with `allowedHosts` when you want a
-run's own code to reach only named hosts. See [Networking](networking.md) for
+session's own code to reach only named hosts. See [Networking](networking.md) for
 the two-layer enforcement model.
 
 ## Explicit call-site rule

package/docs/defaults.md

@@ -5,7 +5,7 @@ title: Defaults
 # Defaults
 
 These are the values aex applies when you **omit** the corresponding option on a
-run. Every value is mirrored from a single source-of-truth constant in the
+session. Every value is mirrored from a single source-of-truth constant in the
 platform's limits module; this page is hand-maintained against those constants.
 If a value here ever disagrees with the constant, the constant wins.
 
@@ -16,34 +16,34 @@ For the hard ceilings and who can raise them, see
 [Limits & quotas](limits-and-quotas.md). For policy boundaries, see
 [Limits](limits.md).
 
-## Run
+## SessionRecord
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| `timeout` (run deadline) | 8 hours (also the ceiling) | Per-session via `overrides.timeout` (e.g. `"30m"`, `"2h"`). Values outside the run-timeout floor (1 minute) / ceiling (8 hours) are rejected with `RunConfigValidationError` before submission. | `RUN_DEFAULT_TIMEOUT_MS` |
-| `runtime` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-session via `runtime` (use `Sizes.*` in TypeScript). | `RUN_DEFAULT_RUNTIME_SIZE` |
+| `timeout` (session deadline) | 8 hours (also the ceiling) | Per-session via `overrides.timeout` (e.g. `"30m"`, `"2h"`). Values outside the session-timeout floor (1 minute) / ceiling (8 hours) are rejected with `SessionConfigValidationError` before submission. | `SESSION_DEFAULT_TIMEOUT_MS` |
+| `runtime` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-session via `runtime` (use `Sizes.*` in TypeScript). | `SESSION_DEFAULT_RUNTIME_SIZE` |
 | `overrides.maxSpendUsd` (per-session spend cap) | None — no spend cap (the session is still bounded by its `timeout` and any workspace-level cap) | Per-session via `overrides.maxSpendUsd` (a positive USD amount); the session is stopped once its spend would exceed the cap. | — |
-| `overrides.maxTurns` (agent iterations per run) | 20 (ceiling 200) | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling). | `RUN_DEFAULT_MAX_TURNS` |
+| `overrides.maxTurns` (agent iterations per session) | 20 (ceiling 200) | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling). | `SESSION_DEFAULT_MAX_TURNS` |
 
 ## Tools
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Per-call exec timeout | 30 minutes | Per-call via the tool call's `timeoutMs`. | `RUN_DEFAULT_EXEC_TIMEOUT_MS` |
+| Per-call exec timeout | 30 minutes | Per-call via the tool call's `timeoutMs`. | `SESSION_DEFAULT_EXEC_TIMEOUT_MS` |
 | `web_fetch` returned body | 500 KB (UTF-8) | Per-call via the tool's `max_bytes` argument. | `REQUEST_WEB_FETCH_DEFAULT_MAX_BYTES` |
 
 ## MCP
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| MCP connect timeout (register + initialize + discover) | 30 seconds | Per-port via `connectTimeoutMs`. | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
-| MCP `tools/call` timeout | 30 minutes | Per-port via `callTimeoutMs`. | `RUN_DEFAULT_MCP_CALL_TIMEOUT_MS` |
+| MCP connect timeout (register + initialize + discover) | 30 seconds | Per-port via `connectTimeoutMs`. | `SESSION_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
+| MCP `tools/call` timeout | 30 minutes | Per-port via `callTimeoutMs`. | `SESSION_DEFAULT_MCP_CALL_TIMEOUT_MS` |
 
 ## Links (signed URLs and tickets)
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Output link / signed-URL TTL | 300 seconds (5 minutes) at the storage layer; `session.outputs().link(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `session.outputs().link` / `session.outputs().fetch`. | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
+| SessionFile link / signed-URL TTL | 300 seconds (5 minutes) at the storage layer; `session.files().link(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `session.files().link` / `session.files().fetch`. | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
 | Event-stream connection ticket TTL | 60 seconds | Per-mint via the `ttlMs` argument. | `REQUEST_TICKET_DEFAULT_TTL_MS` |
 
 ## Subagents
@@ -53,15 +53,15 @@ numeric entitlements; exact operational values may change as capacity evolves.
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Concurrent child runs per lineage root | Platform-managed; designed to scale across hundreds, even thousands, of live child agents. | No public per-run override; contact support for unusually large workloads. | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
-| Max subagent depth | Platform-managed; supports high recursive subagent depth. | No public per-run override. | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
+| Concurrent child sessions per lineage root | Platform-managed; designed to scale across hundreds, even thousands, of live child agents. | No public per-session override; contact support for unusually large workloads. | `SESSION_DEFAULT_MAX_CONCURRENT_CHILD_SESSIONS` |
+| Max subagent depth | Platform-managed; supports high recursive subagent depth. | No public per-session override. | `SESSION_MAX_PUBLIC_SUBAGENT_DEPTH` |
 
 ## Workspace
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Run submit rate (per minute) | 120 (`0` = disabled); past it `POST /runs` fails with `429 workspace_submit_rate_exceeded` | Per-plane via env `AEX_WORKSPACE_SUBMIT_RATE_PER_MIN`; per-workspace via support. | — |
-| Max concurrent runs | Plan-based: 5 live root runs (free), 50 (Pro), 200 (Team); hard ceiling 200 | Per-plan (upgrade) or per-workspace override via support, clamped to the ceiling. | `PLANS[planKey].maxConcurrentRuns` |
+| SessionRecord submit rate (per minute) | 120 (`0` = disabled); past it `POST /sessions` fails with `429 workspace_submit_rate_exceeded` | Per-plane via env `AEX_WORKSPACE_SUBMIT_RATE_PER_MIN`; per-workspace via support. | — |
+| Max concurrent sessions | Plan-based: 5 live root sessions (free), 50 (Pro), 200 (Team); hard ceiling 200 | Per-plan (upgrade) or per-workspace override via support, clamped to the ceiling. | `PLANS[planKey].maxConcurrentSessions` |
 | Monthly spend cap | $250 per UTC calendar month (`0` = unlimited) | Per-workspace override via support. | `WORKSPACE_DEFAULT_SPEND_CAP_USD` |
-| Per-workspace mutation rate limits (per minute) | run cancel 30, run delete 30, signed link 120, API key create 10, API key delete 30 | Per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var. | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
+| Per-workspace mutation rate limits (per minute) | session cancel 30, session delete 30, signed link 120, API key create 10, API key delete 30 | Per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var. | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | Workspace storage cap | 500 GB (decimal) | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES`; admin workspaces are uncapped (not a customer entitlement). | `WORKSPACE_DEFAULT_STORAGE_CAP_BYTES` |

package/docs/errors.md

@@ -21,7 +21,7 @@ factory dispatches to a subclass by code/status:
 | `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, …) | — |
+| `AexApiError` (base) | every other stable code (session_busy, session_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`,
@@ -31,7 +31,7 @@ codes: `isAuthError`, `isInsufficientScope`, `isIdempotencyConflict`,
 import { isInsufficientScope, isIdempotencyConflict } from "@aexhq/sdk";
 
 try {
-  await aex.run(config);
+  await aex.start(config);
 } catch (err) {
   if (isInsufficientScope(err)) {
     // err.requiredScope names the missing scope; mint a key that includes it.
@@ -44,7 +44,7 @@ try {
 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`,
+`session_busy`, `session_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
@@ -53,7 +53,7 @@ The **stable** `apiCode` set the SDK types and dispatches on is: `unauthorized`,
 
 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
+`SessionConfigValidationError` (`err.code === "SESSION_CONFIG_INVALID"`) before any
 request is sent.
 
 ## 401 — authentication
@@ -78,7 +78,7 @@ is the cheapest way to validate a credential. See
 | `forbidden` | The authenticated workspace does not own the addressed resource. |
 
 ```json
-{ "error": "insufficient_scope", "requiredScope": "runs:write" }
+{ "error": "insufficient_scope", "requiredScope": "sessions:write" }
 ```
 
 ## 400 — validation
@@ -91,7 +91,7 @@ is the cheapest way to validate a credential. See
 | `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 (`RunConfigValidationError`) catches most of
+The SDK's client-side validation (`SessionConfigValidationError`) catches most of
 these before the request is sent.
 
 ## 402 — payment required
@@ -104,7 +104,7 @@ effective submit floor. Top up the balance or bind a payment method.
 ```json
 {
   "error": "insufficient_balance",
-  "message": "Workspace balance is depleted; top up your prepaid balance or bind a payment method to submit runs.",
+  "message": "Workspace balance is depleted; top up your prepaid balance or bind a payment method to submit sessions.",
   "balanceUsd": 0,
   "balanceGraceFloorUsd": 0,
   "paymentMethodStatus": "none",
@@ -132,13 +132,13 @@ raise it.
 ## 429 — rate limits
 
 **`workspace_concurrency_exceeded`** — admitting one more live run would exceed
-the workspace's concurrent-run cap. Wait for a run to finish, or contact
+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 runs at the cap of 50. Wait for a run to finish, or contact support to raise your workspace limit.",
+  "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
 }
@@ -178,7 +178,7 @@ request body. The SDK raises `AexIdempotencyConflictError` (guard:
 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 `""`.
+`SessionConfigValidationError` before the request is sent — never pass `""`.
 
 ## 5xx — server errors
 

package/docs/events.md

@@ -4,7 +4,7 @@ title: Events
 
 # Events
 
-aex runs agent sessions on the managed runtime. Sessions are **non-blocking**:
+aex sessions agent sessions on the managed runtime. Sessions are **non-blocking**:
 the managed runtime advances the agent while aex observes lifecycle state, maps
 runtime output into one event shape, and persists every captured event. The SDK
 and CLI observe the durable event timeline from aex — there is no in-process
@@ -14,7 +14,7 @@ tool-approval hook.
 
 A session's reads and streams are grouped under accessor sub-resources:
 `session.events()` owns the event timeline, `session.messages()` owns the decoded
-assistant text, and `session.outputs()` owns the captured files. Reach a verb by
+assistant text, and `session.files()` owns the captured files. Reach a verb by
 chaining it off the accessor.
 
 ```ts
@@ -74,7 +74,7 @@ stream as `session.events().streamEnvelopes()` (replay-from-cursor + tail +
 exactly-once resume), so they are the low-latency equivalents of
 `events --follow`'s polling. `--json` is the raw-NDJSON escape hatch; `--filter`
 keeps only the named AG-UI types (`TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, …)
-or sources (`agent`/`runtime`/…); a `RUN_ERROR` is surfaced as a jump-to-failure
+or sources (`agent`/`runtime`/…); a `TURN_ERROR` is surfaced as a jump-to-failure
 line. `aex inspect` adds a header, a settle-consistent full timeline, and a
 cost/usage footer. Both exit `0` parked cleanly / `1` error park / `3` timeout.
 They need a global `WebSocket` (Bun or Node ≥ 22).
@@ -93,7 +93,7 @@ message is accepted replays the events it missed, then continues live.
 ## Session turn events
 
 The canonical SDK session surface stops a turn on session lifecycle events, not
-terminal run events:
+terminal session events:
 
 ```ts
 const session = await aex.openSession(config);
@@ -111,9 +111,9 @@ The turn stream ends on the turn's park terminal: a resumable
 `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
+`aex.start(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.
+returned `sessionId` is the session id.
 
 ## Per-token streaming (`outputMode: 'stream'`)
 
@@ -132,16 +132,16 @@ 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
+## Terminal events vs. the session record
 
 Two families of events can end a turn's stream, and which one you see depends
 on how the turn ends:
 
-- **AG-UI terminals** — `RUN_FINISHED` / `RUN_ERROR`. These are *render-complete*
+- **AG-UI terminals** — `TURN_FINISHED` / `TURN_ERROR`. These are *render-complete*
   signals emitted by the agent stream itself. On the managed plane a normal
-  session turn usually does **not** emit `RUN_FINISHED`: the session *parks*
-  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"
+  session turn usually does **not** emit `TURN_FINISHED`: the session *parks*
+  instead (see below). Expect `TURN_ERROR` on stream-level failures, and treat
+  `TURN_FINISHED` — when it does appear — as a low-latency "stop the spinner"
   hint, not a read-consistency barrier.
 - **`aex.session.*` park terminals** — `CUSTOM` events carrying the turn's
   OUTCOME: `aex.session.succeeded` / `aex.session.failed` / `aex.session.timed_out`
@@ -149,11 +149,11 @@ on how the turn ends:
   `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
+  is why `start()`/`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
+  is aex starttime/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.
@@ -161,11 +161,11 @@ on how the turn ends:
 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**
+- `event.isTurnTerminal()` — true for the AG-UI `TURN_FINISHED` / `TURN_ERROR` pair.
+- `event.isSessionSettled()` — true for the `aex.session.settled` settle barrier **and**
   for any `aex.session.*` park terminal. The managed plane emits the barrier after
   settle when it is delivered to the stream; the park event remains a terminal
-  fallback for streams that do not receive a later barrier. `event.isRunSettled()`
+  fallback for streams that do not receive a later barrier. `event.isSessionSettled()`
   is the one check that reliably means "this stream is done and the record is
   authoritative".
 
@@ -188,16 +188,16 @@ 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 `event.isRunSettled()`
-first fires; on a raw stream, call `event.isRunSettled()` yourself. What it
+`settleConsistent: true` makes the iterator end exactly when `event.isSessionSettled()`
+first fires; on a raw stream, call `event.isSessionSettled()` 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
+parked/terminal status and `session.files().list()` is complete. Files are
 uploaded before the terminal is broadcast, so they are readable the moment the
 stream ends.
 
 ## Temporary event archive links
 
-For terminal runs, `session.events().archiveLink(options?)` returns a temporary direct URL to `events.jsonl`, the same redacted customer-visible event export used by `session.events().download()`.
+For terminal sessions, `session.events().archiveLink(options?)` returns a temporary direct URL to `events.jsonl`, the same redacted customer-visible event export used by `session.events().download()`.
 
 ```ts
 const link = await session.events().archiveLink({ expiresIn: "1h" });
@@ -215,7 +215,7 @@ Every read and stream surface yields one canonical shape — the versioned coord
 
 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
+`SessionResult.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:
 
@@ -225,15 +225,15 @@ for await (const event of session.send("Continue the task.")) {
     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");
+  } else if (event.isTurnError()) {
+    console.error("turn error");
   }
 }
 ```
 
-The full method set: `isRunStarted()`, `isRunFinished()`, `isRunError()`,
-`isRunTerminal()`, `isTextMessage()`, `isToolCallStart()`, `isToolCallResult()`,
-`isCustom()`, `isLog()`, `isEventChannel()`, `isRunSettled()`, and
+The full method set: `isTurnStarted()`, `isTurnFinished()`, `isTurnError()`,
+`isTurnTerminal()`, `isTextMessage()`, `isToolCallStart()`, `isToolCallResult()`,
+`isCustom()`, `isLog()`, `isEventChannel()`, `isSessionSettled()`, 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