@aexhq/sdk 0.23.0 → 0.25.0

package/docs/provider-runtime-capabilities.md

@@ -4,54 +4,52 @@ title: Provider runtime capabilities
 
 # Provider runtime capabilities
 
-Generated from `packages/contracts/src/provider-support.ts`; runtime cells are 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`; runtime routing is derived through `checkRuntimeSupported` and `selectRuntime` in `packages/contracts/src/submission.ts`.
 
 Regenerate with `pnpm capabilities:generate`; check with `pnpm 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`.
 
-All new submissions run on the managed runtime. Public support facts are listed separately from runtime dispatch facts.
+All new submissions run on the managed runtime. Public support is expressed as supported providers and supported model ids.
 
-Status vocabulary: `supported`, `live-unverified`, `rejected`.
+## Supported models
 
-## Public support
-
-| Provider | Wire value | Status | Docs | Evidence |
+| Provider | Selector | Supported models | Docs | Evidence |
 | --- | --- | --- | --- | --- |
-| [Anthropic](#anthropic) | `anthropic` | supported | [Credentials](credentials.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` | supported | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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` | live-unverified | [Credentials](credentials.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) |
+| [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: "managed"` |
+| 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` | yes | `managed` | [supported](#anthropic) |
-| `deepseek` | no | `managed` | [supported](#deepseek) |
-| `openai` | no | `managed` | [live-unverified](#openai) |
-| `gemini` | no | `managed` | [live-unverified](#gemini) |
-| `mistral` | no | `managed` | [live-unverified](#mistral) |
-| `openrouter` | no | `managed` | [live-unverified](#openrouter) |
-| `doubao` | no | `managed` | [live-unverified](#doubao) |
-| `doubao-cn` | no | `managed` | [live-unverified](#doubao-cn) |
-
-## Runtime cell evidence
-
-| Provider | Runtime | Status | Ownership | Enforcement path | Evidence |
-| --- | --- | --- | --- | --- | --- |
-| `anthropic` | `managed` | supported | supported | 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` | supported | supported | 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` | live-unverified | live-unverified | 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` | live-unverified | live-unverified | 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` | live-unverified | live-unverified | 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` | live-unverified | live-unverified | 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` | live-unverified | live-unverified | 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` | live-unverified | live-unverified | 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) |
+| `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
 
@@ -65,72 +63,72 @@ Provider-hosted skill refs (a `kind:"provider"` skill ref) are rejected because
 
 Notes:
 
-- Public status describes provider availability on the SDK surface. Runtime routing describes how a validated submission is dispatched.
+- 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.
-- `live-unverified` means the shape is accepted by code but does not yet have equal live user-test evidence.
 
 ## Provider anchors
 
 ### Anthropic
 
 - Wire provider: `anthropic`
-- Public status: supported
+- Supported models: `claude-haiku-4-5`, `claude-3-5-haiku-latest`, `claude-3-5-sonnet-latest`, `claude-sonnet-4-6`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### DeepSeek
 
 - Wire provider: `deepseek`
-- Public status: supported
+- Supported models: `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### OpenAI
 
 - Wire provider: `openai`
-- Public status: live-unverified
+- Supported models: `gpt-4.1`, `gpt-4o-mini`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### Gemini
 
 - Wire provider: `gemini`
-- Public status: live-unverified
+- Supported models: `gemini-2.0-flash`, `gemini-2.5-flash`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### Mistral
 
 - Wire provider: `mistral`
-- Public status: live-unverified
+- Supported models: `mistral-large-latest`, `mistral-small-latest`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### OpenRouter
 
 - Wire provider: `openrouter`
-- Public status: live-unverified
+- Supported models: `gpt-4o-mini`, `gpt-4o`, `gemini-2.0-flash`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### Doubao
 
 - Wire provider: `doubao`
-- Public status: live-unverified
+- Supported models: `doubao-seed-pro`, `doubao-seed-flash`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)
 
 ### Doubao (China)
 
 - Wire provider: `doubao-cn`
-- Public status: live-unverified
+- Supported models: `doubao-seed-pro`, `doubao-seed-flash`
 - Auto route: `managed`
-- Docs: [Credentials](credentials.md); [Events](events.md)
+- 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)

package/docs/public-surface.json

@@ -0,0 +1,81 @@
+{
+  "brand": "aex",
+  "productName": "Agent Executor",
+  "oneLine": "aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.",
+  "description": "Submit typed runs, stream durable events, capture outputs, and compose agents with skills, files, MCP, proxy endpoints, and subagents across the managed runtime.",
+  "installCommand": "npm install @aexhq/sdk",
+  "examples": {
+    "typescriptLines": [
+      "import { AgentExecutor, Models, Providers } 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! }",
+      "});",
+      "",
+      "for await (const event of aex.stream(runId)) console.log(event.type);",
+      "await aex.wait(runId);",
+      "await aex.download(runId, { to: \"./run.zip\" });"
+    ],
+    "cliLines": [
+      "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.\" \\",
+      "  --follow"
+    ]
+  },
+  "providers": [
+    { "id": "anthropic", "name": "Anthropic" },
+    { "id": "deepseek", "name": "DeepSeek" },
+    { "id": "openai", "name": "OpenAI" },
+    { "id": "gemini", "name": "Gemini" },
+    { "id": "mistral", "name": "Mistral" },
+    { "id": "openrouter", "name": "OpenRouter" },
+    { "id": "doubao", "name": "Doubao" },
+    { "id": "doubao-cn", "name": "Doubao China" }
+  ],
+  "featureAreas": [
+    {
+      "slug": "agent-runtime",
+      "href": "/docs/features/#agent-runtime",
+      "title": "Agent runtime",
+      "description": "Managed autonomous runs with shell, filesystem, editing, notebook, web fetch/search, background command, and post-hook repair tools."
+    },
+    {
+      "slug": "durable-infrastructure",
+      "href": "/docs/features/#durable-infrastructure",
+      "title": "Durable infrastructure",
+      "description": "Run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes."
+    },
+    {
+      "slug": "agent-composition",
+      "href": "/docs/features/#agent-composition",
+      "title": "Agent composition",
+      "description": "Skills, files, AGENTS.md, remote MCP servers, proxy endpoints, environment variables, packages, and networking controls."
+    },
+    {
+      "slug": "subagents",
+      "href": "/docs/features/#subagents",
+      "title": "Subagents",
+      "description": "Typed parent/child lineage for async child runs, output handoff, and bounded agent delegation."
+    },
+    {
+      "slug": "models-and-providers",
+      "href": "/docs/features/#models-and-providers",
+      "title": "Models and providers",
+      "description": "Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape."
+    },
+    {
+      "slug": "typed-control-surface",
+      "href": "/docs/features/#typed-control-surface",
+      "title": "Typed control surface",
+      "description": "Strongly typed SDK inputs, CLI parity, BYOK secrets, scoped proxy auth, redaction, and output modes."
+    }
+  ]
+}

package/docs/quickstart.md

@@ -1,137 +1,60 @@
 ---
-title: aex quickstart
+title: Quickstart
 ---
 
 # Quickstart
 
-1. Get an aex SDK API token (`ant_…`).
-2. Create `AgentExecutor` — the workspace is derived server-side from the token.
-3. Submit the run with the agent's brief plus an inline `secrets` bundle. Wait for terminal status. Fetch outputs.
+## 1. Install
+
+```bash
+npm install @aexhq/sdk
+```
+
+## 2. Submit a run
 
 ```ts
-import { AgentExecutor, RunModels } from "@aexhq/sdk";
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!,
-  // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
+  apiToken: process.env.AEX_API_TOKEN!
 });
 
 const runId = await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
-  prompt: "Write a short answer about agent-first SDK design.",
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Write a short report and save it as a file.",
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
 });
-
-const run = await aex.wait(runId);
-console.log(run.status);
-console.log(await aex.outputs(runId));
 ```
 
-For reusable, credential-free configs, use an ordinary function:
+## 3. Stream, wait, and download
 
 ```ts
-function summarise(topic: string) {
-  return {
-    model: RunModels.CLAUDE_HAIKU_4_5,
-    prompt: `Write a short answer about ${topic}.`
-  };
+for await (const event of aex.stream(runId)) {
+  console.log(event.type);
 }
 
-const runId = await aex.submit({
-  ...summarise("agent-first SDK design"),
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
-});
+const run = await aex.wait(runId);
+console.log(run.status);
+
+await aex.download(runId, { to: "./run.zip" });
 ```
 
-Or from the shell:
+The same run from the CLI:
 
 ```bash
 aex run \
   --api-token "$AEX_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --prompt "Write a short answer about agent-first SDK design." \
+  --prompt "Write a short report and save it as a file." \
   --follow
 ```
 
-For a config-file flow, pass `--config <path>` with a run-config JSON file for a single run request (`{ model, system?, prompt, skills?, mcpServers?, environment?, runtimeSize?, timeout?, postHook?, proxyEndpoints?, metadata? }`). Both surfaces hit the same aex backend and operate on the same durable run records. The JSON `model` value is validated against `RUN_MODELS`.
-
-## Runtime controls
-
-`submit` also accepts per-run controls that are not secrets:
-
-- `runtimeSize` - a closed managed-runtime preset. Prefer `RuntimeSizes`, e.g. `RuntimeSizes.SHARED_2X_2GB`.
-- `timeout` - run deadline as a duration string such as `"30m"` or `"2h"`; bounded server-side.
-- `postHook` - optional post-agent verifier, e.g. `{ command: "pnpm test", timeout: "5m", maxTurns: 3, maxChars: 12000 }`. It runs after the agent process exits successfully; failures are sent back to the agent for repair until `maxTurns` is exhausted. Empty `command` is treated as omitted.
-- `builtins` - managed-runtime builtin extensions. Omit it to use the default `["developer"]` toolkit. Pass `[]` for a pure-MCP run with no builtins.
-- `outputMode` - `"buffered"` by default; pass `"stream"` for per-token assistant text deltas.
-
-## Where things go: customer → primitive mapping
-
-Every kind of thing you want to ship at run time has exactly one right primitive in the SDK. Reach for the right one rather than rolling your own wrapper.
-
-| What you have | Primitive | What it does |
-|---|---|---|
-| Non-secret paths or config (`BROLL_STORE`, mode flags) | `environment.envVars` | Mounted as `RUNTIME.env` / `RUNTIME.json`; `__KEY__` substitution in agent-facing markdown; echoed back as `run.runtimeManifest.envVars` |
-| Upstream HTTPS API keys (TMDB, Brave, Tavily, …) | `ProxyEndpoint` | Credentials live server-side; aex proxy injects them on outbound calls. The key never enters the container. |
-| MCP server credentials | `secrets.mcpServers` | Held in run-scoped custody, attached per run |
-| Provider API key | `secrets.apiKey` | Required on every `submit`; held in run-scoped custody. Carries the BYOK key for the selected `provider` |
-| Non-secret reference data files or folders (transcripts, persona docs, PDFs) | `File.fromPath('./subtitles.srt')` / `File.fromPath('./customer-folder/')` | Unzipped into the `mountPath` directory (default `/workspace`, the agent's cwd), preserving the real filename + extension — e.g. `/workspace/subtitles.srt`. See [Files: where they land](#files-where-they-land). |
-| Executable skill code (a `.pyz` wrapper, scripts, prompts) | `Skill.fromPath('./skills/my-skill/')` | Mounted under `skills/<name>/`; the bundle's `SKILL.md` is composed into the agent's instructions |
-| Agent instructions file | `AgentsMd.fromPath('./AGENTS.md')` | Prepended as the first user turn |
-
-`Skill`, `AgentsMd`, and `File` values are materialized for the run before the first agent turn. `environment.envVars` values surface in runtime metadata and can be referenced by `__KEY__` placeholders in agent-facing markdown.
-
-### Files: where they land
-
-A `File` is uploaded as a content-addressed archive and **unzipped on the runtime into a directory**, preserving the real filename + extension — the agent sees the actual file, never a `.zip` to unpack.
-
-- **`mountPath` is the directory the archive unzips into.** It must be an absolute container path (`/...`, no `..` traversal). It defaults to **`/workspace`**, which is also the agent's default working directory — so a file handed with no `mountPath` lands directly in the agent's cwd.
-- **A single file keeps its real basename.** `File.fromPath('./source-video-subtitles.srt')` lands at `/workspace/source-video-subtitles.srt` (not a slug, not a `.zip`). `File.fromBytes({ name: 'data.csv', bytes })` lands at `/workspace/data.csv` — `name` is the real filename here.
-- **A folder lands its entries under the mount directory.** `File.fromPath('./repo/', { mountPath: '/workspace/repo' })` puts each file at `/workspace/repo/<relative-path>`.
-- **The resolved mount directory is surfaced back on the run.** Read `run.runtimeManifest.mountedFiles` (an array of `{ name, mountPath }`) to learn where each handed file landed.
-
-```ts
-const subtitles = await File.fromPath('./source-video-subtitles.srt'); // → /workspace/source-video-subtitles.srt
-const dataset = await File.fromPath('./data/', { mountPath: '/workspace/input' }); // → /workspace/input/<files>
-const run = await client.submit({ model, prompt, files: [subtitles, dataset], secrets: { apiKey } });
-const resolved = (await client.getRun(run.id)).runtimeManifest?.mountedFiles;
-// [{ name: 'source-video-subtitles', mountPath: '/workspace' }, { name: 'data', mountPath: '/workspace/input' }]
-```
-
-## Safe retries with `idempotencyKey`
-
-Every `submit` call carries an `idempotencyKey`. When omitted the SDK auto-generates a UUID per call. Supplying your own key makes retries deterministic:
-
-| Submit shape | Server response |
-| --- | --- |
-| New `idempotencyKey` | HTTP 202 — returns the new run id. |
-| Same key + identical request body hash | HTTP 200 — returns the original run id. The SDK call resolves with that id. |
-| Same key + **different** request body hash | HTTP 409 — body `{ error: { message, code: "idempotency_conflict", details: { existingRunId } } }`. The SDK throws an `HttpError` carrying that body. Use `details.existingRunId` to adopt the pre-existing run, or pick a fresh key. |
-| Omitted `idempotencyKey` | A new UUID is generated on every call — repeat submissions create new runs. |
-
-The request hash is computed server-side over the canonical submission JSON (model, prompt, system, environment, skill refs, MCP server descriptors, proxy endpoints, `outputs`, etc.) so reordering JSON keys, adding whitespace, or rotating the inline secret bundle does **not** change the hash. Changing the prompt, model, system, or any other non-secret field does.
-
-Pattern for safe retries:
-
-```ts
-const idempotencyKey = crypto.randomUUID();
-async function submitWithRetry() {
-  for (let attempt = 0; attempt < 3; attempt++) {
-    try {
-      return await aex.submit({
-        model: RunModels.CLAUDE_HAIKU_4_5,
-        prompt: "...",
-        idempotencyKey,
-        secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
-      });
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("network")) continue;
-      throw err;
-    }
-  }
-  throw new Error("submit failed after retries");
-}
-```
+## Add capabilities
 
-The same `idempotencyKey` reused with the same body will deterministically resolve to the same run id regardless of how many times the network drops between attempts. Query, stream, wait, or download the run by that id.
+- Add files, skills, AGENTS.md, MCP servers, proxy endpoints, packages, and networking controls with [Composition](concepts/composition.md).
+- Inspect runtime tools with [Agent tools](concepts/agent-tools.md).
+- Use parent/child run delegation from the [Features](https://aex.dev/docs/features/#subagents) page.
+- Narrow output capture or download individual files with [Outputs](outputs.md).
+- Check supported providers and models in the [provider/runtime capability matrix](provider-runtime-capabilities.md).

package/docs/run-config.md

@@ -22,7 +22,7 @@ Allowed fields:
 
 `agentsMd`, `files`, `outputs`, `builtins`, 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.
 
-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 [Credentials](credentials.md) for the proxy endpoint policy/auth split and retry fields.
+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.
 
 ## Reuse in code
 

package/docs/secrets.md

@@ -0,0 +1,123 @@
+---
+title: Secrets
+---
+
+# Secrets
+
+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.
+
+## Use A Provider Key For One Run
+
+### 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: "Write the report and save outputs.",
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+### CLI
+
+```bash
+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."
+```
+
+## Upload An Env Secret
+
+Use `Secret.value(...).upload(...)` when you start with an ephemeral value and
+want to persist it as a named workspace secret for later runs.
+
+```ts
+import { AgentExecutor, Models, Providers, Secret } from "@aexhq/sdk";
+
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+
+const githubToken = await Secret.value(process.env.GITHUB_TOKEN!).upload(aex, {
+  name: "github-token"
+});
+
+await aex.submit({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Inspect the repository issues.",
+  secretEnv: { GITHUB_TOKEN: githubToken },
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+## Set Or Rotate A Workspace Secret
+
+Use `client.secrets.set(...)` to create a named secret directly. Use
+`client.secrets.rotate(...)` to replace its value while keeping the same name.
+
+```ts
+await aex.secrets.set({
+  name: "serper-api-key",
+  value: process.env.SERPER_API_KEY!
+});
+
+await aex.secrets.rotate({
+  name: "serper-api-key",
+  value: process.env.SERPER_API_KEY_NEXT!
+});
+```
+
+## Retrieve Secret Metadata
+
+`list` and `get` return metadata only. They never return the secret value.
+
+```ts
+const secrets = await aex.secrets.list();
+const metadata = await aex.secrets.get("serper-api-key");
+```
+
+## Get A Secret Value
+
+Use `get_value` only when the value is intentionally needed outside a run. It is
+the explicit audited value-read path.
+
+```ts
+const secretValue = await aex.secrets.get_value("serper-api-key");
+console.log(secretValue.value);
+```
+
+## Inject A Workspace Secret Into A Run
+
+Reference workspace secrets with `Secret.ref(name)`. The value resolves
+server-side and is injected as the named environment variable.
+
+```ts
+import { Models, Providers, Secret } from "@aexhq/sdk";
+
+await aex.submit({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Use SERPER_API_KEY for web search.",
+  secretEnv: {
+    SERPER_API_KEY: Secret.ref("serper-api-key")
+  },
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+## Delete A Workspace Secret
+
+```ts
+await aex.secrets.delete("serper-api-key");
+```
+
+The CLI supports per-run provider, MCP, and proxy credentials. Workspace secret
+administration is exposed through the SDK.

package/docs/vision-skills.md

@@ -32,7 +32,7 @@ a raised `maxRequestBytes` (so the base64 image fits):
 ```ts
 import { AgentExecutor, RunModels, Skill, ProxyEndpoint, validateProxyAuth } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({ apiToken: process.env.AEX_WORKSPACE_TOKEN! });
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 
 const proxyEndpoints = [
   ProxyEndpoint.bearer({
@@ -146,11 +146,8 @@ frame_%03d.jpg`) — full-res adds payload and cost, not signal.
 
 ## Notes
 
-- **Egress.** The named proxy reaches any HTTPS host you declare as `baseUrl`
-  (no upstream allow-list; only a literal-IP SSRF deny-list). The international
-  BytePlus host (`ark.ap-southeast.bytepluses.com`) is a normal public host. The
-  China host (`ark.cn-beijing.volces.com`) is reachable in principle but the
-  platform's egress to Beijing is currently unverified — prefer the BytePlus host.
+- **Host selection.** Use the provider endpoint that matches your account and
+  declare it as the proxy endpoint `baseUrl`.
 - **Keyless model hosts.** If the upstream takes no credential, declare the
   endpoint with `authShape: { type: "none" }` and omit the `proxyEndpointAuth`
   entry (see `credentials.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
     "examples"
   ],
   "devDependencies": {
-    "@aexhq/contracts": "0.23.0"
+    "@aexhq/contracts": "0.25.0"
   },
   "engines": {
     "node": ">=20"