@aexhq/sdk 0.24.0 → 0.25.1

package/docs/concepts/composition.md

@@ -0,0 +1,43 @@
+---
+title: Composition
+description: The primitives used to assemble each run.
+icon: Blocks
+---
+
+aex composes an agent from explicit per-run inputs. The SDK materializes local
+bytes before submission and the platform mounts them into the managed runtime
+before the first agent turn.
+
+| Need | Primitive |
+| --- | --- |
+| Executable or instructional bundles | `Skill.fromPath`, `Skill.fromFiles`, `Skill.fromUrl`, `Skill.fromCatalog` |
+| Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
+| Reference files and folders | `File.fromPath`, `File.fromBytes` |
+| Remote tools | `McpServer.remote`, `McpServer.fromId` |
+| Credentialed HTTP APIs | `ProxyEndpoint.none`, `bearer`, `basic`, `header`, `query` |
+| Non-secret runtime settings | `environment.envVars`, `environment.packages`, `environment.networking` |
+
+```ts
+import { AgentsMd, File, McpServer, Models, ProxyEndpoint, Skill } from "@aexhq/sdk";
+
+await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Use the attached docs and tools to produce a report.",
+  agentsMd: [AgentsMd.fromContent("Follow the repo conventions.")],
+  files: [await File.fromPath("./input")],
+  skills: [await Skill.fromPath("./skills/report-writer", { name: "report-writer" })],
+  mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
+  proxyEndpoints: [
+    ProxyEndpoint.bearer({
+      name: "internal-api",
+      baseUrl: "https://api.example.com",
+      allowMethods: ["GET"],
+      allowPathPrefixes: ["/v1/"]
+    })
+  ],
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+Secrets stay out of reusable configs. Put provider keys, MCP auth, and proxy
+auth in the `secrets` bundle on the concrete submit call.

package/docs/concepts/providers-and-runtimes.md

@@ -0,0 +1,53 @@
+---
+title: Providers & runtimes
+description: How provider selection maps to managed runtime execution.
+icon: Network
+---
+
+aex exposes one submission shape across supported providers:
+
+| Provider | Selector |
+| --- | --- |
+| Anthropic | `Providers.ANTHROPIC` |
+| DeepSeek | `Providers.DEEPSEEK` |
+| OpenAI | `Providers.OPENAI` |
+| Gemini | `Providers.GEMINI` |
+| Mistral | `Providers.MISTRAL` |
+| OpenRouter | `Providers.OPENROUTER` |
+| Doubao | `Providers.DOUBAO` |
+| Doubao China | `Providers.DOUBAO_CN` |
+
+All submissions run on the managed runtime. Omit `runtime` or pass
+`runtime: "managed"`; `runtime: "native"` is rejected before any runtime side
+effect.
+
+## Selection
+
+### TypeScript
+
+```ts
+import { Models, Providers } from "@aexhq/sdk";
+
+await aex.submit({
+  provider: Providers.OPENAI,
+  model: Models.GPT_4_1,
+  prompt: "Summarise the attached files.",
+  secrets: { apiKey: process.env.OPENAI_API_KEY! }
+});
+```
+
+### CLI
+
+```bash
+aex run \
+  --api-token "$AEX_API_TOKEN" \
+  --provider openai \
+  --openai-api-key "$OPENAI_API_KEY" \
+  --model gpt-4.1 \
+  --prompt "Summarise the attached files." \
+  --follow
+```
+
+Events, outputs, cleanup, and downloads use the same SDK and CLI surface for
+every provider. For the exact supported model list, use the generated
+[provider/runtime capability matrix](../provider-runtime-capabilities.md).

package/docs/concepts/runs.md

@@ -0,0 +1,40 @@
+---
+title: Runs
+description: The durable unit aex submits, observes, and archives.
+icon: Play
+---
+
+A run is an immutable request to execute an autonomous agent task. The caller
+submits the model, prompt, optional system message, composition primitives,
+output policy, and one inline secrets bundle. aex snapshots the non-secret
+inputs, holds secrets for the run lifecycle, dispatches through the managed
+runtime, and records status, typed events, and outputs.
+
+```ts
+import { AgentExecutor, Models } from "@aexhq/sdk";
+
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+
+const runId = await aex.submit({
+  provider: "anthropic",
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Write the report and save it as a file.",
+  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" });
+```
+
+The same durable record backs SDK and CLI reads. Use `getRun`/`get`, `events`,
+`stream`, `streamEnvelopes`, `wait`, `outputs`, and `download` to inspect the
+run live or after completion.
+
+Use `idempotencyKey` when retrying a submit from your own workflow. aex hashes
+the normalized non-secret submission, so a retry with the same key and same body
+returns the existing run while a mismatched body fails with an idempotency
+conflict.

package/docs/credentials.md

@@ -4,7 +4,9 @@ title: Credentials
 
 # Credentials
 
-aex does not store provider keys or MCP credential values across runs.
+aex treats provider keys, MCP credentials, and proxy endpoint auth as per-run
+credentials. Reusable env secrets are documented separately in
+[Secrets](secrets.md).
 
 The caller passes a workspace-scoped SDK token and the provider key inline on every `submit` call. aex holds the bundle in run-scoped custody for the run lifecycle and attempts terminal cleanup/revocation for the aex-controlled references. MCP credentials and proxy endpoint auth values travel the same way.
 
@@ -100,7 +102,7 @@ node /mnt/session/uploads/aex/aex proxy stripe \
   --response-mode headers_only
 ```
 
-The CLI reads the per-run bearer from `/mnt/session/uploads/aex/run-token`, attaches the `X-Aex-Proxy-Protocol` header, and the BFF injects the bearer/header/query/basic credential before dispatching the outbound call. Only the response (subject to `responseMode` and `maxResponseBytes`) reaches the container. `--response-mode` can only narrow below the policy ceiling.
+The CLI reads the per-run bearer from `/mnt/session/uploads/aex/run-token`, attaches the `X-Aex-Proxy-Protocol` header, and the hosted proxy injects the bearer/header/query/basic credential before dispatching the outbound call. Only the response (subject to `responseMode` and `maxResponseBytes`) reaches the container. `--response-mode` can only narrow below the policy ceiling.
 
 Retries are declaration-based. Add `retry` to the endpoint policy when safe for that upstream; runs without `retry` keep single-attempt behavior. `maxAttempts` counts the initial request, and defaults apply only when `retry` is present: `maxAttempts: 3`, `initialDelayMs: 250`, `maxDelayMs: 5000`, `jitter: "full"`, `retryOnStatuses: [408, 425, 429, 500, 502, 503, 504]`, `retryOnMethods: ["GET", "HEAD"]`, and `respectRetryAfter: true`. There are no per-call `aex proxy` retry flags.
 
@@ -127,7 +129,7 @@ const runId = await aex.submit({
 });
 ```
 
-The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, and redacted. The BFF injects no `Authorization` header and no query-string credential. Shipping a `proxyEndpointAuth` entry for a `none`-shape endpoint is rejected at submission time. Equivalent class-based form:
+The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, and redacted. The hosted proxy injects no `Authorization` header and no query-string credential. Shipping a `proxyEndpointAuth` entry for a `none`-shape endpoint is rejected at submission time. Equivalent class-based form:
 
 ```ts
 import { ProxyEndpoint } from "@aexhq/sdk";
@@ -144,7 +146,9 @@ ProxyEndpoint.none({
 
 ### Networking
 
-When a run uses `limited` networking, the platform host must appear in `allowed_hosts`. The worker injects it automatically; for advance validation use:
+Networking is open by default. When a run explicitly uses `limited` networking,
+the platform host must appear in `allowed_hosts`. aex injects it
+automatically; for advance validation use:
 
 ```ts
 const allowedHosts = buildPlatformAllowedHosts({

package/docs/events.md

@@ -88,6 +88,18 @@ run's last stream event, immediately after the durable record commits.
 `settleConsistent` ends the stream on it; on a raw stream, detect it with
 `isRunSettled(event)`.
 
+## Temporary event archive links
+
+For terminal runs, `eventArchiveLink(runId, options?)` returns a temporary direct URL to `events.jsonl`, the same redacted customer-visible event export used by `downloadEvents(runId)`.
+
+```ts
+const link = await aex.eventArchiveLink(runId, { expiresIn: "1h" });
+const response = await fetch(link.url);
+const jsonl = await response.text();
+```
+
+`expiresIn` accepts seconds or `"15m"`, `"1h"`, or `"1d"`; the default is `"1h"`. The URL is a reusable bearer URL until it expires, so treat it like a short-lived secret. Internal runtime, host, and provider diagnostics are not included in this export.
+
 ## Event shape
 
 Events are typed as the discriminated `RunEvent` union for compatibility and as the versioned coordinator envelope for live consumers. aex records raw runtime/provider payloads **after** secret redaction and structural sanitization, so the bytes you see never contain the provider key, MCP credentials, or proxy bearer that were supplied to `submit`.

package/docs/limits.md

@@ -0,0 +1,53 @@
+---
+title: Limits
+---
+
+# Limits
+
+aex runs autonomous agents on the hosted managed runtime. The SDK and CLI submit
+runs, stream events, capture outputs, and expose auth-gated reads and downloads.
+
+For what the product supports, see [Features](https://aex.dev/docs/features/).
+For the current provider/model set, see the generated
+[provider/runtime capability matrix](provider-runtime-capabilities.md).
+
+## Current Defaults
+
+| Area | Default |
+| --- | --- |
+| Workspace storage | 50 GiB per workspace for captured outputs and workspace artifacts. aex-maintainer admin workspaces may be unlimited for internal dogfooding; this is not a customer entitlement. |
+| Proxy request body | 10 MiB per proxy endpoint unless the endpoint declares a different `maxRequestBytes`. |
+| Proxy timeout | 5 minutes per proxy endpoint unless the endpoint declares a different `timeoutMs`. |
+| Proxy telemetry | Proxy calls emit report-only usage telemetry for call count, failed calls, request bytes, response bytes when known, and duration. Public proxy pricing is not shipped unless documented later. |
+
+## Product Boundaries
+
+| Area | Boundary |
+| --- | --- |
+| Runtime | New submissions run on the managed runtime. `runtime: "native"` is rejected. |
+| 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. |
+| Proxy endpoints | The proxy enforces declared host/path/method/auth policy for calls routed through it. Upstream side effects and data handling remain with the upstream service and customer. |
+| Outputs | Captured outputs, events, and metadata are stored under the run record and downloaded through auth-gated routes. Output content is customer content. |
+| Human review | Runs execute after submission. Cancellation is available, but aex does not pause a run for platform-mediated approval or interactive clarification. |
+| Agent identity | The durable product primitive is the run record. Persistent agent profiles, stateful memory, reusable sessions, and saved agent definitions are out of scope. |
+| Deployment | The supported product is the hosted aex service plus the SDK and CLI. Alternate `baseUrl` values are for local, staging, or hosted aex API planes, not a self-host product promise. |
+| Cost | BYOK provider-token charges accrue to the customer's provider account. aex records report-only telemetry for runtime, storage, and proxy usage; free trials, billing-grade invoices, and public pricing documents are not shipped unless documented later. |
+
+## Provider Policy Links
+
+These links are starting points for provider-owned policy areas; they do not
+create aex guarantees.
+
+- Anthropic API data retention policy: <https://platform.claude.com/docs/en/manage-claude/api-and-data-retention>
+- OpenAI API data controls: <https://platform.openai.com/docs/guides/your-data>
+- Mistral privacy and API data handling: <https://docs.mistral.ai/admin/security-access/privacy>
+- Gemini API data handling: <https://ai.google.dev/gemini-api/docs/logs-policy>
+
+## Unsupported Claims
+
+Do not describe aex as providing true self-host or customer-cloud deployment
+support, provider-wide retention, HIPAA/BAA or data-residency guarantees, free
+trials, a general-purpose sandbox for every downstream service, human-in-the-loop
+approval checkpoints, or persistent agent identity.

package/docs/outputs.md

@@ -77,6 +77,64 @@ const looseReport = await aex.downloadOutput(runId, { path: "report.txt", match:
 console.log(looseReport.byteLength);
 ```
 
+## Finding outputs
+
+`listOutputs(runId, query?)` and its alias `outputs(runId, query?)` can filter the captured output list client-side. Use `findOutputs` when you want discovery to be explicit, or `findOutput` when exactly one file is expected:
+
+```ts
+const images = await aex.findOutputs(runId, { type: "image" });
+const jsonReports = await aex.outputs(runId, {
+  dir: "reports",
+  extension: ".json"
+});
+
+const report = await aex.findOutput(runId, {
+  filename: "summary.json",
+  contentType: "application/json"
+});
+if (report) {
+  const bytes = await aex.downloadOutput(runId, report);
+}
+```
+
+Query fields compose with AND semantics:
+
+| Field | Match |
+| --- | --- |
+| `path` | Exact normalized output path. Leading `/` and `outputs/` are ignored. |
+| `filename` | Basename match, as a string or `RegExp`. |
+| `dir` / `recursive` | Directory prefix. `recursive` defaults to `true`; set `false` for direct children only. |
+| `extension` | Case-insensitive extension, with or without a leading dot. |
+| `contentType` | Exact content type or a prefix wildcard such as `image/*`. |
+| `type` | High-level type: `text`, `json`, `image`, `audio`, `video`, `pdf`, `archive`, `binary`, or `unknown`. |
+
+`findOutput` returns `null` when nothing matches and throws `RunStateError` when the query matches more than one output.
+
+## Temporary output links
+
+Use `outputLink(runId, selectorOrQuery, options?)` when another process, browser, media tag, or downloader needs a direct artifact URL instead of bytes buffered through the SDK. `createOutputLink` remains as the compatibility name.
+
+```ts
+const link = await aex.outputLink(
+  runId,
+  { path: "reports/summary.json" },
+  { expiresIn: "15m" }
+);
+
+console.log(link.url, link.expiresAt);
+```
+
+Selectors can be an output id, an `Output` object, a path selector, or an `OutputQuery`. `expiresIn` accepts seconds or `"15m"`, `"1h"`, or `"1d"`; the default is `"1h"`.
+
+The returned URL is a reusable bearer URL until it expires. Anyone who has it can read that artifact during the TTL. aex does not promise one-time use or early revocation for these direct artifact URLs.
+
+For large files, `fetchOutput` mints the same temporary URL and returns the `Response` from fetching it directly, without adding the SDK API token to that second request:
+
+```ts
+const response = await aex.fetchOutput(runId, { type: "video", filename: /clip\.mp4$/ });
+const stream = response.body;
+```
+
 ## Lifecycle behaviour
 
 `download()` works at any run state — it reads whatever the public endpoints currently expose, so the zip reflects the run as of the call:

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
 
@@ -61,76 +59,76 @@ Status vocabulary: `supported`, `live-unverified`, `rejected`.
 
 ### 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 the run's object-storage directory.
+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.
 
 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 filesystem read/edit, grep/glob/head/tail, open web fetch/search defaults, optional notebook tools, and post-hook repair."
+    },
+    {
+      "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."
+    }
+  ]
+}