@aexhq/sdk 0.35.0 → 0.37.0

package/docs/events.md

@@ -53,9 +53,9 @@ for the string:
 const lastText = (await session.messages().last())?.text;
 ```
 
-`decodeAssistantText`, `textOf`, and `summarizeRunTrace` remain exported as the
-power-user escape hatch over a raw `RunEvent` list, but "get the last message"
-is now `await session.messages().last()`.
+Prefer `session.messages().list()` or the collected `result.messages` /
+`result.text` fields for assistant text. Low-level event helpers remain exported
+for callers that build custom collectors.
 
 The CLI mirrors the same surface:
 
@@ -110,22 +110,32 @@ collected session turn. The returned `runId` is the session id.
 
 ## Terminal events vs. the run record
 
-A session turn emits a terminal **event** — `RUN_FINISHED`
-(success) or `RUN_ERROR` — when
-the agent's stream ends. This is an AG-UI *render-complete* signal: the runner
-emits it **before** aex commits the authoritative session record, so an
-`aex.sessions.get(id)` issued the instant you observe `RUN_FINISHED` can still
-read a non-parked status for a moment. Treat the terminal event as the
-lowest-latency "stop the spinner" signal — **not** a read-consistency barrier.
-
-Two facts make this easy to work with:
-
-- **Outputs are already durable at the terminal event.** The runner uploads every
-  output before it emits the terminal event, and `session.outputs().list()` / downloads
-  read object storage directly — so the moment you see `RUN_FINISHED` the outputs
-  are complete and readable.
-- **The session _record_ settles a beat later.** To read the authoritative status
-  consistently, don't key off the terminal event — use one of:
+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*
+  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"
+  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**
+  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".
+
+To read the authoritative status consistently, use one of:
 
 ```ts
 // Session record path: send a turn, then wait for the session to park.
@@ -135,18 +145,21 @@ const record = await session.wait(); // the parked session record
 ```
 
 ```ts
-// Live events AND a settle-consistent end: the iterator keeps reading past
-// RUN_FINISHED until the post-mirror barrier, so the record is terminal when it ends.
+// Live events AND a settle-consistent end: the iterator ends on the settle
+// barrier OR the aex.session.* park terminal, whichever the plane emits —
+// so when it ends, the session record is already parked/terminal.
 for await (const event of session.events().streamEnvelopes({ settleConsistent: true })) {
   // render events live…
 }
-const settled = await aex.sessions.get(session.id); // guaranteed terminal here
+const settled = await aex.sessions.get(session.id); // parked/terminal here
 ```
 
-Under the hood the coordinator broadcasts one `aex.run.settled` CUSTOM event as a
-run's last stream event, immediately after the durable record commits.
-`settleConsistent` ends the stream on it; on a raw stream, detect it with
-`isRunSettled(event)`.
+`settleConsistent: true` makes the iterator end exactly when `isRunSettled(event)`
+first fires; on a raw stream, apply `isRunSettled(event)` 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
+stream ends.
 
 ## Temporary event archive links
 
@@ -162,7 +175,7 @@ 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 the provider key, MCP credentials, or proxy bearer that were supplied when the session was opened.
+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.
 
 ## Typed helpers
 
@@ -180,8 +193,7 @@ import {
   isToolCallResult,
   isCustom,
   isLog,
-  isEventChannel,
-  textOf
+  isEventChannel
 } from "@aexhq/sdk";
 ```
 
@@ -191,6 +203,6 @@ All guards test the `type` discriminant at runtime. `isTextMessage`,
 `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. `textOf(events)` returns
-the run's final assistant text concatenated from the `TEXT_MESSAGE_CONTENT`
-blocks.
+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.

package/docs/limits-and-quotas.md

@@ -5,10 +5,9 @@ title: Limits & quotas
 # Limits & quotas
 
 These are the hard ceilings and caps that bound a run, a workspace, and a single
-request. Every value is mirrored from a single source-of-truth constant; the
-constant file is authoritative and this page is generated documentation, not a
-second source of truth. If a value here ever disagrees with that constant,
-the constant wins.
+request. 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.
 
 Each row is named by its source-of-truth constant. For the values that apply
 when you omit an option, see
@@ -26,7 +25,7 @@ And whether you can **raise** it: per-run option, per-plan, or no.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Maximum run timeout | 6 hours | aex policy | Per plan (billing-driven) | `RUN_MAX_TIMEOUT_MS` |
+| Maximum run timeout | 8 hours (also the default when `timeout` is omitted) | aex policy | Per plan (billing-driven) | `RUN_MAX_TIMEOUT_MS` |
 | Minimum run timeout | 1 minute | aex policy | No (floor) | `RUN_MIN_TIMEOUT_MS` |
 | Per-call exec timeout (default) | 30 minutes | aex policy | Per-call via the tool call's `timeoutMs` | `RUN_DEFAULT_EXEC_TIMEOUT_MS` |
 | MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
@@ -43,8 +42,8 @@ silently lost.
 | --- | --- | --- | --- | --- |
 | Capture wall-clock budget | 1 hour | aex policy | No (hard ceiling) | `RUN_CAPTURE_DEFAULT_TIMEOUT_MS` |
 | Max files captured | 50,000 | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_FILES` |
-| Max bytes per captured file | 1 TB | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_FILE_BYTES` |
-| Max total captured bytes | 1 TB | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_TOTAL_BYTES` |
+| Max bytes per captured file | 500 GB (decimal) | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_FILE_BYTES` |
+| Max total captured bytes | 500 GB (decimal) | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_TOTAL_BYTES` |
 
 ### Tool output caps (per run)
 
@@ -74,9 +73,11 @@ silently lost.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Workspace storage cap | 50 GiB (admins uncapped — not a customer entitlement) | Workspace default | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES` | `WORKSPACE_DEFAULT_STORAGE_CAP_BYTES` |
-| Max concurrent runs per workspace | Advisory — there is no hard per-workspace concurrent-run cap constant; concurrency is bounded by plan, the subagent child-run cap, and provider/platform throughput rather than a fixed number. | aex policy | n/a | — |
-| Skill bundle max compressed size (`.zip`) | 100 GB | Workspace default | Per-workspace (plan/env) | `WORKSPACE_SKILL_BUNDLE_MAX_COMPRESSED_BYTES` |
+| Workspace storage cap | 500 GB (decimal; admins uncapped — not a customer entitlement) | Workspace default | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES` | `WORKSPACE_DEFAULT_STORAGE_CAP_BYTES` |
+| Max concurrent runs per workspace | **50** live (non-terminal) root runs by default; hard platform ceiling **200**. One more submit past the cap fails with `429 workspace_concurrency_exceeded` (see [Errors](errors.md)). Subagent children are governed separately by the per-lineage caps below. | Workspace default | Per-workspace override (contact support), clamped to the 200 ceiling | `WORKSPACE_DEFAULT_MAX_CONCURRENT_RUNS` / `WORKSPACE_MAX_CONCURRENT_RUNS_CEILING` |
+| Monthly workspace spend cap | **$250** per rolling UTC calendar month by default; `0` = unlimited. A submit past the cap fails with `402 workspace_spend_cap_exceeded` (see [Errors](errors.md)). | Workspace default | Per-workspace override (contact support) | `WORKSPACE_DEFAULT_SPEND_CAP_USD` |
+| Skill bundle max compressed size (`.zip`) | 10 GiB (enforced at upload by the SDK and re-enforced server-side) | aex policy | No (hard ceiling) | `SKILL_BUNDLE_LIMITS.maxCompressedBytes` |
+| Skill bundle max decompressed size (sum of uncompressed file sizes) | 50 MB | aex policy | No (hard ceiling) | `SKILL_BUNDLE_LIMITS.maxDecompressedBytes` |
 | Skill bundle max file entries | 1,000 | Workspace default | Per-workspace (plan/env) | `WORKSPACE_SKILL_BUNDLE_MAX_FILES` |
 | Skill bundle max directory depth (`a/b/c/d` = 4) | 16 | Workspace default | Per-workspace (plan/env) | `WORKSPACE_SKILL_BUNDLE_MAX_DEPTH` |
 | Skill bundle max entry path length | 512 characters | Workspace default | No (hard ceiling) | `WORKSPACE_SKILL_BUNDLE_MAX_PATH_LENGTH` |
@@ -84,24 +85,36 @@ silently lost.
 
 ### Rate limits (per workspace, per minute)
 
-Default values; each is overridable per-plane via the matching
-`AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var.
+Run submission has its own platform-enforced velocity cap: **120 submits per
+minute** per workspace by default (`0` = disabled). Past it, `POST /runs` fails
+with `429 workspace_submit_rate_exceeded` (see [Errors](errors.md)). It is
+overridable per-plane via `AEX_WORKSPACE_SUBMIT_RATE_PER_MIN` or per-workspace
+via support.
+
+The dashboard mutation actions below default as listed; each is overridable
+per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var.
 
 | Action | Default per minute | Source | Constant |
 | --- | --- | --- | --- |
-| Run submit | 60 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | Run cancel | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | Run delete | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | Signed output link | 120 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | API token create | 10 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | API token delete | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 
-## Request scope (proxy and egress)
+### Introspecting your effective caps
+
+`aex.whoami()` (CLI: `aex whoami`) returns a `limits` object carrying the
+workspace's *effective* values for the caps above — `maxConcurrentRuns`,
+`submitRatePerMinute`, `spendCapUsd`, plus the live `monthSpendUsd`,
+`balanceUsd`, `balanceGraceFloorUsd`, and `paymentMethodStatus` — resolved by
+the same code the admission gates use, so you can anticipate a `429`/`402`
+before submitting. See [Authentication](authentication.md) and
+[Errors](errors.md).
+
+## Request Scope
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Proxy request body | 10 MiB | aex policy | Per-endpoint via `maxRequestBytes` | `REQUEST_PROXY_DEFAULT_MAX_REQUEST_BYTES` |
-| Proxy response body | `0` = unlimited (streamed unbuffered) | aex policy | Per-endpoint via `maxResponseBytes` | `REQUEST_PROXY_DEFAULT_MAX_RESPONSE_BYTES` |
-| Proxy upstream timeout | 5 minutes | aex policy | Per-endpoint via `timeoutMs` | `REQUEST_PROXY_DEFAULT_TIMEOUT_MS` |
 | Signed output URL TTL | 300 seconds | aex policy | Per-call via `expiresSeconds` | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
 | Event-stream connection ticket TTL | 60 seconds | aex policy | Per-mint via `ttlMs` | `REQUEST_TICKET_DEFAULT_TTL_MS` |

package/docs/limits.md

@@ -16,25 +16,21 @@ For the current provider/model set, see the generated
 
 | Area | Default |
 | --- | --- |
-| Workspace storage | 50 GiB per workspace for captured outputs and workspace artifacts. aex-maintainer admin workspaces may be unlimited for internal dogfooding; this is not a customer entitlement. |
-| Proxy request body | 10 MiB per proxy endpoint unless the endpoint declares a different `maxRequestBytes`. |
-| Proxy timeout | 5 minutes per proxy endpoint unless the endpoint declares a different `timeoutMs`. |
-| Proxy telemetry | Proxy calls emit report-only usage telemetry for call count, failed calls, request bytes, response bytes when known, and duration. Public proxy pricing is not shipped unless documented later. |
+| Workspace storage | 500 GB per workspace for captured outputs and workspace artifacts. aex-maintainer admin workspaces may be unlimited for internal dogfooding; this is not a customer entitlement. |
 
 ## Product Boundaries
 
 | Area | Boundary |
 | --- | --- |
-| Runtime | New submissions run on the managed runtime. There is no public runtime selector. |
+| Runtime | New submissions run on the managed runtime. The `runtime` option selects a managed machine-size preset (`Sizes.*`); there is no alternative runtime backend. |
 | Provider policy | Provider retention, training exclusion, HIPAA/BAA, data residency, abuse policy, and pricing belong to the selected provider account, endpoint, and contract. |
-| Secrets | Provider keys, MCP credentials, proxy auth, and env secrets are caller-owned. aex excludes secret values from idempotency and uses the explicit secret surfaces described in [Secrets](secrets.md). |
+| Secrets | Provider keys, MCP credentials, and env secrets are caller-owned. aex excludes secret values from idempotency and uses the explicit secret surfaces described in [Secrets](secrets.md). |
 | MCP servers | Remote MCP servers are customer-trusted systems. aex validates declarations and routes credentials; it does not make an untrusted MCP server safe. |
-| Proxy endpoints | The proxy enforces declared host/path/method/auth policy for calls routed through it. Upstream side effects and data handling remain with the upstream service and customer. |
 | Outputs | Captured outputs, events, and metadata are stored under the run record and downloaded through auth-gated routes. Output content is customer content. |
 | Human review | Runs execute after submission. Cancellation is available, but aex does not pause a run for platform-mediated approval or interactive clarification. |
 | Sessions | The durable product primitive is the session/run record. Sessions can be resumed by id and auto-suspend after the configured idle window; persistent named agent profiles and saved agent definitions are out of scope. |
 | Deployment | The supported product is the hosted aex service plus the SDK and CLI. Alternate `baseUrl` values are for local, staging, or hosted aex API planes, not a self-host product promise. |
-| Cost | BYOK provider-token charges accrue to the customer's provider account. aex records report-only telemetry for runtime, storage, and proxy usage; free trials, billing-grade invoices, and public pricing documents are not shipped unless documented later. |
+| Cost | BYOK provider-token charges accrue to the customer's provider account. aex records report-only telemetry for runtime and storage usage; free trials, billing-grade invoices, and public pricing documents are not shipped unless documented later. |
 
 ## Provider Policy Links
 

package/docs/mcp.md

@@ -20,19 +20,18 @@ Use allowlists for sensitive servers whenever possible.
 ## Large-payload responses
 
 aex is a session dispatcher, not an MCP runtime. We intentionally do
-**not** interpose on the transport between Claude and an upstream MCP
+**not** interpose on the transport between the model and an upstream MCP
 server, so we cannot elide MCP responses or write them to the session
 filesystem on the user's behalf. Anything an MCP tool returns lands
 directly in the model's context.
 
-For ingestion-style tools that return large JSON blobs (search results,
-catalogue dumps, bulk reads), use the **CLI-as-skill + managed proxy**
-pattern instead of MCP:
+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.
-2. Route every upstream HTTPS call through a per-run `ProxyEndpoint`
-   (audit, byte caps, budget enforcement).
+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
    `outputs.allowedDirs` only when you want to narrow capture to specific roots.

package/docs/networking.md

@@ -4,45 +4,64 @@ title: Networking
 
 # Networking
 
-A run executes your agent's code in a sandbox that has **no unmediated route to
-the internet**. Every outbound connection — whether it comes from the model, a
-built-in tool, or a `curl` your code runs in the shell — passes through the
-platform's egress boundary, which enforces the run's networking policy and a
-fixed SSRF deny-list (loopback, link-local, cloud-metadata, and other private
-ranges are always blocked, including hostnames that resolve to those ranges).
-
-**Networking is open by default.** A run that does not set
-`environment.networking` may reach any public host — still subject to the SSRF
-deny-list above — with no allowlist required. You use the `environment.networking`
-field to *narrow* that surface when you want a tighter, auditable egress posture.
-Code cannot widen the policy from inside the container: the boundary is the
-platform's, not the agent's.
+A run executes your agent's code in a sandbox with **no direct route to the
+internet**. Outbound traffic is governed by **two layers**:
+
+1. **The per-run policy (`environment.networking`)** — enforced by the agent
+   runtime *inside the run*. It applies to the standard proxy path every normal
+   HTTP client uses (see below) and can only *narrow* what the run may reach.
+2. **The platform ceiling** — a fixed, platform-managed egress boundary every
+   connection ultimately traverses. It allows the hosts aex itself manages
+   (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.
+
+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
+the platform proxy layer. A subprocess that deliberately bypasses the standard
+proxy environment (a raw socket / raw CONNECT) is bounded by the **platform
+ceiling** rather than by the per-run list. Per-run enforcement at the platform
+proxy layer is planned; until it ships, treat `allowedHosts` as a strong
+default-path control and an auditable statement of intent, not a hard isolation
+boundary against adversarial code inside the run.
+
+**Default posture.** A run that does not set `environment.networking` runs in
+`open` mode: its own code may reach anything within the platform ceiling with
+no allowlist required. Use `environment.networking` to *narrow* that surface
+when you want a tighter, auditable egress posture. Code cannot widen the
+ceiling from inside the container.
 
 ## Paths that always work
 
-These reach the network over managed paths and are **not** subject to
+These reach the network over managed platform paths and are **not** subject to
 `environment.networking`, so you never list their hosts:
 
 - The model / provider call for the run (and its subagents).
-- The built-in `web_search` and `web_fetch` tools (still SSRF-guarded).
-- Any remote MCP servers you declare in `mcpServers` — see [MCP](mcp.md).
-- Any `proxyEndpoints` you declare — see [Credentials](credentials.md).
+- The built-in `web_search` and `web_fetch` tools. They run over a managed,
+  SSRF-guarded server-side path, which is why they can reach arbitrary public
+  URLs even though your own code is bounded by the ceiling.
+- Remote MCP servers you declare in `mcpServers` — MCP traffic rides a managed
+  path; see [MCP](mcp.md).
 - The package registries for any `environment.packages` you declare (pip → PyPI,
   apt → the distribution mirrors). Declaring a package implicitly allows the
   registry it installs from.
 
-`environment.networking` governs the **other** case: arbitrary outbound that
-your own code makes to a host the platform doesn't already manage — a `curl` in
-the `bash` tool, a `requests`/`urllib` call in Python, a `fetch` in
-`code_execution`, or a third-party SDK.
+`environment.networking` governs the **other** case: outbound that your own
+code makes — a `curl` in the `bash` tool, a `requests`/`urllib` call in Python,
+a `fetch` in `code_execution`, or a third-party SDK.
 
 ## Restrict a run to an allowlist
 
 Set `mode: "limited"` and list exactly the hosts your code is allowed to reach.
-Anything not on the list (and not one of the always-allowed paths above) is
-blocked, and the call fails. The platform automatically appends the
-infrastructure hosts aex itself needs, so the model and tool paths keep working
-without you listing them.
+The run's runtime enforces the list on the standard proxy path: a connection to
+a host that is neither on the list nor one of the always-allowed paths above is
+refused before it leaves the run. Package-registry hosts implied by
+`environment.packages` are appended automatically so installs keep working.
+
+Note that `allowedHosts` narrows *within* the platform ceiling — listing a host
+does not by itself make it reachable if the platform ceiling does not carry it.
+If your run needs a host the ceiling blocks, contact support.
 
 ### TypeScript
 
@@ -70,26 +89,17 @@ non-default port when you need one (`api.example.com:8443`); a bare host name
 covers HTTPS on 443. Matching is exact per host — it is not a wildcard or suffix
 match, so list each host you need.
 
-To validate your allowlist before submitting, `buildPlatformAllowedHosts` returns
-the host set the platform will enforce given a base URL plus your extra hosts:
-
-```ts
-import { buildPlatformAllowedHosts } from "@aexhq/sdk";
-
-const allowedHosts = buildPlatformAllowedHosts({
-  baseUrl: "https://api.aex.dev",
-  extraHosts: ["api.example.com"]
-});
-```
+Keep the allowlist in your session options so the submitted network policy is
+visible at the same call site as the code that needs it.
 
 ## Open mode
 
 `open` is the default: a run that omits `environment.networking` already runs in
-open mode. Set `mode: "open"` explicitly when you want to be unambiguous, or when
-a run needs to reach hosts you can't enumerate ahead of time. The run may then
-reach any public host, still subject to the SSRF deny-list. Prefer `limited`
-whenever you can name the hosts — it gives the run a stable, auditable, least-
-privilege egress surface (it is the tighter posture, not the default).
+open mode. Set `mode: "open"` explicitly when you want to be unambiguous. Open
+mode applies no per-run allowlist — the run's own code may reach anything the
+platform ceiling allows, still subject to the SSRF deny-list. Prefer `limited`
+whenever you can name the hosts — it gives the run a stable, auditable,
+least-privilege egress surface (it is the tighter posture, not the default).
 
 ```ts
 await aex.run({
@@ -100,6 +110,9 @@ await aex.run({
 });
 ```
 
+(Web research like the example above flows through the managed `web_search` /
+`web_fetch` path, which is not ceiling-bounded.)
+
 ## Transparent for normal HTTP clients
 
 You write ordinary code — there is no per-request proxy configuration and no
@@ -111,7 +124,7 @@ that honors it — `curl`, Python `requests` / `urllib`, `pip`, `npm`, Node
 ```bash
 # In the agent's shell, against a limited run that allows api.example.com:
 curl -sS https://api.example.com/v1/status   # works
-curl -sS https://other-host.example          # blocked (not in allowlist)
+curl -sS https://other-host.example          # refused (not in allowlist)
 ```
 
 You also do **not** need to install any certificate. The platform manages the
@@ -120,22 +133,25 @@ your client succeeds without extra setup.
 
 ## Limitations and gotchas
 
-- **Enforcement is at the platform boundary, not in your code.** A tool can't
-  bypass the policy by ignoring proxy settings or opening a raw socket — the
-  sandbox has no other route out, so a disallowed host simply fails. This is the
-  intended fail-closed behavior.
+- **The per-run policy is enforced by the run's runtime, not at the platform
+  proxy.** Clients that honor the standard proxy environment (almost all HTTP
+  tooling) are held to the `allowedHosts` list. A subprocess that deliberately
+  ignores the proxy environment and opens a raw connection is **not** held to
+  the per-run list — it is bounded by the platform ceiling (the aex-managed
+  provider/tool/registry host set) and the SSRF deny-list instead. Per-run
+  enforcement at the platform proxy layer is planned.
 - **A client that hard-bypasses the standard environment may fail to connect.**
-  This is rare — almost all HTTP tooling honors `HTTP_PROXY` / `HTTPS_PROXY` and
-  the system trust store. But a client that is explicitly told to ignore the
-  proxy environment, pins or replaces its certificate trust store, or speaks a
-  non-HTTP protocol over a raw socket can hit a wall even for an allowed host.
-  The fix is to let the client use the standard proxy and certificate
-  environment the runtime provides (most libraries do by default), rather than
-  overriding it.
+  A client that ignores the proxy environment, pins or replaces its certificate
+  trust store, or speaks a non-HTTP protocol over a raw socket can hit a wall
+  even for a host you allowed. The fix is to let the client use the standard
+  proxy and certificate environment the runtime provides (most libraries do by
+  default), rather than overriding it.
 - **`allowedHosts` only applies in `limited` mode.** It is ignored in `open`
-  mode, where the SSRF deny-list is the only gate.
-
-For routing credentialed HTTP calls through the managed proxy without putting the
-secret in the container, use proxy endpoints — see
-[Credentials](credentials.md). For remote tool servers, see [MCP](mcp.md). For
-the full set of run-config fields, see [Run configuration](run-config.md).
+  mode, where the platform ceiling and the SSRF deny-list are the gates.
+- **`allowedHosts` cannot exceed the platform ceiling.** It narrows; it never
+  widens. A listed host outside the ceiling still fails.
+
+For credentialed HTTP calls, pass the credential as an `environment.secrets`
+entry and let your code use its normal HTTP client. For remote tool servers, see
+[MCP](mcp.md). For the full set of run-config fields, see
+[Run configuration](run-config.md).

package/docs/outputs.md

@@ -100,10 +100,6 @@ if (truncated) {
 
 Check `truncated` before treating `text` as complete. Pass `options.grep` (a substring or `RegExp`) to keep only matching lines of the capped text. The returned `output` is the matched `Output` record, and `totalBytes` is the file's full size when the server reports it.
 
-### Chatting over a workspace's outputs
-
-`createDataTools(client)` packages the read surface (`sessions.list` + `sessions.outputs(id).list` + `sessions.outputs(id).read`) as a vendor-neutral LLM tool set (`{ tools, instructions, execute }`) so you can build a search-then-fetch chat over your sessions and their outputs in a few lines on top of the public SDK. The `tools` are plain JSON-Schema definitions (the shape every major LLM tool API accepts); `execute(name, input)` dispatches a tool call against the workspace-scoped client. See the runnable `examples/data-chat/` example.
-
 ## Finding outputs
 
 `session.outputs().list(query?)` can filter the captured output list client-side. Use `session.outputs().find(query)` when you want discovery to be explicit, or `session.outputs().findOne(query)` when exactly one file is expected:
@@ -167,9 +163,10 @@ const stream = response.body;
 
 | Run state | Behaviour |
 | --- | --- |
-| `pending` / `queued` / `provisioning` | `metadata/run.json` reflects the early state; `events/` and `outputs/` are typically empty. |
-| `provider_running`, mid-session / `cleaning_up` | Whatever events + outputs have been captured so far. Call again after terminal for the complete set. |
-| `succeeded` / `failed` / `cancelled` / `terminated` | The complete typed event archive + all captured outputs. |
+| `queued` / `claiming` / `provisioning` | `metadata/run.json` reflects the early state; `events/` and `outputs/` are typically empty. |
+| `provider_running`, mid-session / `capturing_outputs` / `cleaning_up` | Whatever events + outputs have been captured so far. Call again after the session parks for the complete set. |
+| `idle` / `suspended` (parked between turns) | The complete archive for every turn sent so far; a later turn appends to it. |
+| `succeeded` / `failed` / `timed_out` / `cancelled` | The complete typed event archive + all captured outputs. |
 
 ## `outputs.allowedDirs` — override capture roots
 

package/docs/public-surface.json

@@ -2,12 +2,12 @@
   "brand": "aex",
   "productName": "Agent Executor",
   "oneLine": "aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.",
-  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, proxy endpoints, and subagents across the managed runtime.",
+  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, secrets, networking controls, and subagents across the managed runtime.",
   "alpha": {
     "label": "Alpha testing",
     "description": "Access is limited to invited testers while we harden the hosted runtime, dashboard, and SDK workflows."
   },
-  "installCommand": "bun add @aexhq/sdk",
+  "installCommand": "npm i @aexhq/sdk",
   "examples": {
     "typescriptLines": [
       "import { Aex, Models, Sizes } from \"@aexhq/sdk\";",
@@ -61,7 +61,7 @@
       "slug": "agent-composition",
       "href": "/docs/features/#agent-composition",
       "title": "Agent composition",
-      "description": "Skills, files, AGENTS.md, remote MCP servers, proxy endpoints, environment variables, packages, and networking controls."
+      "description": "Skills, files, AGENTS.md, remote MCP servers, environment variables, packages, secrets, and networking controls."
     },
     {
       "slug": "subagents",
@@ -79,7 +79,7 @@
       "slug": "typed-control-surface",
       "href": "/docs/features/#typed-control-surface",
       "title": "Typed control surface",
-      "description": "Strongly typed SDK inputs, CLI parity, BYOK secrets, scoped proxy auth, redaction, and output modes."
+      "description": "Strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes."
     }
   ]
 }

package/docs/quickstart.md

@@ -7,16 +7,18 @@ title: Quickstart
 ## 1. Install
 
 ```bash
-bun add @aexhq/sdk
+npm i @aexhq/sdk
 ```
 
 This installs the TypeScript SDK exports and the bundled `aex` CLI.
 
 ## 2. Set credentials
 
-In the dashboard, create a quickstart SDK token with `runs:read`, `runs:write`,
-and `outputs:read`. The examples also need your BYOK provider key for the model
-you choose. For the Claude examples below:
+aex is currently in **invite-only beta**: workspaces and API tokens 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:
 
 ```bash
 export AEX_API_TOKEN="<your-aex-token>"
@@ -28,7 +30,7 @@ export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
 ```ts
 import { Aex, Models, Sizes } from "@aexhq/sdk";
 
-const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
+const aex = new Aex(process.env.AEX_API_TOKEN!);
 
 const session = await aex.openSession({
   model: Models.CLAUDE_HAIKU_4_5,
@@ -83,11 +85,8 @@ for await (const event of turn) {
 }
 await turn.done();
 
-// Reads/streams/downloads are grouped into accessor sub-resources:
-// session.messages() / events() / outputs() / webhooks(). Grab the last
-// assistant message (an AssistantTextEntry; use ?.text for the string).
-const lastText = (await session.messages().last())?.text;
-console.log(lastText);
+const messages = await session.messages().list();
+console.log(messages.at(-1)?.text);
 
 // Poll the record until the session parks (idle / suspended / error).
 const record = await session.wait();
@@ -110,8 +109,8 @@ aex run \
 
 ## Add capabilities
 
-- Add files, skills, AGENTS.md, MCP servers, proxy endpoints, packages, and networking controls with [Composition](concepts/composition.md).
-- Inspect runtime tools with [Agent tools](concepts/agent-tools.md).
-- Use parent/child run delegation from the [Features](https://aex.dev/docs/features/#subagents) page.
+- Add files, skills, AGENTS.md, MCP servers, packages, and networking controls with [Composition](concepts/composition.md).
+- Delegate bounded sub-tasks to child runs with [Subagents](concepts/subagents.md).
+- Get notified when a run finishes with [Webhooks](webhooks.md).
 - Narrow output capture or download individual files with [Outputs](outputs.md).
 - Check supported providers and models in the [provider/runtime capability matrix](provider-runtime-capabilities.md).

package/docs/run-config.md

@@ -13,13 +13,16 @@ Allowed fields:
 - `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.
-- `proxyEndpoints` - array of `ProxyEndpoint` instances; endpoint-level `retry` is allowed here and remains declaration-based.
 - `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)).
 
-`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 run in-process; there is no `limits` / `parentRunId` option.
+`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.
 
-Secrets never live in run config. Pass provider keys through the top-level `apiKeys` map (and run secrets through `environment.secrets`) in the SDK, or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`) in the CLI. See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md) for the proxy endpoint policy/auth split and retry fields.
+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
 
@@ -52,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`, `--proxy-endpoint`, `--proxy-auth`, `--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.