@aexhq/sdk 0.30.0 → 0.31.0

package/docs/defaults.md

@@ -7,13 +7,12 @@ title: 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; 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)
-(runtime-size presets:
-[`packages/contracts/src/runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts)).
+Each value below is named by its source-of-truth constant. The runtime-size
+presets are defined in the public
+[`packages/contracts/src/runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts).
 For the hard ceilings and who can raise them, see
 [Limits & quotas](limits-and-quotas.md). For policy boundaries, see
 [Limits](limits.md).
@@ -22,50 +21,51 @@ For the hard ceilings and who can raise them, see
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| `timeout` (run deadline) | 1 hour | Per-run via `options.timeout` (e.g. `"30m"`, `"2h"`), clamped to the run-timeout floor/ceiling. | [`RUN_DEFAULT_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L154) |
-| `runtimeSize` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-run via `options.runtimeSize` (use `RuntimeSizes.*` in TypeScript). | [`RUN_DEFAULT_RUNTIME_SIZE`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L143) |
-| `postHook.timeout` | 60 minutes | 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) |
-| `postHook.maxTurns` (repair budget) | 10 turns | Per-run via the hook's `maxTurns`. | [`RUN_DEFAULT_POST_HOOK_MAX_TURNS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L244) |
+| `timeout` (run deadline) | 1 hour | Per-run via `options.timeout` (e.g. `"30m"`, `"2h"`), clamped to the run-timeout floor/ceiling. | `RUN_DEFAULT_TIMEOUT_MS` |
+| `runtimeSize` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-run via `options.runtimeSize` (use `RuntimeSizes.*` in TypeScript). | `RUN_DEFAULT_RUNTIME_SIZE` |
+| `postHook.timeout` | 60 minutes | Per-run via the hook's `timeoutMs`. | `RUN_DEFAULT_POST_HOOK_TIMEOUT_MS` |
+| `postHook.maxTurns` (repair budget) | 10 turns | Per-run via the hook's `maxTurns`. | `RUN_DEFAULT_POST_HOOK_MAX_TURNS` |
+| `limits.maxSpendUsd` (per-run spend cap) | None — no per-run spend cap (the run is still bounded by its `timeout` and any workspace-level cap) | Per-run via `options.limits.maxSpendUsd` (a positive USD amount); the run is stopped once its spend would exceed the cap. | — |
 
 ## 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`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L202) |
-| `web_fetch` returned body | 500 KB (UTF-8) | Per-call via the tool's `max_bytes` argument. | [`REQUEST_WEB_FETCH_DEFAULT_MAX_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L528) |
+| Per-call exec timeout | 30 minutes | Per-call via the tool call's `timeoutMs`. | `RUN_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`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L255) |
-| MCP `tools/call` timeout | 30 minutes | Per-port via `callTimeoutMs`. | [`RUN_DEFAULT_MCP_CALL_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L265) |
+| 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` |
 
 ## Proxy endpoints
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| `maxRequestBytes` | 10 MiB | Per-endpoint via the endpoint's `maxRequestBytes`. | [`REQUEST_PROXY_DEFAULT_MAX_REQUEST_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L499) |
-| `maxResponseBytes` | `0` (unlimited — the response is streamed unbuffered) | Per-endpoint via the endpoint's `maxResponseBytes`. | [`REQUEST_PROXY_DEFAULT_MAX_RESPONSE_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L509) |
-| `timeoutMs` (upstream) | 5 minutes | Per-endpoint via the endpoint's `timeoutMs`. | [`REQUEST_PROXY_DEFAULT_TIMEOUT_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L519) |
+| `maxRequestBytes` | 10 MiB | Per-endpoint via the endpoint's `maxRequestBytes`. | `REQUEST_PROXY_DEFAULT_MAX_REQUEST_BYTES` |
+| `maxResponseBytes` | `0` (unlimited — the response is streamed unbuffered) | Per-endpoint via the endpoint's `maxResponseBytes`. | `REQUEST_PROXY_DEFAULT_MAX_RESPONSE_BYTES` |
+| `timeoutMs` (upstream) | 5 minutes | Per-endpoint via the endpoint's `timeoutMs`. | `REQUEST_PROXY_DEFAULT_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; `outputLink(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `outputLink` / `fetchOutput`. | [`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 | Per-mint via the `ttlMs` argument. | [`REQUEST_TICKET_DEFAULT_TTL_MS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L549) |
+| Output link / signed-URL TTL | 300 seconds (5 minutes) at the storage layer; `outputLink(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `outputLink` / `fetchOutput`. | `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
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Concurrent child runs per lineage root | 1000 (live, non-terminal child runs) | Per-run via `options.limits.maxConcurrentChildRuns`, clamped to the 4096 platform ceiling. | [`RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L429) |
-| Max subagent depth | 5 | Per-run via `options.limits.maxSubagentDepth`, clamped to the same 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 child runs) | Per-run via `options.limits.maxConcurrentChildRuns`, clamped to the 4096 platform ceiling. | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
+| Max subagent depth | 5 | Per-run via `options.limits.maxSubagentDepth`, clamped to the same hard ceiling. | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
 
 ## Workspace
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Per-workspace mutation rate limits (per minute) | run submit 60, run cancel 30, run delete 30, signed link 120, API token create 10, API token delete 30 | Per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var. | [`WORKSPACE_RATE_LIMIT_DEFAULTS`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L112) |
-| Workspace storage cap | 50 GiB | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES`; admin workspaces are uncapped (not a customer entitlement). | [`WORKSPACE_DEFAULT_STORAGE_CAP_BYTES`](https://github.com/aexhq/aex-platform/blob/main/packages/shared/src/limits.ts#L52) |
+| Per-workspace mutation rate limits (per minute) | run submit 60, run cancel 30, run delete 30, signed link 120, API token create 10, API token delete 30 | Per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var. | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
+| Workspace storage cap | 50 GiB | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES`; admin workspaces are uncapped (not a customer entitlement). | `WORKSPACE_DEFAULT_STORAGE_CAP_BYTES` |

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

@@ -61,7 +61,7 @@ await aex.submit({
       allowedHosts: ["api.example.com", "status.example.com"]
     }
   },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 
@@ -96,7 +96,7 @@ await aex.submit({
   model: Models.CLAUDE_HAIKU_4_5,
   prompt: "Research the topic across the open web.",
   environment: { networking: { mode: "open" } },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 

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,7 +10,19 @@ title: Quickstart
 bun add @aexhq/sdk
 ```
 
-## 2. Run a prompt
+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 } from "@aexhq/sdk";
@@ -18,24 +30,24 @@ import { AgentExecutor, Models } from "@aexhq/sdk";
 const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 
 // run() submits, waits for the run to settle, and returns the result.
-// `provider` is derived from the model; `apiKey` is your BYOK provider key.
+// `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,
-  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. Submit, 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,
-  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."
 });
 
@@ -49,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.