@aexhq/sdk 0.13.6

package/docs/outputs.md

@@ -0,0 +1,157 @@
+---
+title: Outputs
+---
+
+# Outputs
+
+Every run produces durable metadata (status, events, snapshots, cleanup state) and an outputs namespace. By default, managed runs capture every regular file the run creates or modifies in the container: the runner snapshots the filesystem just before the agent starts, rescans it when the agent exits, and uploads the delta. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `client.download(runId)` returns the whole run — metadata, events, logs, and captured output bytes — as a zip; the per-namespace verbs (`downloadOutputs` / `downloadLogs` / `downloadEvents` / `downloadMetadata`) return one slice each.
+
+## Quickstart
+
+```ts
+const runId = await client.submitRun({
+  model: "claude-haiku-4-5",
+  prompt: "Produce a report and save it as a file.",
+  secrets: { anthropic: { apiKey } }
+});
+
+await client.wait(runId);
+await client.download(runId, { to: "./run.zip" });
+```
+
+```bash
+aex download <run-id> --out ./run.zip --api-token …
+```
+
+## The four namespaces
+
+A run's downloadable content is organised into four logical namespaces, each with a matching verb. Every zip is assembled **client-side** from the public read endpoints (`getRun` + `listEvents` + `listOutputs` + per-output `/download`) — there is no server-side archive route.
+
+| Namespace | What it holds | Verb | CLI |
+| --- | --- | --- | --- |
+| `outputs` | The run's real deliverables. | `downloadOutputs(runId)` | `download <id> --only outputs` |
+| `logs` | Platform diagnostics in canonical namespaces: `runtime/`, `host/`, `provider-proxy/`, and `control-plane/`. Stored separately from `outputs`, so deliverables stay deliverables-only. | `downloadLogs(runId)` | `download <id> --only logs` |
+| `events` | Typed events (`events.jsonl`) plus log/full-stream JSONL when the event channel opt-ins are available. | `downloadEvents(runId)` | `download <id> --only events` |
+| `metadata` | The run record (`run.json`). | `downloadMetadata(runId)` | `download <id> --only metadata` |
+
+## What `download()` returns
+
+`download(runId)` is the **whole-run** verb — it bundles all four namespaces as top-level folders. It is distinct from `downloadOutput(runId, selector)`, which fetches a single file. Layout:
+
+```
+metadata/run.json     # run record (status, runId, timestamps, snapshot)
+metadata/submission.json # public-safe submission snapshot, when available
+metadata/cost.json    # public cost telemetry, when available
+events/events.jsonl   # typed event-channel records, ordered
+events/logs.jsonl     # log-channel records, when available
+events/all.jsonl      # full unified stream, when available
+outputs/<name>        # one file per deliverable
+logs/<name>           # platform diagnostics
+manifest.json         # RunRecordManifestV1
+```
+
+`manifest.json` is the versioned `RunRecordManifestV1` described in [Run record](run-record.md). It carries:
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` / `runRecordSchemaVersion` | Manifest and run-record contract versions. |
+| `runId` | The run the zip was assembled for. |
+| `namespaces[]` / `files[]` | Namespace inventory and per-file presence state. Optional submission/cost/event-channel files are marked `present` only when the client assembled actual entries; custody remains `pending` until its writer/read path exists. |
+| `outputs[]` / `logs[]` | `{ id, filename, sizeBytes?, contentType? }` — one row per file successfully written under `outputs/` / `logs/`. |
+| `errors[]` | `{ namespace, id, filename, message }` — per-artifact byte fetches that failed during assembly. Best-effort: a failure records an entry here and is skipped from the tree rather than aborting the whole zip. |
+
+The single-namespace verbs return the same per-file bytes at the zip root (e.g. `downloadOutputs(runId)` → `report.txt` + a `manifest.json`; `downloadEvents(runId)` → `events.jsonl` plus optional `logs.jsonl` / `all.jsonl`).
+
+## Downloading one output
+
+`downloadOutput(runId, selector)` returns a `Uint8Array`. Omit the selector to download the whole outputs namespace as a zip; pass an output from `client.outputs(runId)`, an `{ id }`, or a path selector against the listed `Output.filename` values to download one file:
+
+```ts
+const allOutputs = await client.downloadOutput(runId);
+await client.downloadOutput(runId, undefined, { to: "./outputs.zip" });
+
+const report = await client.downloadOutput(runId, { path: "reports/report.txt" });
+console.log(new TextDecoder().decode(report));
+
+const looseReport = await client.downloadOutput(runId, { path: "report.txt", match: "suffix" });
+console.log(looseReport.byteLength);
+```
+
+## 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:
+
+| Run state | Behaviour |
+| --- | --- |
+| `pending` / `queued` / `provisioning` | `metadata/run.json` reflects the early state; `events/` and `outputs/` are typically empty. |
+| `provider_running`, mid-session / `cleaning_up` | Whatever events + outputs have been captured so far. Call again after terminal for the complete set. |
+| `succeeded` / `failed` / `cancelled` / `terminated` | The complete typed event archive + all captured outputs; log/full-stream JSONL are included when the deployed event API serves those channel opt-ins. |
+
+## `outputs.allowedDirs` — override capture roots
+
+```ts
+client.submitRun({
+  /* ... */,
+  outputs: {
+    allowedDirs: ["/workspace/reports", "/workspace/state"]
+  }
+});
+```
+
+When omitted, aex captures the whole filesystem delta. When supplied, `outputs.allowedDirs` is a whitelist that replaces that default with the listed roots. In other words, explicit `outputs.allowedDirs` narrows capture; it does not add paths on top of `/`.
+
+Validation:
+
+- absolute UNIX paths only (`/...`),
+- no `..` segments, no NUL bytes,
+- maximum 32 entries,
+- maximum 512 bytes per entry.
+
+Runtime notes:
+
+- The managed runtime captures files by diffing the filesystem against a baseline snapshot taken just before the agent starts. Platform setup files, installed packages, and materialized inputs are already present before the baseline, so they are excluded by timing.
+- If you pass an explicit root that does not exist by terminal time, that root contributes no files.
+
+## `outputs.deniedDirs` — subtract noise
+
+```ts
+client.submitRun({
+  /* ... */,
+  outputs: {
+    deniedDirs: ["node_modules", "/var/cache", "*.tmp"]
+  }
+});
+```
+
+`outputs.deniedDirs` is subtracted from the capture roots. Entries may be an absolute subtree (`/var/cache`), a bare path segment (`node_modules`), or a `*.ext` extension match. Denied entries beat allowed roots. Platform-mandatory excludes, including pseudo-filesystems and secret/platform paths, always apply and cannot be re-included.
+
+Mechanism (no platform-magical paths — this is honest):
+
+1. The hosted platform materializes the workspace, opens runtime logs, and records a filesystem baseline across the capture roots.
+2. The agent runs normally. There is no extra model turn and no synthetic sync instruction.
+3. When the agent exits, the runner rescans the capture roots and finds files that are new or whose metadata changed.
+4. The runner uploads changed regular files to durable run artifact storage. Diagnostic log paths are routed to `logs`; other paths are routed to `outputs`.
+
+Cost: output capture does not add a model turn. The runner pays a filesystem scan and upload cost near the end of the run.
+
+Capture notes:
+
+- Files over a configured per-file size cap are skipped.
+- Once total file or byte caps are reached, remaining changed files are dropped from upload.
+- Files that vanish between scan and upload are skipped.
+- Upload failures are recorded in runner events/logs. The zip's `manifest.errors[]` only records byte fetches that failed while assembling the download archive.
+
+## Runs without explicit `outputs.allowedDirs`
+
+Metadata still gets the full treatment. aex captures every regular file the run created or modified outside mandatory platform excludes. A run that produces no files still returns a zip with `run.json`, `events.jsonl`, and an empty `outputs/` directory (manifest `outputs: []`).
+
+## Mid-session download semantics
+
+Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the filesystem diff. If you need the full output set, wait for the run to reach terminal status and call `download()` again.
+
+## Safety
+
+- Filenames are sanitized for cross-platform safety; collisions are disambiguated with a short id suffix before the extension.
+- Downloads stay within the requested local directory.
+- The archive endpoint is workspace-scoped (`outputs:read` scope) and rate-limited (`AEX_RATE_LIMIT_RUN_ARCHIVE_PER_MINUTE`, default 30/min/workspace).
+- `manifest.json` never contains file bytes — only ids, paths, sizes, content types.

package/docs/product-boundaries.md

@@ -0,0 +1,57 @@
+---
+title: Product capabilities and boundaries
+---
+
+# Product capabilities and boundaries
+
+aex is the serverless control plane for autonomous agent sessions. It accepts a complete run request, dispatches it to Goose Managed, records ordered events and logs, captures outputs, and exposes auth-gated reads and downloads.
+
+aex is not a custom agent loop, a general-purpose sandbox, an interactive approval system, or a provider compliance layer. True self-host and customer-cloud deployment modes are not supported today.
+
+Start with the generated [provider/runtime capability matrix](provider-runtime-capabilities.md) for supported providers, runtime routing, and evidence pointers.
+
+## Owned by aex today
+
+- Run submission, idempotency, status, cancellation, reads, downloads, and workspace auth.
+- Runtime dispatch through Goose Managed, with unsupported runtime selectors rejected at submission.
+- Ordered event/log capture through the per-run coordinator and durable archive.
+- Output capture into the run record, subject to runtime behavior and storage limits.
+- BYOK provider-key custody for a single run, using the top-level `secrets` carrier and terminal cleanup/revocation attempts for aex-controlled references.
+- Named proxy endpoint policy, auth injection, redaction, call budgets, and audit metadata on the aex-owned proxy path.
+- Default cleanup attempts for tracked aex runtime resources.
+
+## Boundary matrix
+
+| Area | aex-owned behavior | Inherited or customer-owned behavior |
+| --- | --- | --- |
+| Provider and model policy | aex validates the selected provider, injects the run-scoped BYOK credential, and records public-safe runtime events. | Provider retention, training exclusion, zero-retention, HIPAA/BAA, data residency, abuse policy, and pricing are properties of the selected provider account, endpoint, and contract. |
+| Runtime isolation | Goose Managed runs in an isolated managed runtime. aex tracks resources and runs cleanup attempts. | Runtime isolation guarantees belong to the managed runtime provider. |
+| Secrets | Provider keys, MCP credentials, and proxy auth values are supplied inline per run, held in run-scoped custody, excluded from idempotency, and targeted for cleanup/revocation at terminal where aex controls the reference. | Customers choose and rotate their provider keys and MCP/proxy credentials. Provider-side credentials, sessions, and data may have their own retention rules. |
+| MCP servers | aex accepts remote HTTP/SSE MCP servers, validates their declaration, attaches run-scoped credentials, and records access metadata on the aex-controlled edge. | MCP servers are customer-trusted remote systems. aex does not sandbox their downstream behavior or make an untrusted MCP server safe. |
+| Proxy endpoints | The named endpoint proxy enforces declared host/path/method/auth policy and response caps for calls routed through it. | The upstream service's own auth, data handling, side effects, and compliance posture remain with the upstream service and customer. |
+| Outputs and run record | Captured outputs, events, logs, and metadata are stored under the run record and downloaded through auth-gated routes. | Output content is customer content. Storage, deletion, and retention follow the run policy and infrastructure behavior; deletion-proof custody manifests are roadmap work until shipped. |
+| Human review | Runs execute full-auto after submission. Cancellation is available as an abort control. | Required input, approval, and planning happen before submission or after inspecting the completed run record. aex does not pause a run for platform-mediated human approval or interactive clarification. |
+| Agent identity and memory | The durable product primitive is the run record, addressed by run id. | Persistent agent identity, agent profiles, stateful memory, reusable provider sessions, and saved-definition products are out of scope. |
+| Deployment model | The supported product is the hosted aex control plane, plus the SDK and CLI used to submit and inspect runs. | True self-host and customer-cloud deployments are not supported product modes today. Alternate `baseUrl` values are for local, staging, or hosted aex API planes, not a self-host promise. |
+| Cost | BYOK provider-token charges accrue to the customer's provider account. aex can expose run/runtime/output metadata that helps operators reason about usage. | Paid managed-key mode, free trials, billing-grade cost telemetry, public rate cards, margins, and reconciliation are not shipped in the public product unless explicitly documented later. |
+
+## Provider and infrastructure policy links
+
+Use these links as starting points for the policy areas aex does not own:
+
+- 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>
+These links do not create aex guarantees. They identify the provider whose current terms and product behavior must be reviewed for a given workload.
+
+## Non-goals and unsupported claims
+
+Do not describe aex as providing:
+
+- true self-host or customer-cloud deployment support;
+- aex does not provide zero retention, HIPAA, BAA, or data-residency guarantees across providers;
+- aex does not provide a free trial or low-cost managed-key mode;
+- a general-purpose sandbox for every runtime and downstream MCP service;
+- human-in-the-loop approval checkpoints, ask-the-user loops, or interactive resume;
+- persistent agent identity, agent profiles, stateful memory, reusable sessions, or saved agent definitions.

package/docs/provider-runtime-capabilities.md

@@ -0,0 +1,103 @@
+---
+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`.
+
+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`). Runtime selectors: `managed`.
+
+All new submissions run on the managed runtime. Public support facts are listed separately from runtime dispatch facts.
+
+Status vocabulary: `supported`, `live-unverified`, `rejected`.
+
+## Public support
+
+| Provider | Wire value | Status | 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 live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.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 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) |
+
+## Runtime routing
+
+| Provider | Default provider | Auto route | `runtime: "managed"` |
+| --- | --- | --- | --- |
+| `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) |
+
+## Runtime cell evidence
+
+| Provider | Runtime | Status | Ownership | Enforcement path | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| `anthropic` | `managed` | supported | supported | submission parser + managed dispatch | [Installed-SDK live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts) |
+| `deepseek` | `managed` | supported | supported | submission parser + managed dispatch | [Installed-SDK 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) |
+
+## Validation errors
+
+| Code | Docs anchor | Enforcement path | Evidence |
+| --- | --- | --- | --- |
+| `feature_runtime_mismatch` | [managed-unsupported-features](#managed-unsupported-features) | collectManagedUnsupportedFeatures + selectRuntime | [Submission parser and routing parity](../../contracts/test/submission.test.ts) |
+
+### Managed unsupported features
+
+Provider-hosted skill refs such as `Skill.provider(...)` are rejected because new runs dispatch to Goose Managed. Use inline aex skills or remove the provider-hosted ref.
+
+Notes:
+
+- Public status describes provider availability on the SDK surface. 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
+- Auto route: `managed`
+- Docs: [Credentials](credentials.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 live user matrix](../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts); [Runtime support validator](../../contracts/test/runtime-support.test.ts)
+
+### DeepSeek
+
+- Wire provider: `deepseek`
+- Public status: supported
+- Auto route: `managed`
+- Docs: [Credentials](credentials.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 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
+- Auto route: `managed`
+- Docs: [Credentials](credentials.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
+- Auto route: `managed`
+- Docs: [Credentials](credentials.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
+- Auto route: `managed`
+- Docs: [Credentials](credentials.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/quickstart.md

@@ -0,0 +1,110 @@
+---
+title: aex quickstart
+---
+
+# Quickstart
+
+1. Get an aex SDK API token (`ant_…`).
+2. Create `AexClient` — 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.
+
+```ts
+import { AexClient } from "@aexhq/sdk";
+
+const client = new AexClient({
+  apiToken: process.env.AEX_API_TOKEN!
+  // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
+});
+
+const runId = await client.submitRun({
+  model: "claude-haiku-4-5",
+  prompt: "Write a short answer about agent-first SDK design.",
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+
+const run = await client.wait(runId);
+console.log(run.status);
+console.log(await client.outputs(runId));
+```
+
+For reusable, credential-free configs, use an ordinary function:
+
+```ts
+function summarise(topic: string) {
+  return {
+  model: "claude-haiku-4-5",
+  prompt: `Write a short answer about ${topic}.`
+  };
+}
+
+const runId = await client.submitRun({
+  ...summarise("agent-first SDK design"),
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+Or from the shell:
+
+```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." \
+  --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?, proxyEndpoints?, metadata? }`). Both surfaces hit the same aex backend and operate on the same durable run records — pick whichever is most convenient.
+
+## 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` | Anthropic Vault, attached per session |
+| Provider API key | `secrets.<provider>.apiKey` | Required on every `submitRun`; per-run vault entry matching `provider` |
+| Non-secret reference data folders (transcripts, persona docs, PDFs) | `File.fromPath('./customer-folder/')` | Materialized under `/workspace/files/<f_id>/<name>` by default and described in the agent-facing instructions |
+| Executable skill code (a `.pyz` wrapper, scripts, prompts) | `Skill.fromPath('./skills/my-skill/')` | Registered with Anthropic's Skills API; auto-discovered by the agent |
+| 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.
+
+## Safe retries with `idempotencyKey`
+
+Every `submitRun` 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 client.submitRun({
+        model: "claude-haiku-4-5",
+        prompt: "...",
+        idempotencyKey,
+        secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+      });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("network")) continue;
+      throw err;
+    }
+  }
+  throw new Error("submitRun failed after retries");
+}
+```
+
+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.

package/docs/release.md

@@ -0,0 +1,99 @@
+---
+title: Release
+---
+
+# Release
+
+Releases are manually dispatched from `.github/workflows/release.yml` after the
+target version is already on `main`. The npm package version is the release
+source of truth. The workflow publishes to npm and runs post-publish install
+checks, but it does not create git tags or GitHub Releases, keeping the remote
+repository on a clean `main` branch unless tags are added deliberately later.
+
+## How to ship a release
+
+1. Bump both `packages/sdk/package.json#version` and
+   `packages/sdk/src/version.ts` to the next semver.
+2. Land the change on `main` with any companion code or docs.
+3. Confirm CI is green.
+4. Run the **Release** workflow from `main` and choose the npm dist-tag
+   (`latest` or `next`).
+
+If `@aexhq/sdk@<version>` already exists on npm, the release workflow fails before
+publishing. A failed release is fixed by bumping to a higher version and running
+the workflow again.
+
+## Release pipeline
+
+The workflow has two jobs:
+
+1. **`publish`** runs on Ubuntu in the protected `npm-release` environment:
+   - `pnpm install --frozen-lockfile`
+   - npm version availability check for `packages/sdk/package.json#version`
+   - `pnpm lint`
+   - `pnpm test`
+   - `pnpm run docs:build`
+   - `pnpm build`
+   - `pnpm --filter @aexhq/sdk pack`
+   - `pnpm run test:user:offline` against the packed tarball
+   - a final npm version availability check
+   - `pnpm publish --provenance --no-git-checks --access public`
+2. **`post-publish-user-tests`** waits for npm registry visibility, then runs
+   `pnpm run test:user:offline` against the published version on Ubuntu and
+   Windows.
+
+The pre-publish user-test gate catches broken package shape, missing CLI bin,
+workspace dependency leaks, and TypeScript/ESM install regressions before npm
+publish. The post-publish matrix confirms the published registry artifact is
+installable from clean user projects on both Linux and Windows.
+
+## What ships in the tarball
+
+The published tarball is **self-contained**. It declares **zero `@aexhq/*`
+runtime dependencies** and is installable from a clean `npm install @aexhq/sdk`
+with no workspace access:
+
+- `@aexhq/contracts` lives in `packages/sdk/package.json#devDependencies`
+  only. At build time, [`packages/sdk/scripts/inline-contracts.mjs`](../scripts/inline-contracts.mjs)
+  copies `packages/contracts/dist/**` into `packages/sdk/dist/_contracts/` and
+  rewrites `from "@aexhq/contracts"` to `from "./_contracts/index.js"` across
+  the SDK dist tree. A sanity check at the end of that script refuses to finish
+  if any bare `@aexhq/contracts` specifier survives.
+- `@aexhq/cli` is bundled at build time by
+  [`packages/sdk/scripts/bundle-cli.mjs`](../scripts/bundle-cli.mjs) into a
+  single `dist/cli.mjs`, which is the `bin: aex` entry in
+  `packages/sdk/package.json`.
+- This invariant is mechanically enforced by
+  `apps/user-tests/test/offline/install.test.ts` ("declares no @aexhq/*
+  runtime dependencies") before publish.
+
+## Repository setup
+
+Configure npm Trusted Publishing for this repository:
+
+- **Organization or user**: `aexhq`
+- **Repository**: `aex`
+- **Workflow filename**: `release.yml`
+- **Environment name**: `npm-release`
+
+Protect the GitHub `npm-release` environment with the reviewers or deployment
+rules you want before enabling real publishes. No `NPM_TOKEN` secret is
+required when Trusted Publishing is configured.
+
+## Local checklist
+
+Before dispatching a release, the same public-safe checks can be run locally:
+
+```text
+pnpm lint
+pnpm test
+pnpm run test:user:offline
+pnpm run docs:build
+pnpm run pack:sdk
+```
+
+## Rollback
+
+There is no reliable "unpublish and reuse the version" path. npm version numbers
+are effectively immutable for release purposes, so a bad release is fixed by
+publishing a higher version.

package/docs/run-config.md

@@ -0,0 +1,53 @@
+---
+title: Run configuration
+---
+
+# Run configuration
+
+A run config is the credential-free subset of a `submitRun` request that you can keep in code or load from a JSON file. It is not a platform object, saved definition, DSL, trigger, or persistent agent profile. aex only stores the immutable run record created when you submit.
+
+Allowed fields:
+
+- `model` - required.
+- `prompt` - required, string or array of strings.
+- `system` - optional system message.
+- `skills` - array of `SkillRef`, either workspace, provider, or inline.
+- `mcpServers` - array of `McpServerRef`; headers are split into `secrets.mcpServers` server-side.
+- `proxyEndpoints` - array of `PlatformProxyEndpoint`.
+- `environment` - `{ networking?, packages?, envVars? }`. `envVars` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts.
+- `metadata` - non-secret structured metadata.
+
+`agentsMd`, `files`, and `outputs` are top-level `submitRun` options, not run-config fields. They carry bytes or capture behavior that belongs on a concrete run submission.
+
+Secrets never live in run config. Pass credentials through `submitRun({ ...config, secrets })` in the SDK or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`) in the CLI.
+
+## Reuse in code
+
+Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the run parameters you submit.
+
+```ts
+function summarise(topic: string) {
+  return {
+  model: "claude-haiku-4-5",
+  system: "You are a concise automation agent.",
+  prompt: `Write a short answer about ${topic}.`
+  };
+}
+
+await client.submitRun({
+  ...summarise("agent-first SDK design"),
+  secrets: { anthropic: { apiKey } }
+});
+```
+
+## CLI
+
+The `aex run` host subcommand accepts the same run config either as a JSON file:
+
+```bash
+aex run --config ./run.json \
+  --api-token "$AEX_API_TOKEN" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--proxy-endpoint`, `--proxy-auth`, `--metadata`). The two modes are mutually exclusive.

package/docs/run-record.md

@@ -0,0 +1,39 @@
+---
+title: Run record
+---
+
+# Run record
+
+The run record is the durable product primitive for one run id. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured outputs, platform diagnostics, and manifest entries for custody and cost telemetry.
+
+`client.download(runId)` and `aex download <run-id>` return a zip with this layout:
+
+```text
+manifest.json
+metadata/run.json
+metadata/submission.json      # when a public-safe submission snapshot is returned by the read API
+metadata/cost.json            # when public cost telemetry is returned by the read API
+events/events.jsonl
+events/logs.jsonl             # when the event API serves channel=log
+events/all.jsonl              # when the event API serves channel=all
+outputs/<captured deliverable files>
+logs/<platform diagnostic files>
+```
+
+`manifest.json` is versioned as `RunRecordManifestV1`:
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` | `aex.run-record.manifest.v1`. |
+| `runRecordSchemaVersion` | `aex.run-record.v1`. |
+| `runId` | The run the archive was assembled for. |
+| `namespaces[]` | The documented top-level namespaces: `metadata`, `events`, `outputs`, `logs`. |
+| `files[]` | Inventory of expected and present files with `namespace`, `path`, `role`, and `status`. |
+| `outputs[]` / `logs[]` | Compatibility aliases for present captured artifacts. |
+| `errors[]` | Per-artifact byte fetch failures during archive assembly. |
+
+Current v1 downloads always include `metadata/run.json` and `events/events.jsonl`. `events/events.jsonl` contains typed event-channel records only; log-channel or full-stream exports are not mixed into that file. The client also probes the existing event API opt-ins and includes `events/logs.jsonl` / `events/all.jsonl` when `?channel=log` / `?channel=all` prove those streams are available. Older deployments that do not serve those channel reads keep the manifest entries as `unavailable`.
+
+`metadata/submission.json` is present only when the run read shape includes a public-safe submission snapshot. `metadata/cost.json` is present only when the run read shape includes public `costTelemetry`; otherwise cost stays `pending`. `metadata/custody.json` remains `pending` until the custody manifest writer and public read surface land. `events/manifest.json` remains `unavailable` in this client-side slice because there is no public coordinator-manifest download route.
+
+The record boundary is public-safe. It must not contain provider API keys, runner bearers, workspace tokens, signed URLs, raw provider response bodies, R2 object keys, Vault ids, raw query strings, or secret-shaped values. Credentials are supplied per run and vaulted separately for the run lifetime.