@aexhq/sdk 0.29.0 → 0.31.0

package/docs/limits-and-quotas.md

@@ -7,12 +7,11 @@ title: 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 the linked constant,
+second source of truth. If a value here ever disagrees with that constant,
 the constant wins.
 
-Source of truth:
-[`packages/shared/src/limits.ts`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts).
-For the values that apply when you omit an option, see
+Each row is named by its source-of-truth constant. For the values that apply
+when you omit an option, see
 [Defaults](defaults.md). For product/policy boundaries (what aex does and does
 not promise), see [Limits](limits.md).
 
@@ -27,12 +26,13 @@ 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`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L163) |
-| Minimum run timeout | 1 minute | aex policy | No (floor) | [`RUN_MIN_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L172) |
-| Per-call exec timeout (default) | 30 minutes | aex policy | Per-call via the tool call's `timeoutMs` | [`RUN_DEFAULT_EXEC_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L202) |
-| Post-hook timeout (default) | 60 minutes | aex policy | Per-run via the hook's `timeoutMs` | [`RUN_DEFAULT_POST_HOOK_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L234) |
-| MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | [`RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L255) |
-| MCP call timeout (default) | 30 minutes | aex policy | Per-port via `callTimeoutMs` | [`RUN_DEFAULT_MCP_CALL_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L265) |
+| Maximum run timeout | 6 hours | 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` |
+| Post-hook timeout (default) | 60 minutes | aex policy | Per-run via the hook's `timeoutMs` | `RUN_DEFAULT_POST_HOOK_TIMEOUT_MS` |
+| 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-run spend cap | None by default; when set, the run is stopped once its spend would exceed the cap | aex policy | Per-run via `options.limits.maxSpendUsd` (a positive USD amount) | — |
 
 ### Output capture (per run)
 
@@ -42,46 +42,46 @@ silently lost.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Capture wall-clock budget | 1 hour | aex policy | No (hard ceiling) | [`RUN_CAPTURE_DEFAULT_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L288) |
-| Max files captured | 50,000 | aex policy | No (hard ceiling) | [`RUN_CAPTURE_MAX_FILES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L297) |
-| Max bytes per captured file | 1 TB | aex policy | No (hard ceiling) | [`RUN_CAPTURE_MAX_FILE_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L307) |
-| Max total captured bytes | 1 TB | aex policy | No (hard ceiling) | [`RUN_CAPTURE_MAX_TOTAL_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L315) |
+| 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` |
 
 ### Tool output caps (per run)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| `web_fetch` returned body | 500 KB (UTF-8) | aex policy | Per-call via `max_bytes` | [`REQUEST_WEB_FETCH_DEFAULT_MAX_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L528) |
-| `bash_output` per-read body | 1 MB (UTF-8) | aex policy | No (hard ceiling) | [`RUN_BASH_BG_OUTPUT_MAX_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L327) |
-| `grep` max file size (larger files skipped — use `bash grep`) | 25 MB | aex policy | No (hard ceiling) | [`RUN_TOOL_GREP_MAX_FILE_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L341) |
-| `head`/`tail` max file size (larger files rejected — use `bash head`/`tail`) | 100 MB | aex policy | No (hard ceiling) | [`RUN_TOOL_HEAD_TAIL_MAX_FILE_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L352) |
-| `grep`/`glob` files visited per recursive walk (then truncates with a notice) | 100,000 | aex policy | No (hard ceiling) | [`RUN_TOOL_WALK_MAX_FILES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L364) |
+| `web_fetch` returned body | 500 KB (UTF-8) | aex policy | Per-call via `max_bytes` | `REQUEST_WEB_FETCH_DEFAULT_MAX_BYTES` |
+| `bash_output` per-read body | 1 MB (UTF-8) | aex policy | No (hard ceiling) | `RUN_BASH_BG_OUTPUT_MAX_BYTES` |
+| `grep` max file size (larger files skipped — use `bash grep`) | 25 MB | aex policy | No (hard ceiling) | `RUN_TOOL_GREP_MAX_FILE_BYTES` |
+| `head`/`tail` max file size (larger files rejected — use `bash head`/`tail`) | 100 MB | aex policy | No (hard ceiling) | `RUN_TOOL_HEAD_TAIL_MAX_FILE_BYTES` |
+| `grep`/`glob` files visited per recursive walk (then truncates with a notice) | 100,000 | aex policy | No (hard ceiling) | `RUN_TOOL_WALK_MAX_FILES` |
 
 ### Subagents (per run lineage)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Max subagent depth (public submit / `subagent` tool) | 5 (a depth-5 lineage may not spawn deeper) | aex policy | Per-run via `options.limits.maxSubagentDepth` (clamped to this hard ceiling) | [`RUN_MAX_PUBLIC_SUBAGENT_DEPTH`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L415) |
-| Concurrent child runs per lineage root | 1000 live (non-terminal); hard ceiling 4096 | aex policy | Per-run via `options.limits.maxConcurrentChildRuns` (clamped to the 4096 ceiling) | [`RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L429) |
+| Max subagent depth (public submit / `subagent` tool) | 5 (a depth-5 lineage may not spawn deeper) | aex policy | Per-run via `options.limits.maxSubagentDepth` (clamped to this hard ceiling) | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
+| Concurrent child runs per lineage root | 1000 live (non-terminal); hard ceiling 4096 | aex policy | Per-run via `options.limits.maxConcurrentChildRuns` (clamped to the 4096 ceiling) | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
 
 ### Retention (per run)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Per-run metadata KV record TTL | 24 hours | aex policy | No (hard ceiling) | [`RUN_KV_RECORD_TTL_SECONDS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L462) |
-| Per-run secret-envelope KV TTL | 24 hours | aex policy | No (hard ceiling) | [`RUN_KV_SECRET_TTL_SECONDS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L474) |
+| 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` |
 
 ## Workspace scope
 
 | 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`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L52) |
+| 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`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L63) |
-| Skill bundle max file entries | 1,000 | Workspace default | Per-workspace (plan/env) | [`WORKSPACE_SKILL_BUNDLE_MAX_FILES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L72) |
-| Skill bundle max directory depth (`a/b/c/d` = 4) | 16 | Workspace default | Per-workspace (plan/env) | [`WORKSPACE_SKILL_BUNDLE_MAX_DEPTH`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L81) |
-| Skill bundle max entry path length | 512 characters | Workspace default | No (hard ceiling) | [`WORKSPACE_SKILL_BUNDLE_MAX_PATH_LENGTH`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L89) |
-| `File.mountPath` max length | 512 characters | Workspace default | No (hard ceiling) | [`WORKSPACE_MOUNT_PATH_MAX_LENGTH`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L99) |
+| Skill bundle max compressed size (`.zip`) | 100 GB | Workspace default | Per-workspace (plan/env) | `WORKSPACE_SKILL_BUNDLE_MAX_COMPRESSED_BYTES` |
+| 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` |
+| `File.mountPath` max length | 512 characters | Workspace default | No (hard ceiling) | `WORKSPACE_MOUNT_PATH_MAX_LENGTH` |
 
 ### Rate limits (per workspace, per minute)
 
@@ -90,19 +90,19 @@ Default values; each is overridable per-plane via the matching
 
 | Action | Default per minute | Source | Constant |
 | --- | --- | --- | --- |
-| Run submit | 60 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| Run cancel | 30 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| Run delete | 30 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| Signed output link | 120 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| API token create | 10 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| API token delete | 30 | Workspace default | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
+| 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)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Proxy request body | 10 MiB | aex policy | Per-endpoint via `maxRequestBytes` | [`REQUEST_PROXY_DEFAULT_MAX_REQUEST_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L499) |
-| Proxy response body | `0` = unlimited (streamed unbuffered) | aex policy | Per-endpoint via `maxResponseBytes` | [`REQUEST_PROXY_DEFAULT_MAX_RESPONSE_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L509) |
-| Proxy upstream timeout | 5 minutes | aex policy | Per-endpoint via `timeoutMs` | [`REQUEST_PROXY_DEFAULT_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L519) |
-| Signed output URL TTL | 300 seconds | aex policy | Per-call via `expiresSeconds` | [`REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L539) |
-| Event-stream connection ticket TTL | 60 seconds | aex policy | Per-mint via `ttlMs` | [`REQUEST_TICKET_DEFAULT_TTL_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L549) |
+| 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

@@ -24,7 +24,7 @@ For the current provider/model set, see the generated
 
 | Area | Boundary |
 | --- | --- |
-| Runtime | New submissions run on the managed runtime. `runtime: "native"` is rejected. |
+| Runtime | New submissions run on the managed runtime. There is no public runtime selector. |
 | 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). |
 | MCP servers | Remote MCP servers are customer-trusted systems. aex validates declarations and routes credentials; it does not make an untrusted MCP server safe. |

package/docs/networking.md

@@ -0,0 +1,141 @@
+---
+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.
+
+## Paths that always work
+
+These reach the network over managed 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 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.
+
+## 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.
+
+### TypeScript
+
+```ts
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+
+await aex.submit({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Fetch the public status page and summarize it.",
+  environment: {
+    networking: {
+      mode: "limited",
+      allowedHosts: ["api.example.com", "status.example.com"]
+    }
+  },
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+`allowedHosts` entries are host names (lowercased), e.g. `api.example.com`. Add a
+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"]
+});
+```
+
+## 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).
+
+```ts
+await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Research the topic across the open web.",
+  environment: { networking: { mode: "open" } },
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+## Transparent for normal HTTP clients
+
+You write ordinary code — there is no per-request proxy configuration and no
+client changes. The runtime sets the standard proxy environment
+(`HTTP_PROXY` / `HTTPS_PROXY`, with `NO_PROXY` for internal hosts), so any client
+that honors it — `curl`, Python `requests` / `urllib`, `pip`, `npm`, Node
+`fetch`, and most language SDKs — reaches allowed hosts transparently:
+
+```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)
+```
+
+You also do **not** need to install any certificate. The platform manages the
+trust store for the managed egress path automatically, so TLS verification in
+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.
+- **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.
+- **`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).

package/docs/outputs.md

@@ -14,7 +14,7 @@ import { RunModels } from "@aexhq/sdk";
 const runId = await aex.submit({
   model: RunModels.CLAUDE_HAIKU_4_5,
   prompt: "Produce a report and save it as a file.",
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 
 await aex.wait(runId);

package/docs/provider-runtime-capabilities.md

@@ -4,11 +4,11 @@ title: Provider runtime capabilities
 
 # Provider runtime capabilities
 
-Generated from `packages/contracts/src/provider-support.ts` and `packages/contracts/src/models.ts`; runtime routing is derived through `checkRuntimeSupported` and `selectRuntime` in `packages/contracts/src/submission.ts`.
+Generated from `packages/contracts/src/provider-support.ts` and `packages/contracts/src/models.ts`.
 
 Regenerate with `bun run capabilities:generate`; check with `bun run capabilities:check`.
 
-Providers: [Anthropic](#anthropic) (`anthropic`), [DeepSeek](#deepseek) (`deepseek`), [OpenAI](#openai) (`openai`), [Gemini](#gemini) (`gemini`), [Mistral](#mistral) (`mistral`), [OpenRouter](#openrouter) (`openrouter`), [Doubao](#doubao) (`doubao`), [Doubao (China)](#doubao-cn) (`doubao-cn`). Runtime selectors: `managed`.
+Providers: [Anthropic](#anthropic) (`anthropic`), [DeepSeek](#deepseek) (`deepseek`), [OpenAI](#openai) (`openai`), [Gemini](#gemini) (`gemini`), [Mistral](#mistral) (`mistral`), [OpenRouter](#openrouter) (`openrouter`), [Doubao](#doubao) (`doubao`), [Doubao (China)](#doubao-cn) (`doubao-cn`).
 
 All new submissions run on the managed runtime. Public support is expressed as supported providers and supported model ids.
 
@@ -16,56 +16,36 @@ All new submissions run on the managed runtime. Public support is expressed as s
 
 | Provider | Selector | Supported models | Docs | Evidence |
 | --- | --- | --- | --- | --- |
-| [Anthropic](#anthropic) | `anthropic` | `claude-haiku-4-5`, `claude-3-5-haiku-latest`, `claude-3-5-sonnet-latest`, `claude-sonnet-4-6` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts) |
-| [DeepSeek](#deepseek) | `deepseek` | `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts) |
-| [OpenAI](#openai) | `openai` | `gpt-4.1`, `gpt-4o-mini` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| [Gemini](#gemini) | `gemini` | `gemini-2.0-flash`, `gemini-2.5-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| [Mistral](#mistral) | `mistral` | `mistral-large-latest`, `mistral-small-latest` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| [OpenRouter](#openrouter) | `openrouter` | `gpt-4o-mini`, `gpt-4o`, `gemini-2.0-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| [Doubao](#doubao) | `doubao` | `doubao-seed-pro`, `doubao-seed-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| [Doubao (China)](#doubao-cn) | `doubao-cn` | `doubao-seed-pro`, `doubao-seed-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-
-## Runtime routing
-
-| Provider | Default provider | Auto route | Runtime selector |
-| --- | --- | --- | --- |
-| `anthropic` | yes | `managed` | [managed](#anthropic) |
-| `deepseek` | no | `managed` | [managed](#deepseek) |
-| `openai` | no | `managed` | [managed](#openai) |
-| `gemini` | no | `managed` | [managed](#gemini) |
-| `mistral` | no | `managed` | [managed](#mistral) |
-| `openrouter` | no | `managed` | [managed](#openrouter) |
-| `doubao` | no | `managed` | [managed](#doubao) |
-| `doubao-cn` | no | `managed` | [managed](#doubao-cn) |
-
-## Runtime evidence
-
-| Provider | Runtime | Enforcement path | Evidence |
-| --- | --- | --- | --- |
-| `anthropic` | `managed` | submission parser + managed dispatch | [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts) |
-| `deepseek` | `managed` | submission parser + managed dispatch | [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts) |
-| `openai` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| `gemini` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| `mistral` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| `openrouter` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| `doubao` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-| `doubao-cn` | `managed` | submission parser + managed dispatch | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
-
-## Validation errors
-
-| Code | Docs anchor | Enforcement path | Evidence |
-| --- | --- | --- | --- |
-| `feature_runtime_mismatch` | [managed-unsupported-features](#managed-unsupported-features) | collectManagedUnsupportedFeatures + selectRuntime | [Submission parser and routing parity](../../contracts/test/submission.test.ts) |
-
-### Managed unsupported features
-
-Provider-hosted skill refs (a `kind:"provider"` skill ref) are rejected because new runs dispatch to the managed runtime. Supply skill bytes through `Skill.fromFiles`, `Skill.fromPath`, `Skill.fromUrl`, or `Skill.fromCatalog`; each path normalizes to an asset that the platform snapshots into durable run asset storage.
+| [Anthropic](#anthropic) | `anthropic` | `claude-haiku-4-5`, `claude-3-5-haiku-latest`, `claude-3-5-sonnet-latest`, `claude-sonnet-4-6` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts) |
+| [DeepSeek](#deepseek) | `deepseek` | `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts) |
+| [OpenAI](#openai) | `openai` | `gpt-4.1`, `gpt-4o-mini` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| [Gemini](#gemini) | `gemini` | `gemini-2.0-flash`, `gemini-2.5-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| [Mistral](#mistral) | `mistral` | `mistral-large-latest`, `mistral-small-latest` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| [OpenRouter](#openrouter) | `openrouter` | `gpt-4o-mini`, `gpt-4o`, `gemini-2.0-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| [Doubao](#doubao) | `doubao` | `doubao-seed-pro`, `doubao-seed-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| [Doubao (China)](#doubao-cn) | `doubao-cn` | `doubao-seed-pro`, `doubao-seed-flash` | [Secrets](secrets.md); [Events](events.md) | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+
+## Managed evidence
+
+| Provider | Enforcement path | Evidence |
+| --- | --- | --- |
+| `anthropic` | submission parser + managed execution | [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts) |
+| `deepseek` | submission parser + managed execution | [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts) |
+| `openai` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| `gemini` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| `mistral` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| `openrouter` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| `doubao` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+| `doubao-cn` | submission parser + managed execution | [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts) |
+
+## Skills
+
+Only asset-backed skills are accepted on submissions. Supply skill bytes through `Skill.fromFiles`, `Skill.fromPath`, `Skill.fromUrl`, or `Skill.fromCatalog`; each path normalizes to an asset that the platform snapshots into durable run asset storage.
 
 Notes:
 
 - Supported models are the public SDK model ids accepted for each provider.
-- Runtime routing describes how a validated submission is dispatched.
-- `runtime: "native"` is not a runtime selector; the submission parser rejects it as an invalid enum value.
+- Execution uses the managed path; there is no public runtime selector.
 
 ## Provider anchors
 
@@ -73,62 +53,54 @@ Notes:
 
 - Wire provider: `anthropic`
 - Supported models: `claude-haiku-4-5`, `claude-3-5-haiku-latest`, `claude-3-5-sonnet-latest`, `claude-sonnet-4-6`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK Anthropic live user test](../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts)
 
 ### DeepSeek
 
 - Wire provider: `deepseek`
 - Supported models: `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts); [Installed-SDK DeepSeek live user test](../../../apps/user-tests/test/live/live-sdk-deepseek.test.ts); [Installed-SDK DeepSeek comprehensive live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts)
 
 ### OpenAI
 
 - Wire provider: `openai`
 - Supported models: `gpt-4.1`, `gpt-4o-mini`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
 
 ### Gemini
 
 - Wire provider: `gemini`
 - Supported models: `gemini-2.0-flash`, `gemini-2.5-flash`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
 
 ### Mistral
 
 - Wire provider: `mistral`
 - Supported models: `mistral-large-latest`, `mistral-small-latest`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
 
 ### OpenRouter
 
 - Wire provider: `openrouter`
 - Supported models: `gpt-4o-mini`, `gpt-4o`, `gemini-2.0-flash`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
 
 ### Doubao
 
 - Wire provider: `doubao`
 - Supported models: `doubao-seed-pro`, `doubao-seed-flash`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
 
 ### Doubao (China)
 
 - Wire provider: `doubao-cn`
 - Supported models: `doubao-seed-pro`, `doubao-seed-flash`
-- Auto route: `managed`
 - Docs: [Secrets](secrets.md); [Events](events.md)
-- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)
+- Evidence: [Submission parser and routing parity](../../contracts/test/submission.test.ts); [Generated matrix freshness](../../../scripts/validate/capability-matrix.test.ts)

package/docs/public-surface.json

@@ -6,15 +6,14 @@
   "installCommand": "bun add @aexhq/sdk",
   "examples": {
     "typescriptLines": [
-      "import { AgentExecutor, Models, Providers } from \"@aexhq/sdk\";",
+      "import { AgentExecutor, Models } from \"@aexhq/sdk\";",
       "",
       "const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });",
       "",
       "const runId = await aex.submit({",
-      "  provider: Providers.ANTHROPIC,",
       "  model: Models.CLAUDE_HAIKU_4_5,",
       "  prompt: \"Write the report and save outputs.\",",
-      "  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }",
+      "  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }",
       "});",
       "",
       "for await (const event of aex.stream(runId)) console.log(event.type);",

package/docs/quickstart.md

@@ -10,26 +10,47 @@ title: Quickstart
 bun add @aexhq/sdk
 ```
 
-## 2. Submit a run
+This installs the TypeScript SDK exports and the bundled `aex` CLI.
+
+## 2. Set credentials
+
+The examples need both an aex API token and your BYOK provider key for the model
+you choose. For the Claude examples below:
+
+```bash
+export AEX_API_TOKEN="<your-aex-token>"
+export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
+```
+
+## 3. Run a prompt
 
 ```ts
-import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+import { AgentExecutor, Models } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!
-});
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 
-const runId = await aex.submit({
-  provider: Providers.ANTHROPIC,
+// run() submits, waits for the run to settle, and returns the result.
+// `provider` is derived from the model; `secrets.apiKeys` carries your BYOK provider key.
+const { text, ok } = await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Write a short report and save it as a file.",
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } },
+  prompt: "Write a short report and save it as a file."
 });
+
+console.log(ok, text);
 ```
 
-## 3. Stream, wait, and download
+## 4. Submit, stream, wait, and download
+
+When you need the run id, live events, or downloads, drive the lifecycle yourself:
 
 ```ts
+const runId = await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } },
+  prompt: "Write a short report and save it as a file."
+});
+
 for await (const event of aex.stream(runId)) {
   console.log(event.type);
 }
@@ -40,7 +61,7 @@ console.log(run.status);
 await aex.download(runId, { to: "./run.zip" });
 ```
 
-The same run from the CLI:
+The same run from the bundled CLI:
 
 ```bash
 aex run \

package/docs/run-config.md

@@ -15,13 +15,12 @@ Allowed fields:
 - `mcpServers` - array of `McpServerRef`; headers are split into `secrets.mcpServers` server-side.
 - `environment` - `{ networking?, packages?, envVars? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `envVars` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts.
 - `runtimeSize` - optional managed-runtime preset. Prefer `RuntimeSizes` in TypeScript.
-- `region` - optional product placement region: `eu-west`, `us-west`, or `ap-northeast`. These are platform placement targets, not exact city guarantees; omitted runs infer a configured region from request geography and fall back when no hint matches.
 - `timeout` - optional run deadline duration string such as `"30m"` or `"2h"`.
 - `postHook` - optional post-agent verifier `{ command, timeout?, maxTurns?, maxChars? }`. It runs after a successful agent process; a failing or timed-out command is sent back to the agent for repair until `maxTurns` is exhausted. Empty `command` is treated as omitted.
 - `proxyEndpoints` - array of `PlatformProxyEndpoint`; endpoint-level `retry` is allowed here and remains declaration-based.
 - `metadata` - non-secret structured metadata.
 
-`agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, `limits`, and `outputMode` are top-level `submit` options, not run-config fields. They carry bytes, capture behavior, or agent tool/output controls that belong on a concrete run submission. The `limits` option sets per-run subagent-lineage caps (`maxConcurrentChildRuns`, `maxSubagentDepth`); see [Limits & quotas](limits-and-quotas.md).
+`agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, `limits`, and `outputMode` are top-level `submit` options, not run-config fields. They carry bytes, capture behavior, or agent tool/output controls that belong on a concrete run submission. The `limits` option sets per-run caps: the subagent-lineage caps (`maxConcurrentChildRuns`, `maxSubagentDepth`) and a USD spend cap (`maxSpendUsd`, which stops the run once its spend would exceed the cap); see [Limits & quotas](limits-and-quotas.md).
 
 Secrets never live in run config. Pass credentials through `submit({ ...config, 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.
 
@@ -46,7 +45,7 @@ function summarise(topic: string) {
 
 await aex.submit({
   ...summarise("agent-first SDK design"),
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 
@@ -60,4 +59,4 @@ aex run --config ./run.json \
   --anthropic-api-key "$ANTHROPIC_API_KEY"
 ```
 
-...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--region`, `--runtime-size`, `--run-timeout`, `--proxy-endpoint`, `--proxy-auth`, `--metadata`). The two modes are mutually exclusive. `postHook` is available through `--config`; there are no standalone hook flags.
+...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. `postHook` is available through `--config`; there are no standalone hook flags.