@aexhq/sdk 0.33.1 → 0.35.0

package/docs/credentials.md

@@ -8,30 +8,28 @@ 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.
+The caller passes a workspace-scoped SDK token and the provider key inline on every `openSession` / `run` call. aex holds the bundle in run-scoped custody for the session lifecycle and attempts terminal cleanup/revocation for the aex-controlled references. MCP credentials and proxy endpoint auth values travel the same way.
 
-A run selects one upstream `provider` (default `anthropic`) and must carry a BYOK
-key for it. Keys are supplied per-provider so a run can also hold keys for the
+A session selects one upstream `provider` (default `anthropic`) and must carry a BYOK
+key for it. Keys are supplied per-provider so a session can also hold keys for the
 **other** providers its subagents may use:
 
 | Field | Required secret |
 | --- | --- |
-| Provider API keys | `secrets.apiKeys` (keyed by provider) |
+| Provider API keys | `apiKeys` (top-level, keyed by provider) |
 
 ```ts
-// The run's own provider key, plus extra keys its subagents can use.
-secrets: {
-  apiKeys: {
-    anthropic: process.env.ANTHROPIC_API_KEY!, // the run's provider
-    deepseek: process.env.DEEPSEEK_API_KEY!     // for a cross-provider subagent
-  }
+// The session's own provider key, plus extra keys its subagents can use.
+apiKeys: {
+  anthropic: process.env.ANTHROPIC_API_KEY!, // the session's provider
+  deepseek: process.env.DEEPSEEK_API_KEY!     // for a cross-provider subagent
 }
 ```
 
 A `subagent` spawned with a different-family model **inherits the parent's keys
-server-side** from the run's vaulted bundle — the keys never transit the
-container. If the parent holds no key for the child's provider, the child submit
-is rejected with `parent_missing_provider_key`.
+server-side** from the session's vaulted bundle — the keys never transit the
+container. If the parent holds no key for the child's provider, the child is
+rejected with `parent_missing_provider_key`.
 
 MCP credential types:
 
@@ -50,64 +48,46 @@ For managed-runtime runs, aex injects the matching BYOK provider key at the host
 
 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.
+The platform's managed HTTP proxy is the agent-first alternative. Declare each endpoint with a `ProxyEndpoint.*` constructor: the instance carries the non-secret **policy** (hashed for idempotency) and its **auth token** together at the call site. The SDK splits the token into the vaulted secrets channel server-side (not hashed, so key rotation does not collapse onto a stale run), and the raw credential value never enters the container.
 
 ```ts
-import {
-  AgentExecutor,
-  Models,
-  validateProxyAuth,
-  buildPlatformAllowedHosts
-} from "@aexhq/sdk";
-
-const aex = new AgentExecutor({
+import { Aex, Models, ProxyEndpoint } from "@aexhq/sdk";
+
+const aex = new Aex({
   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",
-    retry: {
-      maxAttempts: 3,
-      initialDelayMs: 250,
-      maxDelayMs: 5000,
-      jitter: "full",
-      retryOnStatuses: [408, 425, 429, 500, 502, 503, 504],
-      retryOnMethods: ["GET", "HEAD"],
-      respectRetryAfter: true
-    }
+const stripe = ProxyEndpoint.bearer({
+  name: "stripe",
+  baseUrl: "https://api.stripe.com",
+  token: process.env.STRIPE_API_KEY!,
+  allowMethods: ["GET", "POST"],
+  allowPathPrefixes: ["/v1/charges", "/v1/refunds"],
+  maxRequestBytes: 65_536,
+  maxResponseBytes: 65_536,
+  timeoutMs: 10_000,
+  responseMode: "headers_only",
+  retry: {
+    maxAttempts: 3,
+    initialDelayMs: 250,
+    maxDelayMs: 5000,
+    jitter: "full",
+    retryOnStatuses: [408, 425, 429, 500, 502, 503, 504],
+    retryOnMethods: ["GET", "HEAD"],
+    respectRetryAfter: true
   }
-] 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 aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "…",
-  proxyEndpoints,
-  secrets: {
-    apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-    proxyEndpointAuth
-  }
+  message: "…",
+  proxyEndpoints: [stripe],
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
+The five constructors — `ProxyEndpoint.none` / `bearer` / `header` / `basic` / `query` — put the auth secret on the same call as the policy, so any drift (wrong `responseMode`, misnamed auth field) is a TypeScript error at the call site instead of an HTTP 400 a round-trip later.
+
 Inside the run container, every session has the platform CLI mounted at `/mnt/session/uploads/aex/aex` (a Bun-compatible ESM bundle) and a manifest at `/mnt/session/uploads/aex/index.json` describing the declared endpoints. The skill invokes the CLI through `bun` (the mount has no execute permission so direct invocation fails with `bad interpreter: Permission denied`):
 
 ```bash
@@ -123,40 +103,28 @@ Retries are declaration-based. Add `retry` to the endpoint policy when safe for
 
 #### 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 aex.submit({
-  model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "…",
-  proxyEndpoints,
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
-});
-```
-
-The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, and redacted. The hosted proxy injects no `Authorization` header and no query-string credential. Shipping a `proxyEndpointAuth` entry for a `none`-shape endpoint is rejected at submission time. Equivalent class-based form:
+For public APIs that take no credential (Wikimedia Commons, Internet Archive, Library of Congress, NASA Images, NARA, GDELT, etc.), declare the endpoint with `ProxyEndpoint.none(...)` — it produces only a declaration, no auth token:
 
 ```ts
 import { ProxyEndpoint } from "@aexhq/sdk";
 
-ProxyEndpoint.none({
+const wikimedia = ProxyEndpoint.none({
   name: "wikimedia",
   baseUrl: "https://commons.wikimedia.org",
   allowMethods: ["GET"],
   allowPathPrefixes: ["/wiki/", "/w/api.php"]
 });
+
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "…",
+  proxyEndpoints: [wikimedia],
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
 ```
 
+The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, and redacted. The hosted proxy injects no `Authorization` header and no query-string credential.
+
 `bun /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
@@ -174,4 +142,4 @@ const allowedHosts = buildPlatformAllowedHosts({
 
 ### Secrets are always explicit at the call site
 
-There is no `defaultSecrets` and no client-held secret state. Every `submit` 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.
+There is no `defaultSecrets` and no client-held secret state. Every `openSession` / `run` call carries its own credentials at the call site: the top-level `apiKeys` map (one provider key, plus any subagent keys), MCP auth on each `McpServer` instance, and proxy auth on each `ProxyEndpoint` instance. This is the agent-first invariant: the credentials being used on any given call are visible in the same code that opens the session.

package/docs/defaults.md

@@ -21,9 +21,9 @@ For the hard ceilings and who can raise them, see
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| `timeout` (run deadline) | 1 hour | Per-run via `options.timeout` (e.g. `"30m"`, `"2h"`), clamped to the run-timeout floor/ceiling. | `RUN_DEFAULT_TIMEOUT_MS` |
-| `runtimeSize` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-run via `options.runtimeSize` (use `RuntimeSizes.*` in TypeScript). | `RUN_DEFAULT_RUNTIME_SIZE` |
-| `limits.maxSpendUsd` (per-run spend cap) | None — no per-run spend cap (the run is still bounded by its `timeout` and any workspace-level cap) | Per-run via `options.limits.maxSpendUsd` (a positive USD amount); the run is stopped once its spend would exceed the cap. | — |
+| `timeout` (run deadline) | 1 hour | Per-session via `overrides.timeout` (e.g. `"30m"`, `"2h"`), clamped to the run-timeout floor/ceiling. | `RUN_DEFAULT_TIMEOUT_MS` |
+| `runtime` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-session via `runtime` (use `Sizes.*` in TypeScript). | `RUN_DEFAULT_RUNTIME_SIZE` |
+| `overrides.maxSpendUsd` (per-session spend cap) | None — no spend cap (the session is still bounded by its `timeout` and any workspace-level cap) | Per-session via `overrides.maxSpendUsd` (a positive USD amount); the session is stopped once its spend would exceed the cap. | — |
 
 ## Tools
 
@@ -51,15 +51,15 @@ For the hard ceilings and who can raise them, see
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Output link / signed-URL TTL | 300 seconds (5 minutes) at the storage layer; `outputLink(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `outputLink` / `fetchOutput`. | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
+| Output link / signed-URL TTL | 300 seconds (5 minutes) at the storage layer; `session.outputs().link(...)` defaults to `"1h"` | Per-call via `expiresSeconds` (storage) or `expiresIn` on `session.outputs().link` / `session.outputs().fetch`. | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
 | Event-stream connection ticket TTL | 60 seconds | Per-mint via the `ttlMs` argument. | `REQUEST_TICKET_DEFAULT_TTL_MS` |
 
 ## Subagents
 
 | Option | Default | How to override | Source |
 | --- | --- | --- | --- |
-| Concurrent child runs per lineage root | 1000 (live, non-terminal child runs) | Per-run via `options.limits.maxConcurrentChildRuns`, clamped to the 4096 platform ceiling. | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
-| Max subagent depth | 5 | Per-run via `options.limits.maxSubagentDepth`, clamped to the same hard ceiling. | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
+| Concurrent child runs per lineage root | 1000 (live, non-terminal child runs) | Platform default (subagents run in-process; no public per-run override). Hard ceiling 4096. | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
+| Max subagent depth | 5 | Platform default (subagents run in-process; no public per-run override). | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
 
 ## Workspace
 

package/docs/events.md

@@ -12,15 +12,20 @@ tool-approval hook.
 
 ## Two ways to consume events
 
+A session's reads and streams are grouped under accessor sub-resources:
+`session.events()` owns the event timeline, `session.messages()` owns the decoded
+assistant text, and `session.outputs()` owns the captured files. Reach a verb by
+chaining it off the accessor.
+
 ```ts
 // Pull a snapshot of every event captured so far.
-const events = await aex.events(runId);
+const events = await session.events().list();
 ```
 
 ```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 aex.stream(runId, { intervalMs: 1000 })) {
+// session parks. Backed by polling the aex events endpoint.
+for await (const event of session.events().stream({ intervalMs: 1000 })) {
   if (event.type === "TEXT_MESSAGE_CONTENT") {
     // ...
   }
@@ -30,42 +35,57 @@ for await (const event of aex.stream(runId, { intervalMs: 1000 })) {
 For the canonical event envelope, use the coordinator WebSocket stream:
 
 ```ts
-for await (const event of aex.streamEnvelopes(runId, { from: 0 })) {
+for await (const event of session.events().streamEnvelopes({ 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.
+`session.events().streamEnvelopes()` uses a short-lived ticket minted by the hosted API, then subscribes directly to the per-session coordinator. Subscribe means read-from-cursor plus tail: reconnects resume from the last sequence.
+
+## Assistant text
+
+To collect just the agent's assistant messages, use the `messages()` accessor —
+`list()` returns every decoded `AssistantTextEntry` oldest-first, and
+`last()`/`first()` return one entry (or `undefined` when empty). Read `.text`
+for the string:
+
+```ts
+const lastText = (await session.messages().last())?.text;
+```
+
+`decodeAssistantText`, `textOf`, and `summarizeRunTrace` remain exported as the
+power-user escape hatch over a raw `RunEvent` list, but "get the last message"
+is now `await session.messages().last()`.
 
 The CLI mirrors the same surface:
 
 ```bash
-aex events  <run-id> --api-token … [--aex-url …]                      # snapshot (polling)
-aex events  <run-id> --follow [--timeout 8m] --api-token … [--aex-url …]  # stream until terminal (polling)
-aex tail    <run-id> [--json] [--filter <type|source>] [--logs] [--settle] [--timeout 8m] --api-token …  # live, human-readable, over the WS envelope stream
-aex inspect <run-id> [--json] [--filter <type|source>] [--logs] [--timeout 8m] --api-token …             # one-shot full timeline + jump-to-failure + cost/usage
-aex wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …          # block, print final run
+aex events  <session-id> --api-token … [--aex-url …]                      # snapshot (polling)
+aex events  <session-id> --follow [--timeout 8m] --api-token … [--aex-url …]  # stream until the session parks (polling)
+aex tail    <session-id> [--json] [--filter <type|source>] [--logs] [--settle] [--timeout 8m] --api-token …  # live, human-readable, over the WS envelope stream
+aex inspect <session-id> [--json] [--filter <type|source>] [--logs] [--timeout 8m] --api-token …             # one-shot full timeline + jump-to-failure + cost/usage
+aex wait    <session-id> [--timeout 8m] [--interval 2s] --api-token …          # block, print final session
 ```
 
 `aex tail` and `aex inspect` consume the same coordinator WebSocket envelope
-stream as `streamEnvelopes()` (replay-from-cursor + tail + exactly-once resume),
-so they are the low-latency equivalents of `events --follow`'s polling. `--json`
-is the raw-NDJSON escape hatch; `--filter` keeps only the named AG-UI types
-(`TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, …) or sources (`agent`/`runtime`/…);
-a `RUN_ERROR` is surfaced as a jump-to-failure line. `aex inspect` adds a header,
-a settle-consistent full timeline, and a cost/usage footer. Both exit `0`
-succeeded / `1` other terminal / `3` timeout. They need a global `WebSocket`
-(Bun or Node ≥ 22).
-
-`aex wait` is the host mirror of `aex.wait(runId)` / `aex.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 `submit()` or
-a session message is accepted replays the events it missed, then continues live.
+stream as `session.events().streamEnvelopes()` (replay-from-cursor + tail +
+exactly-once resume), so they are the low-latency equivalents of
+`events --follow`'s polling. `--json` is the raw-NDJSON escape hatch; `--filter`
+keeps only the named AG-UI types (`TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, …)
+or sources (`agent`/`runtime`/…); a `RUN_ERROR` is surfaced as a jump-to-failure
+line. `aex inspect` adds a header, a settle-consistent full timeline, and a
+cost/usage footer. Both exit `0` parked cleanly / `1` error park / `3` timeout.
+They need a global `WebSocket` (Bun or Node ≥ 22).
+
+`aex wait` is the host mirror of `session.wait()`:
+it polls until the session parks and prints the final `Session` record. Exit `0`
+when the session parked cleanly (`idle`/`suspended`), `1` for any other park
+(`error` / a non-clean 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 a session
+message is accepted replays the events it missed, then continues live.
 
 ## Session turn events
 
@@ -90,36 +110,37 @@ collected session turn. The returned `runId` is the session id.
 
 ## Terminal events vs. the run record
 
-The low-level `submit()` run path emits a terminal **event** — `RUN_FINISHED`
+A session turn emits a terminal **event** — `RUN_FINISHED`
 (success) or `RUN_ERROR` — when
 the agent's stream ends. This is an AG-UI *render-complete* signal: the runner
-emits it **before** aex commits the authoritative run record, so a `getRun(runId)`
-issued the instant you observe `RUN_FINISHED` can still read `status: "running"`
-for a moment. Treat the terminal event as the lowest-latency "stop the spinner"
-signal — **not** a read-consistency barrier.
+emits it **before** aex commits the authoritative session record, so an
+`aex.sessions.get(id)` issued the instant you observe `RUN_FINISHED` can still
+read a non-parked status for a moment. Treat the terminal event as the
+lowest-latency "stop the spinner" signal — **not** a read-consistency barrier.
 
 Two facts make this easy to work with:
 
 - **Outputs are already durable at the terminal event.** The runner uploads every
-  output before it emits the terminal event, and `listOutputs(runId)` / downloads
+  output before it emits the terminal event, and `session.outputs().list()` / downloads
   read object storage directly — so the moment you see `RUN_FINISHED` the outputs
   are complete and readable.
-- **The run _record_ settles a beat later.** To read the authoritative status
+- **The session _record_ settles a beat later.** To read the authoritative status
   consistently, don't key off the terminal event — use one of:
 
 ```ts
-// Low-level run record path: submit + wait.
-const runId = await aex.submit(runConfig);
-const sameRun = await aex.waitForRun(runId); // or wait on an already-submitted run for the bare Run record
+// Session record path: send a turn, then wait for the session to park.
+const session = await aex.openSession(config);
+await session.send("Continue the task.").done();
+const record = await session.wait(); // the parked session record
 ```
 
 ```ts
 // Live events AND a settle-consistent end: the iterator keeps reading past
 // RUN_FINISHED until the post-mirror barrier, so the record is terminal when it ends.
-for await (const event of aex.streamEnvelopes(runId, { settleConsistent: true })) {
+for await (const event of session.events().streamEnvelopes({ settleConsistent: true })) {
   // render events live…
 }
-const run = await aex.getRun(runId); // guaranteed terminal here
+const settled = await aex.sessions.get(session.id); // guaranteed terminal here
 ```
 
 Under the hood the coordinator broadcasts one `aex.run.settled` CUSTOM event as a
@@ -129,10 +150,10 @@ run's last stream event, immediately after the durable record commits.
 
 ## Temporary event archive links
 
-For terminal runs, `eventArchiveLink(runId, options?)` returns a temporary direct URL to `events.jsonl`, the same redacted customer-visible event export used by `downloadEvents(runId)`.
+For terminal runs, `session.events().archiveLink(options?)` returns a temporary direct URL to `events.jsonl`, the same redacted customer-visible event export used by `session.events().download()`.
 
 ```ts
-const link = await aex.eventArchiveLink(runId, { expiresIn: "1h" });
+const link = await session.events().archiveLink({ expiresIn: "1h" });
 const response = await fetch(link.url);
 const jsonl = await response.text();
 ```
@@ -141,7 +162,7 @@ const jsonl = await response.text();
 
 ## Event shape
 
-Events are typed as the discriminated `RunEvent` union for compatibility and as the versioned coordinator envelope for live consumers. aex records raw runtime/provider payloads **after** secret redaction and structural sanitization, so the bytes you see never contain the provider key, MCP credentials, or proxy bearer that were supplied to `submit`.
+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 when the session was opened.
 
 ## Typed helpers
 
@@ -166,7 +187,7 @@ import {
 
 All guards test the `type` discriminant at runtime. `isTextMessage`,
 `isToolCallStart`, `isToolCallResult`, and `isRunFinished` operate on the loose
-`RunEvent` snapshot (`listEvents` / `RunResult.events`) and additionally NARROW
+`RunEvent` snapshot (`session.events().list()` / `RunResult.events`) and additionally NARROW
 `event.data` to the fields that event type carries — e.g. inside
 `if (isTextMessage(e))`, `e.data.text` is typed `string`. The lifecycle/channel
 guards (`isRunStarted`, `isRunError`, `isCustom`, `isLog`, …) operate on the

package/docs/limits-and-quotas.md

@@ -29,10 +29,9 @@ And whether you can **raise** it: per-run option, per-plan, or no.
 | Maximum run timeout | 6 hours | aex policy | Per plan (billing-driven) | `RUN_MAX_TIMEOUT_MS` |
 | Minimum run timeout | 1 minute | aex policy | No (floor) | `RUN_MIN_TIMEOUT_MS` |
 | Per-call exec timeout (default) | 30 minutes | aex policy | Per-call via the tool call's `timeoutMs` | `RUN_DEFAULT_EXEC_TIMEOUT_MS` |
-| Post-hook timeout (default) | 60 minutes | aex policy | Per-run via the hook's `timeoutMs` | `RUN_DEFAULT_POST_HOOK_TIMEOUT_MS` |
 | MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
 | MCP call timeout (default) | 30 minutes | aex policy | Per-port via `callTimeoutMs` | `RUN_DEFAULT_MCP_CALL_TIMEOUT_MS` |
-| Per-run spend cap | None by default; when set, the run is stopped once its spend would exceed the cap | aex policy | Per-run via `options.limits.maxSpendUsd` (a positive USD amount) | — |
+| Per-session spend cap | None by default; when set, the session is stopped once its spend would exceed the cap | aex policy | Per-session via `overrides.maxSpendUsd` (a positive USD amount) | — |
 
 ### Output capture (per run)
 
@@ -61,8 +60,8 @@ silently lost.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Max subagent depth (public submit / `subagent` tool) | 5 (a depth-5 lineage may not spawn deeper) | aex policy | Per-run via `options.limits.maxSubagentDepth` (clamped to this hard ceiling) | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
-| Concurrent child runs per lineage root | 1000 live (non-terminal); hard ceiling 4096 | aex policy | Per-run via `options.limits.maxConcurrentChildRuns` (clamped to the 4096 ceiling) | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
+| Max subagent depth (`subagent` tool) | 5 (a depth-5 lineage may not spawn deeper) | aex policy | No public per-run override (subagents run in-process) | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
+| Concurrent child runs per lineage root | 1000 live (non-terminal); hard ceiling 4096 | aex policy | No public per-run override (subagents run in-process) | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
 
 ### Retention (per run)
 

package/docs/mcp.md

@@ -13,7 +13,7 @@ Rules:
 - 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.
+- Bearer/OAuth-style auth is carried by the `McpServer` instance (its `headers`); the SDK splits it into the vaulted secrets channel server-side.
 
 Use allowlists for sensitive servers whenever possible.
 
@@ -29,8 +29,8 @@ 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.
+1. Package the upstream as a skill-tool (`Tools.fromSkillDir` /
+   `Tools.fromSkillUrl`) — 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,

package/docs/networking.md

@@ -47,21 +47,21 @@ without you listing them.
 ### TypeScript
 
 ```ts
-import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+import { Aex, Models, Providers } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
 
-await aex.submit({
+await aex.run({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Fetch the public status page and summarize it.",
+  message: "Fetch the public status page and summarize it.",
   environment: {
     networking: {
       mode: "limited",
       allowedHosts: ["api.example.com", "status.example.com"]
     }
   },
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
@@ -92,11 +92,11 @@ whenever you can name the hosts — it gives the run a stable, auditable, least-
 privilege egress surface (it is the tighter posture, not the default).
 
 ```ts
-await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Research the topic across the open web.",
+  message: "Research the topic across the open web.",
   environment: { networking: { mode: "open" } },
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```