@aexhq/sdk 0.24.0 → 0.25.0

package/dist/tool.js

@@ -0,0 +1,138 @@
+import { TOOL_NAME_PATTERN, normaliseSkillBundlePath } from "./_contracts/index.js";
+import { bundleToolFiles, hashSkillBundle } from "./bundle.js";
+import { readDirectoryAsFiles } from "./node-fs.js";
+export class Tool {
+    #ref;
+    #inlineBytes;
+    #consumed = false;
+    constructor(ref, inlineBytes) {
+        this.#ref = ref;
+        this.#inlineBytes = inlineBytes;
+    }
+    get ref() {
+        return this.#ref;
+    }
+    get isDraft() {
+        return this.#ref.kind === "draft" && !this.#consumed;
+    }
+    get isConsumed() {
+        return this.#consumed;
+    }
+    static async fromFiles(args) {
+        if (!args || typeof args !== "object") {
+            throw new Error("Tool.fromFiles: args is required");
+        }
+        const manifest = normalizeToolManifest("Tool.fromFiles", args);
+        const bundled = bundleToolFiles(args.files, manifest);
+        const contentHash = await hashSkillBundle(bundled.zip);
+        const ref = {
+            kind: "draft",
+            assetId: `asset_${contentHash.slice("sha256:".length)}`,
+            contentHash,
+            ...manifest
+        };
+        return new Tool(ref, bundled.zip);
+    }
+    static async fromPath(rootDir) {
+        const files = await readDirectoryAsFiles(rootDir);
+        const rawManifest = files["tool.json"];
+        if (rawManifest === undefined) {
+            throw new Error('Tool.fromPath: tool.json is required at the tool bundle root');
+        }
+        const text = typeof rawManifest === "string" ? rawManifest : new TextDecoder().decode(rawManifest);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`Tool.fromPath: tool.json is not valid JSON: ${err.message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("Tool.fromPath: tool.json must be an object");
+        }
+        const { ["tool.json"]: _manifest, ...bundleFiles } = files;
+        return Tool.fromFiles({
+            ...parsed,
+            files: bundleFiles
+        });
+    }
+    static fromAsset(ref) {
+        return new Tool(normalizeToolRef("Tool.fromAsset", ref));
+    }
+    _takeDraftBundle() {
+        if (this.#consumed) {
+            throw new Error("Tool: cannot reuse a consumed Tool in submit. Build a fresh Tool via Tool.fromPath(...) / Tool.fromFiles(...) per submit call.");
+        }
+        if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
+            return undefined;
+        }
+        this.#consumed = true;
+        const { kind: _kind, contentHash, ...ref } = this.#ref;
+        return {
+            ref: { kind: "asset", ...ref },
+            contentHash,
+            bytes: this.#inlineBytes
+        };
+    }
+    async upload(client) {
+        const bundle = this._takeDraftBundle();
+        if (!bundle) {
+            throw new Error("Tool.upload: only draft Tools can be uploaded. A Tool.fromAsset(...) is already materialized.");
+        }
+        const uploaded = await client._uploadAsset({
+            bytes: bundle.bytes,
+            hash: bundle.contentHash,
+            contentType: "application/zip"
+        });
+        return new Tool({ ...bundle.ref, assetId: uploaded.assetId });
+    }
+    toJSON() {
+        if (this.#ref.kind === "draft") {
+            throw new Error("Tool: draft Tools cannot be JSON-serialised — they only become wire refs when client.submit uploads the bytes as an asset.");
+        }
+        return this.#ref;
+    }
+}
+function normalizeToolManifest(source, input) {
+    const name = input.name;
+    if (typeof name !== "string" || !TOOL_NAME_PATTERN.test(name)) {
+        throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
+    }
+    if (name.includes("__")) {
+        throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
+    }
+    const description = input.description;
+    if (typeof description !== "string" || description.trim().length === 0 || description.length > 2048) {
+        throw new Error(`${source}: description must be non-empty and <= 2048 chars`);
+    }
+    const inputSchema = input.inputSchema ?? input.input_schema;
+    if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+        throw new Error(`${source}: inputSchema must be a JSON Schema object`);
+    }
+    if (inputSchema.type !== "object") {
+        throw new Error(`${source}: inputSchema.type must be "object"`);
+    }
+    const entry = normaliseSkillBundlePath(input.entry);
+    return {
+        name,
+        description,
+        input_schema: inputSchema,
+        entry
+    };
+}
+function normalizeToolRef(source, ref) {
+    const manifest = normalizeToolManifest(source, {
+        name: ref.name,
+        description: ref.description,
+        input_schema: ref.input_schema,
+        entry: ref.entry
+    });
+    if (ref.kind !== "asset") {
+        throw new Error(`${source}: ref.kind must be "asset"`);
+    }
+    if (typeof ref.assetId !== "string" || !/^asset_[A-Za-z0-9_-]{8,128}$/.test(ref.assetId)) {
+        throw new Error(`${source}: ref.assetId must be an asset id`);
+    }
+    return { kind: "asset", assetId: ref.assetId, ...manifest };
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.24.0";
+export declare const SDK_VERSION = "0.25.0";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.24.0";
+export const SDK_VERSION = "0.25.0";
 //# sourceMappingURL=version.js.map

package/docs/concepts/agent-tools.md

@@ -0,0 +1,48 @@
+---
+title: Agent tools
+description: The default machine tools available inside managed runs.
+icon: TerminalSquare
+---
+
+Managed runs expose a fixed set of machine tools to the agent. They are on by
+default. Omit `builtins` or pass any non-empty list to keep them; pass
+`builtins: []` for a pure-MCP run with no machine tools. MCP-derived tools and
+subagent tools are separate surfaces.
+
+## Filesystem and shell
+
+- `bash` runs shell commands in the run container.
+- `read_file`, `write_file`, and `edit_file` read, write, or patch files.
+- `grep` and `glob` search file contents and paths.
+- `head` and `tail` read bounded file slices.
+
+## Background commands
+
+`bash` can run detached with `run_in_background: true`. The agent can then poll
+with `bash_output` or stop the job with `bash_kill`. This is useful for dev
+servers, long builds, and log tails.
+
+## Planning, notebooks, and web
+
+- `todo_write` records the agent's current task list.
+- `notebook_edit` edits Jupyter `.ipynb` cells as JSON.
+- `web_fetch` fetches a URL and returns readable text.
+- `web_search` performs managed web search without requiring a caller-supplied
+  search key.
+
+Networking policy still applies. Under limited networking, fetched hosts and
+the managed search host must be allowed by the run's networking configuration.
+
+## Disable machine tools
+
+```ts
+import { Models } from "@aexhq/sdk";
+
+await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Use only the declared MCP tools.",
+  mcpServers,
+  builtins: [],
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```

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.
 

package/docs/limits.md

@@ -0,0 +1,44 @@
+---
+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).
+
+## 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. Managed-key billing, free trials, billing-grade cost telemetry, 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/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)