@aexhq/sdk 0.30.0 → 0.32.0

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` | [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`
+- Supported models: `deepseek-v4-flash`, `deepseek-v4-pro`
 - 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! }",
+      "  prompt: \"Write a short report and save it as a file.\",",
+      "  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }",
       "});",
       "",
       "for await (const event of aex.stream(runId)) console.log(event.type);",
@@ -26,7 +25,7 @@
       "  --api-token \"$AEX_API_TOKEN\" \\",
       "  --anthropic-api-key \"$ANTHROPIC_API_KEY\" \\",
       "  --model claude-haiku-4-5 \\",
-      "  --prompt \"Write the report and save outputs.\" \\",
+      "  --prompt \"Write a short report and save it as a file.\" \\",
       "  --follow"
     ]
   },

package/docs/quickstart.md

@@ -10,7 +10,20 @@ title: Quickstart
 bun add @aexhq/sdk
 ```
 
-## 2. Run a prompt
+This installs the TypeScript SDK exports and the bundled `aex` CLI.
+
+## 2. Set credentials
+
+In the dashboard, create a quickstart SDK token with `runs:read`, `runs:write`,
+and `outputs:read`. The examples also need your BYOK provider key for the model
+you choose. For the Claude examples below:
+
+```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 +31,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 +62,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.
 
@@ -34,11 +33,11 @@ exhausts `maxTurns` fails the run with `data.failureClass: "post_hook_failed"`.
 Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the run parameters you submit.
 
 ```ts
-import { RunModels } from "@aexhq/sdk";
+import { Models } from "@aexhq/sdk";
 
 function summarise(topic: string) {
   return {
-    model: RunModels.CLAUDE_HAIKU_4_5,
+    model: Models.CLAUDE_HAIKU_4_5,
     system: "You are a concise automation agent.",
     prompt: `Write a short answer about ${topic}.`
   };
@@ -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.

package/docs/secrets.md

@@ -8,20 +8,22 @@ aex supports BYOK provider keys, per-run credentials, and reusable workspace
 secrets. Secret values are excluded from the idempotency fingerprint and do not
 belong in run config.
 
+Runnable examples need both `AEX_API_TOKEN` for aex and the matching BYOK
+provider key, such as `ANTHROPIC_API_KEY` for Claude.
+
 ## Use A Provider Key For One Run
 
 ### TypeScript
 
 ```ts
-import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+import { AgentExecutor, Models } 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: "Write the report and save outputs.",
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  prompt: "Write a short report and save it as a file.",
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 
@@ -32,7 +34,7 @@ aex run \
   --api-token "$AEX_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --prompt "Write the report and save outputs."
+  --prompt "Write a short report and save it as a file."
 ```
 
 ## Upload An Env Secret
@@ -54,7 +56,7 @@ await aex.submit({
   model: Models.CLAUDE_HAIKU_4_5,
   prompt: "Inspect the repository issues.",
   secretEnv: { GITHUB_TOKEN: githubToken },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 
@@ -109,7 +111,7 @@ await aex.submit({
   secretEnv: {
     SERPER_API_KEY: Secret.ref("serper-api-key")
   },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 

package/docs/skills.md

@@ -24,12 +24,6 @@ All three sources normalize to the same content-addressed asset. Identical bytes
 dedup by hash, so repeated submissions of the same bundle are no-op uploads.
 There is no per-run auto-suffixed `skl_*` row for inline skills.
 
-Provider-hosted skill refs (`kind:"provider"`, e.g. Anthropic prebuilt Agent
-Skills or custom provider skill IDs) are not supported on the managed runtime.
-Every new submission dispatches to managed, so a `kind:"provider"` ref is
-rejected at submission time with `feature_runtime_mismatch`. Supply the bytes as
-an aex asset instead.
-
 ## Materialization
 
 For each run, the platform copies referenced skill assets into durable run asset
@@ -60,15 +54,15 @@ keep their run-scoped copy.
 canonical zip bytes and a `sha256:<hex>` content hash.
 
 ```ts
-import { AgentExecutor, RunModels, Skill } from "@aexhq/sdk";
+import { AgentExecutor, Models, Skill } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({ apiToken });
 
 await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
+  model: Models.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [await Skill.fromPath("./skills/rules", { name: "rules" })],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 
@@ -80,9 +74,7 @@ flow:
 2. The SDK PUTs bytes directly to object storage with the signed checksum headers.
 3. `POST /assets/finalize` confirms the object exists.
 
-When direct upload credentials are not configured, small bundles fall back to
-the buffered `/assets` upload path. The runner re-verifies the content hash when
-it downloads the asset.
+The runner re-verifies the content hash when it downloads the asset.
 
 ## Pre-Upload For Reuse
 
@@ -94,10 +86,10 @@ const draft = await Skill.fromFiles({ name: "rules", files });
 const uploaded = await draft.upload(aex);
 
 await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
+  model: Models.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [uploaded],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 
@@ -131,10 +123,10 @@ assets. Use them when a team wants a named, listed skill record:
 const [record] = await aex.skills.list();
 
 await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
+  model: Models.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [Skill.fromCatalog(record)],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 

package/docs/vision-skills.md

@@ -30,7 +30,7 @@ settings are `responseMode: "full"` (so the skill gets the upstream JSON back) a
 a raised `maxRequestBytes` (so the base64 image fits):
 
 ```ts
-import { AgentExecutor, RunModels, Skill, ProxyEndpoint, validateProxyAuth } from "@aexhq/sdk";
+import { AgentExecutor, Models, Skill, ProxyEndpoint, validateProxyAuth } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 
@@ -53,12 +53,12 @@ const proxyEndpointAuth = [
 validateProxyAuth(proxyEndpoints, proxyEndpointAuth); // fail fast at submit time
 
 const runId = await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
+  model: Models.CLAUDE_HAIKU_4_5,
   prompt: "…read skills/frame-vision-gate/SKILL.md, then caption + verify the frame…",
   skills: [await Skill.fromPath("./vision-skill", { name: "frame-vision-gate" })],
   proxyEndpoints,
   secrets: {
-    apiKey: process.env.ANTHROPIC_API_KEY!,
+    apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
     proxyEndpointAuth
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
     "pack:dry-run": "bun ../../scripts/with-generated-dist-lock.mjs bun pm pack --dry-run --ignore-scripts"
   },
   "devDependencies": {
-    "@aexhq/contracts": "0.30.0"
+    "@aexhq/contracts": "0.31.0"
   },
   "engines": {
     "bun": ">=1.3.14"