@aexhq/sdk 0.13.6

package/dist/skill.js

@@ -0,0 +1,169 @@
+import { SKILL_NAME_PATTERN } from "./_contracts/index.js";
+import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+import { fetchSkillArchive } from "./fetch-archive.js";
+import { readDirectoryAsFiles } from "./node-fs.js";
+/**
+ * One `Skill` class for skill bytes. `client.submitRun` materializes the bytes
+ * as an uploaded asset before the run lands; the wire ref becomes
+ * `kind:"asset"`.
+ *
+ * Build from an inline files map (`Skill.fromFiles`), a local directory
+ * (`Skill.fromPath`), or a remote zip archive over a signed URL
+ * (`Skill.fromUrl`). All three converge on the same canonical bundle, so
+ * identical content dedups across sources.
+ *
+ * Asset deduplication makes the same bytes a no-op upload on subsequent runs.
+ * There is no `Skill.fromId(...)` and no `.upload(client)` — a URL is an
+ * ingestion source, not a persistent reference.
+ */
+export class Skill {
+    #ref;
+    #inlineBytes;
+    #consumed = false;
+    /**
+     * Internal constructor. Use `Skill.fromFiles` or `Skill.fromPath` to create
+     * instances.
+     */
+    constructor(ref, inlineBytes) {
+        this.#ref = ref;
+        this.#inlineBytes = inlineBytes;
+    }
+    /**
+     * The wire-level reference. Returns the SDK-private draft shape for
+     * un-materialized skills (kind:"draft", with name + contentHash).
+     * `client.submitRun` walks these and uploads them before the run
+     * lands.
+     */
+    get ref() {
+        return this.#ref;
+    }
+    /** True for local-bytes Skills that haven't been uploaded yet. */
+    get isDraft() {
+        return this.#ref.kind === "draft" && !this.#consumed;
+    }
+    get isConsumed() {
+        return this.#consumed;
+    }
+    /**
+     * Build a draft Skill from an inline files map. The SDK validates
+     * basic safety (no path traversal, size caps, has `SKILL.md`),
+     * deterministically zips the bundle, and computes the
+     * `sha256:<hex>` content hash. `client.submitRun` materializes
+     * these before the run lands.
+     */
+    static async fromFiles(args) {
+        if (!args || typeof args !== "object") {
+            throw new Error("Skill.fromFiles: args is required");
+        }
+        if (typeof args.name !== "string" || !SKILL_NAME_PATTERN.test(args.name)) {
+            throw new Error(`Skill.fromFiles: name must match ${SKILL_NAME_PATTERN.source}`);
+        }
+        const bundled = bundleSkillFiles(args.files);
+        const contentHash = await hashSkillBundle(bundled.zip);
+        const ref = {
+            kind: "draft",
+            name: args.name,
+            contentHash
+        };
+        return new Skill(ref, bundled.zip);
+    }
+    /**
+     * Read a local directory and build a draft Skill. Symlinks and
+     * non-regular files are skipped. Node-only.
+     */
+    static async fromPath(rootDir, args) {
+        const files = await readDirectoryAsFiles(rootDir);
+        return Skill.fromFiles({ name: args.name, files });
+    }
+    /**
+     * Fetch a zip-archived skill from a URL and build a draft Skill. The archive
+     * is downloaded in the SDK process, so the URL is caller-controlled — host
+     * the skill yourself and pass a temporary signed URL (e.g. an S3 presigned
+     * URL). Its bytes are optionally integrity-checked against `sha256`, unzipped,
+     * and reduced to the same files map as `Skill.fromFiles` — so a URL-sourced
+     * skill and the identical local skill produce the same canonical asset and
+     * dedup against each other.
+     *
+     * The archive must contain `SKILL.md` at its root, or inside a single
+     * top-level folder (which is stripped). The signed URL only needs to be valid
+     * for this call; `client.submitRun` snapshots the bytes into the run.
+     *
+     * Universal (Node 18+ / browser): requires a global `fetch`, or pass one.
+     */
+    static async fromUrl(url, args) {
+        if (!args || typeof args !== "object") {
+            throw new Error("Skill.fromUrl: args is required");
+        }
+        if (typeof args.name !== "string" || !SKILL_NAME_PATTERN.test(args.name)) {
+            throw new Error(`Skill.fromUrl: name must match ${SKILL_NAME_PATTERN.source}`);
+        }
+        const files = await fetchSkillArchive(url, {
+            ...(args.sha256 !== undefined ? { sha256: args.sha256 } : {}),
+            ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+            ...(args.fetch !== undefined ? { fetch: args.fetch } : {})
+        });
+        return Skill.fromFiles({ name: args.name, files });
+    }
+    /**
+     * Reference a skill already uploaded to the workspace catalog
+     * (`aex skills upload` / `operations.createSkillBundle`) in a run.
+     *
+     * A catalog skill's bytes are a content-addressed asset, so referencing it
+     * is just an `{ kind:"asset" }` ref — once a run snapshots the bytes, it is
+     * the identical normalized flow as an inline or file-sourced skill. Pass the
+     * `Skill` record returned by `client.skills.list()` / `.get()`:
+     *
+     *   const [s] = await client.skills.list();
+     *   await client.submitRun({ ..., skills: [Skill.fromCatalog(s)] });
+     *
+     * The record must be `ready` (it has a content hash). Unlike the draft
+     * builders this performs no upload — the bytes already live in the catalog.
+     */
+    static fromCatalog(record) {
+        if (!record || typeof record !== "object") {
+            throw new Error("Skill.fromCatalog: a catalog skill record is required");
+        }
+        if (typeof record.name !== "string" || !SKILL_NAME_PATTERN.test(record.name)) {
+            throw new Error(`Skill.fromCatalog: record.name must match ${SKILL_NAME_PATTERN.source}`);
+        }
+        const rawHash = typeof record.hash === "string" ? record.hash : "";
+        const hashHex = rawHash.startsWith("sha256:") ? rawHash.slice("sha256:".length) : rawHash;
+        if (!/^[0-9a-f]{64}$/.test(hashHex)) {
+            throw new Error("Skill.fromCatalog: record.hash must be a sha256 digest — only `ready` catalog skills are referenceable");
+        }
+        const ref = { kind: "asset", assetId: `asset_${hashHex}`, name: record.name };
+        return new Skill(ref);
+    }
+    /**
+     * Internal: yield the draft's bytes + metadata so `client.submitRun`
+     * can upload the asset. After this returns, the Skill is marked consumed
+     * so a second submitRun call against the same instance throws
+     * (avoid silently re-uploading; explicit re-construction is the
+     * supported retry pattern).
+     *
+     * Returns undefined for already-materialized Skills.
+     */
+    _takeDraftBundle() {
+        if (this.#consumed) {
+            throw new Error("Skill: cannot reuse a consumed Skill in submitRun. Build a fresh Skill via " +
+                "Skill.fromPath(...) / Skill.fromFiles(...) per submitRun call.");
+        }
+        if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
+            return undefined;
+        }
+        this.#consumed = true;
+        return {
+            name: this.#ref.name,
+            contentHash: this.#ref.contentHash,
+            bytes: this.#inlineBytes
+        };
+    }
+    toJSON() {
+        if (this.#ref.kind === "draft") {
+            throw new Error("Skill: draft Skills cannot be JSON-serialised — they only become wire refs when " +
+                "client.submitRun uploads the bytes as an asset.");
+        }
+        return this.#ref;
+    }
+}
+//# sourceMappingURL=skill.js.map

package/dist/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAInB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IACP,IAAI,CAA2B;IAC/B,YAAY,CAAyB;IAC9C,SAAS,GAAG,KAAK,CAAC;IAElB;;;OAGG;IACH,YAAoB,GAA6B,EAAE,WAAwB;QACzE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,kEAAkE;IAClE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,IAA2D;QAChF,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,oCAAoC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvD,MAAM,GAAG,GAAkB;YACzB,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW;SACZ,CAAC;QACF,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAe,EAAE,IAA+B;QACpE,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAClD,OAAO,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,CAClB,GAAW,EACX,IAKC;QAED,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,kCAAkC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE;YACzC,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,WAAW,CAAC,MAAgE;QACjF,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CAAC,6CAA6C,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1F,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAa,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QACxF,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,gBAAgB;QACd,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,6EAA6E;gBAC3E,gEAAgE,CACnE,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACrD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;YACpB,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW;YAClC,KAAK,EAAE,IAAI,CAAC,YAAY;SACzB,CAAC;IACJ,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,kFAAkF;gBAClF,iDAAiD,CAClD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Single source of truth for the SDK version exposed at runtime.
+ *
+ * Must match `packages/sdk/package.json`'s `version` field — a unit
+ * test asserts this. Bump both on every release.
+ *
+ * Used by the (future) User-Agent header on outbound SDK requests.
+ */
+export declare const SDK_VERSION = "0.13.6";

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * Single source of truth for the SDK version exposed at runtime.
+ *
+ * Must match `packages/sdk/package.json`'s `version` field — a unit
+ * test asserts this. Bump both on every release.
+ *
+ * Used by the (future) User-Agent header on outbound SDK requests.
+ */
+export const SDK_VERSION = "0.13.6";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC"}

package/docs/cleanup.md

@@ -0,0 +1,38 @@
+---
+title: Cleanup
+---
+
+# Cleanup
+
+aex schedules cleanup after a run reaches a terminal status. There is no
+opt-out for aex-owned cleanup attempts: tracked runtime resources such as
+Fly machines, scratch state, cached files, and run-scoped secret references are
+reclaimed when possible or surfaced through `cleanupStatus` when cleanup cannot
+complete.
+
+The hosted product uses managed runtimes for all supported providers. Reusable
+provider-session retention is not a supported run option, and the removed
+retention field is rejected if supplied.
+
+```ts
+const runId = await client.submitRun({
+  model: "claude-haiku-4-5",
+  prompt: "...",
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+## `cleanupStatus` values
+
+`cleanupStatus` reports the aggregate state of our cleanup work across the
+run's tracked resources. It is one of:
+
+- `not_started` - terminal not yet reached, or no resources to clean.
+- `pending` / `running` - cleanup is queued or in progress.
+- `succeeded` - tracked cleanup work completed for the resources aex
+  controls.
+- `failed_retryable` - a step failed in a way the cleanup worker will retry.
+- `failed_terminal` - a step failed past retries; manual intervention may be
+  needed.
+- `skipped` - cleanup was not applicable for a tracked resource, or the
+  resource was already absent.

package/docs/credentials.md

@@ -0,0 +1,153 @@
+---
+title: Credentials
+---
+
+# Credentials
+
+aex does not store provider keys or MCP credential values across runs.
+
+The caller passes a workspace-scoped SDK token and exactly one matching provider key inline on every `submitRun` 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.
+
+Provider keys are coupled to the submitted `provider`:
+
+| `provider` | Required secret |
+| --- | --- |
+| `anthropic` | `secrets.anthropic.apiKey` |
+| `deepseek` | `secrets.deepseek.apiKey` |
+| `openai` | `secrets.openai.apiKey` |
+| `gemini` | `secrets.gemini.apiKey` |
+| `mistral` | `secrets.mistral.apiKey` |
+
+Supplying a key for any other provider is rejected at submission time.
+
+MCP credential types:
+
+- `static_bearer`;
+- `oauth_access_token`.
+
+Unsupported:
+
+- arbitrary headers;
+- OAuth refresh;
+- persisted aex vault.
+
+For Goose Managed runs, aex injects the matching BYOK provider key at the hosted provider-proxy. Provider-side sessions and data remain subject to the selected provider account's retention and deletion policies.
+
+## Proxy endpoints (per-run custom HTTP credentials)
+
+Some skills need to call non-MCP HTTP services (e.g. Stripe, internal APIs). Embedding the credential in the skill content puts the raw secret on disk in the agent container and in the model's context — both prompt-injection-readable.
+
+The platform's managed HTTP proxy is the agent-first alternative. The caller declares **policy** at the top level of the submission (hashed for idempotency) and supplies the matching **auth value** inside `secrets` (not hashed, so key rotation does not collapse onto a stale run). The raw credential value never enters the container.
+
+```ts
+import {
+  AexClient,
+  validateProxyAuth,
+  buildPlatformAllowedHosts
+} from "@aexhq/sdk";
+
+const client = new AexClient({
+  apiToken: "ant_..."
+});
+
+const proxyEndpoints = [
+  {
+    name: "stripe",
+    baseUrl: "https://api.stripe.com",
+    authShape: { type: "bearer" },
+    allowMethods: ["GET", "POST"],
+    allowPathPrefixes: ["/v1/charges", "/v1/refunds"],
+    maxRequestBytes: 65_536,
+    maxResponseBytes: 65_536,
+    timeoutMs: 10_000,
+    responseMode: "headers_only",
+    perCallBudget: 60,
+    responseByteBudget: 1_048_576
+  }
+] as const;
+
+const proxyEndpointAuth = [
+  {
+    name: "stripe",
+    value: { type: "bearer", token: process.env.STRIPE_API_KEY! }
+  }
+] as const;
+
+// Fail fast at submission time when policy and auth disagree.
+validateProxyAuth(proxyEndpoints, proxyEndpointAuth);
+
+const runId = await client.submitRun({
+  model: "claude-haiku-4-5",
+  prompt: "…",
+  proxyEndpoints,
+  secrets: {
+    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
+    proxyEndpointAuth
+  }
+});
+```
+
+Inside the run container, every session has the platform CLI mounted at `/mnt/session/uploads/aex/aex` (a Node ESM bundle) and a manifest at `/mnt/session/uploads/aex/index.json` describing the declared endpoints. The skill invokes the CLI through `node` (the mount has no execute permission so direct invocation fails with `bad interpreter: Permission denied`):
+
+```bash
+node /mnt/session/uploads/aex/aex proxy stripe \
+  --method GET \
+  --path /v1/charges/ch_123 \
+  --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.
+
+#### Keyless upstreams (`authShape: { type: "none" }`)
+
+For public APIs that take no credential (Wikimedia Commons, Internet Archive, Library of Congress, NASA Images, NARA, GDELT, etc.), declare the endpoint with `authShape: { type: "none" }` and omit the matching `proxyEndpointAuth[]` entry entirely:
+
+```ts
+const proxyEndpoints = [
+  {
+    name: "wikimedia",
+    baseUrl: "https://commons.wikimedia.org",
+    authShape: { type: "none" },
+    allowMethods: ["GET"],
+    allowPathPrefixes: ["/wiki/", "/w/api.php"]
+  }
+] as const;
+
+const runId = await client.submitRun({
+  model: "claude-haiku-4-5",
+  prompt: "…",
+  proxyEndpoints,
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, redacted, and counted against per-run budgets. 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:
+
+```ts
+import { ProxyEndpoint } from "@aexhq/sdk";
+
+ProxyEndpoint.none({
+  name: "wikimedia",
+  baseUrl: "https://commons.wikimedia.org",
+  allowMethods: ["GET"],
+  allowPathPrefixes: ["/wiki/", "/w/api.php"]
+});
+```
+
+`node /mnt/session/uploads/aex/aex --help` reads endpoint details from `/mnt/session/uploads/aex/index.json`. Runs that do not declare any `proxyEndpoints` still have the CLI and an empty manifest mounted, so agents never need to introspect whether the surface exists.
+
+### Networking
+
+When a run uses `limited` networking, the platform host must appear in `allowed_hosts`. The worker injects it automatically; for advance validation use:
+
+```ts
+const allowedHosts = buildPlatformAllowedHosts({
+  baseUrl: "https://api.aex.dev",
+  extraHosts: ["api.stripe.com"]
+});
+```
+
+### Secrets are always explicit at the call site
+
+There is no `defaultSecrets` and no client-held secret state. Every `submitRun` call carries its full `secrets` bundle (one provider key + optional MCP credentials + optional `proxyEndpointAuth`). This is the agent-first invariant: the credentials being used on any given call are visible in the same line of code that submits the run.
+

package/docs/events.md

@@ -0,0 +1,76 @@
+---
+title: Events
+---
+
+# Events
+
+aex runs agent sessions on Goose Managed. Runs are **non-blocking**: the managed runtime advances the agent while aex observes lifecycle state, maps runtime output into one event shape, and persists every captured event. The SDK and CLI observe the durable event timeline from aex — there is no in-process tool-approval hook.
+
+## Two ways to consume events
+
+```ts
+// Pull a snapshot of every event captured so far.
+const events = await client.events(runId);
+```
+
+```ts
+// Stream the RunEvent snapshot shape: yields each event once, stops when the
+// run reaches a terminal status. Backed by polling the aex events endpoint.
+for await (const event of client.stream(runId, { intervalMs: 1000 })) {
+  if (event.type === "agent.message") {
+    // ...
+  }
+}
+```
+
+For the canonical event envelope, use the coordinator WebSocket stream:
+
+```ts
+for await (const event of client.streamEnvelopes(runId, { from: 0 })) {
+  console.log(event.sequence, event.type, event.source);
+}
+```
+
+`streamEnvelopes()` uses a short-lived ticket minted by the hosted API, then subscribes directly to the per-run coordinator. Subscribe means read-from-cursor plus tail: reconnects resume from the last sequence.
+
+The CLI mirrors the same surface:
+
+```bash
+aex events <run-id> --api-token … [--aex-url …]                      # snapshot
+aex events <run-id> --follow [--timeout 8m] --api-token … [--aex-url …]  # stream until terminal
+aex wait   <run-id> [--timeout 8m] [--interval 2s] --api-token …          # block, print final run
+```
+
+`aex wait` is the host mirror of `client.wait(runId)` / `client.waitForRun(runId)`:
+it polls until the run reaches a terminal status and prints the final `Run`
+record. Exit `0` when the run `succeeded`, `1` for any other terminal status,
+and `3` when `--timeout` elapses first (a `--timeout` on `events --follow` /
+`run --follow` uses the same exit-`3` convention). Durations accept `ms`/`s`/`m`/`h`
+suffixes or a bare millisecond integer.
+
+Both surfaces observe the same events. A subscriber attached after `submitRun()` returns replays the events it missed, then continues live.
+
+## 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 `submitRun`.
+
+## Typed helpers
+
+The package exports conservative type guards that narrow normalized aex event envelopes:
+
+```ts
+import {
+  isRunStarted,
+  isRunFinished,
+  isRunError,
+  isRunTerminal,
+  isTextMessage,
+  isToolCallStart,
+  isToolCallResult,
+  isCustom,
+  isLog,
+  isEventChannel
+} from "@aexhq/sdk";
+```
+
+They narrow only the discriminant. Payload field shapes stay `unknown` until callers parse them, and provider-specific payloads remain behind the normalized envelope.

package/docs/mcp.md

@@ -0,0 +1,47 @@
+---
+title: MCP
+---
+
+# MCP
+
+MCP support is remote HTTPS/SSE only. Stdio MCP servers are rejected because aex is a remote session dispatcher, not a local process supervisor.
+
+Rules:
+
+- MCP servers are declared in the run request config (`mcpServers`).
+- Runtime HITL is disabled.
+- Tool policy must be configured before session start.
+- Enabled MCP tools use `always_allow` provider permissions.
+- `always_ask` is not used by aex MVP.
+- Bearer/OAuth-style auth is passed in the per-run `secrets.mcpServers` bundle.
+
+Use allowlists for sensitive servers whenever possible.
+
+## Large-payload responses
+
+aex is a session dispatcher, not an MCP runtime. We intentionally do
+**not** interpose on the transport between Claude and an upstream MCP
+server, so we cannot elide MCP responses or write them to the session
+filesystem on the user's behalf. Anything an MCP tool returns lands
+directly in the model's context.
+
+For ingestion-style tools that return large JSON blobs (search results,
+catalogue dumps, bulk reads), use the **CLI-as-skill + managed proxy**
+pattern instead of MCP:
+
+1. Package the upstream as a `Skill` — a CLI binary the agent invokes
+   with its bash tool.
+2. Route every upstream HTTPS call through a per-run `ProxyEndpoint`
+   (audit, byte caps, budget enforcement).
+3. Have the CLI write the full payload to the session filesystem. By default,
+   files it creates or modifies are captured automatically; pass
+   `outputs.allowedDirs` only when you want to narrow capture to specific roots.
+   Return only a small handle (path, item count, summary) to the model.
+
+The agent sees the handle in context; the bytes ride out through
+`download()` as a normal captured output.
+
+If you genuinely want everything in context (small responses, code
+search, etc.), use MCP. If the payload would blow your context budget,
+the CLI-as-skill pattern is the supported answer — there is no platform
+flag to elide MCP responses.