@aexhq/sdk 0.36.0 → 0.37.0

package/docs/mcp.md

@@ -20,7 +20,7 @@ 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
+**not** interpose on the transport between the model 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.

package/docs/networking.md

@@ -4,44 +4,64 @@ title: Networking
 
 # Networking
 
-A run executes your agent's code in a sandbox that has **no unmediated route to
-the internet**. Every outbound connection — whether it comes from the model, a
-built-in tool, or a `curl` your code runs in the shell — passes through the
-platform's egress boundary, which enforces the run's networking policy and a
-fixed SSRF deny-list (loopback, link-local, cloud-metadata, and other private
-ranges are always blocked, including hostnames that resolve to those ranges).
-
-**Networking is open by default.** A run that does not set
-`environment.networking` may reach any public host — still subject to the SSRF
-deny-list above — with no allowlist required. You use the `environment.networking`
-field to *narrow* that surface when you want a tighter, auditable egress posture.
-Code cannot widen the policy from inside the container: the boundary is the
-platform's, not the agent's.
+A run executes your agent's code in a sandbox with **no direct route to the
+internet**. Outbound traffic is governed by **two layers**:
+
+1. **The per-run policy (`environment.networking`)** — enforced by the agent
+   runtime *inside the run*. It applies to the standard proxy path every normal
+   HTTP client uses (see below) and can only *narrow* what the run may reach.
+2. **The platform ceiling** — a fixed, platform-managed egress boundary every
+   connection ultimately traverses. It allows the hosts aex itself manages
+   (model providers, built-in tool endpoints, package registries, and related
+   well-known development hosts such as `github.com`) and enforces a fixed SSRF
+   deny-list: loopback, link-local, cloud-metadata, and other private ranges are
+   always blocked, including hostnames that resolve to those ranges.
+
+Honest boundary statement: the per-run `allowedHosts` policy is enforced by the
+run's own runtime on the standard proxy path — it is **not** yet enforced at
+the platform proxy layer. A subprocess that deliberately bypasses the standard
+proxy environment (a raw socket / raw CONNECT) is bounded by the **platform
+ceiling** rather than by the per-run list. Per-run enforcement at the platform
+proxy layer is planned; until it ships, treat `allowedHosts` as a strong
+default-path control and an auditable statement of intent, not a hard isolation
+boundary against adversarial code inside the run.
+
+**Default posture.** A run that does not set `environment.networking` runs in
+`open` mode: its own code may reach anything within the platform ceiling with
+no allowlist required. Use `environment.networking` to *narrow* that surface
+when you want a tighter, auditable egress posture. Code cannot widen the
+ceiling from inside the container.
 
 ## Paths that always work
 
-These reach the network over managed paths and are **not** subject to
+These reach the network over managed platform paths and are **not** subject to
 `environment.networking`, so you never list their hosts:
 
 - The model / provider call for the run (and its subagents).
-- The built-in `web_search` and `web_fetch` tools (still SSRF-guarded).
-- Any remote MCP servers you declare in `mcpServers` — see [MCP](mcp.md).
+- The built-in `web_search` and `web_fetch` tools. They run over a managed,
+  SSRF-guarded server-side path, which is why they can reach arbitrary public
+  URLs even though your own code is bounded by the ceiling.
+- Remote MCP servers you declare in `mcpServers` — MCP traffic rides a managed
+  path; see [MCP](mcp.md).
 - The package registries for any `environment.packages` you declare (pip → PyPI,
   apt → the distribution mirrors). Declaring a package implicitly allows the
   registry it installs from.
 
-`environment.networking` governs the **other** case: arbitrary outbound that
-your own code makes to a host the platform doesn't already manage — a `curl` in
-the `bash` tool, a `requests`/`urllib` call in Python, a `fetch` in
-`code_execution`, or a third-party SDK.
+`environment.networking` governs the **other** case: outbound that your own
+code makes — a `curl` in the `bash` tool, a `requests`/`urllib` call in Python,
+a `fetch` in `code_execution`, or a third-party SDK.
 
 ## Restrict a run to an allowlist
 
 Set `mode: "limited"` and list exactly the hosts your code is allowed to reach.
-Anything not on the list (and not one of the always-allowed paths above) is
-blocked, and the call fails. The platform automatically appends the
-infrastructure hosts aex itself needs, so the model and tool paths keep working
-without you listing them.
+The run's runtime enforces the list on the standard proxy path: a connection to
+a host that is neither on the list nor one of the always-allowed paths above is
+refused before it leaves the run. Package-registry hosts implied by
+`environment.packages` are appended automatically so installs keep working.
+
+Note that `allowedHosts` narrows *within* the platform ceiling — listing a host
+does not by itself make it reachable if the platform ceiling does not carry it.
+If your run needs a host the ceiling blocks, contact support.
 
 ### TypeScript
 
@@ -75,11 +95,11 @@ visible at the same call site as the code that needs it.
 ## Open mode
 
 `open` is the default: a run that omits `environment.networking` already runs in
-open mode. Set `mode: "open"` explicitly when you want to be unambiguous, or when
-a run needs to reach hosts you can't enumerate ahead of time. The run may then
-reach any public host, still subject to the SSRF deny-list. Prefer `limited`
-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).
+open mode. Set `mode: "open"` explicitly when you want to be unambiguous. Open
+mode applies no per-run allowlist — the run's own code may reach anything the
+platform ceiling allows, still subject to the SSRF deny-list. Prefer `limited`
+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.run({
@@ -90,6 +110,9 @@ await aex.run({
 });
 ```
 
+(Web research like the example above flows through the managed `web_search` /
+`web_fetch` path, which is not ceiling-bounded.)
+
 ## Transparent for normal HTTP clients
 
 You write ordinary code — there is no per-request proxy configuration and no
@@ -101,7 +124,7 @@ that honors it — `curl`, Python `requests` / `urllib`, `pip`, `npm`, Node
 ```bash
 # In the agent's shell, against a limited run that allows api.example.com:
 curl -sS https://api.example.com/v1/status   # works
-curl -sS https://other-host.example          # blocked (not in allowlist)
+curl -sS https://other-host.example          # refused (not in allowlist)
 ```
 
 You also do **not** need to install any certificate. The platform manages the
@@ -110,20 +133,23 @@ your client succeeds without extra setup.
 
 ## Limitations and gotchas
 
-- **Enforcement is at the platform boundary, not in your code.** A tool can't
-  bypass the policy by ignoring proxy settings or opening a raw socket — the
-  sandbox has no other route out, so a disallowed host simply fails. This is the
-  intended fail-closed behavior.
+- **The per-run policy is enforced by the run's runtime, not at the platform
+  proxy.** Clients that honor the standard proxy environment (almost all HTTP
+  tooling) are held to the `allowedHosts` list. A subprocess that deliberately
+  ignores the proxy environment and opens a raw connection is **not** held to
+  the per-run list — it is bounded by the platform ceiling (the aex-managed
+  provider/tool/registry host set) and the SSRF deny-list instead. Per-run
+  enforcement at the platform proxy layer is planned.
 - **A client that hard-bypasses the standard environment may fail to connect.**
-  This is rare — almost all HTTP tooling honors `HTTP_PROXY` / `HTTPS_PROXY` and
-  the system trust store. But a client that is explicitly told to ignore the
-  proxy environment, pins or replaces its certificate trust store, or speaks a
-  non-HTTP protocol over a raw socket can hit a wall even for an allowed host.
-  The fix is to let the client use the standard proxy and certificate
-  environment the runtime provides (most libraries do by default), rather than
-  overriding it.
+  A client that ignores the proxy environment, pins or replaces its certificate
+  trust store, or speaks a non-HTTP protocol over a raw socket can hit a wall
+  even for a host you allowed. The fix is to let the client use the standard
+  proxy and certificate environment the runtime provides (most libraries do by
+  default), rather than overriding it.
 - **`allowedHosts` only applies in `limited` mode.** It is ignored in `open`
-  mode, where the SSRF deny-list is the only gate.
+  mode, where the platform ceiling and the SSRF deny-list are the gates.
+- **`allowedHosts` cannot exceed the platform ceiling.** It narrows; it never
+  widens. A listed host outside the ceiling still fails.
 
 For credentialed HTTP calls, pass the credential as an `environment.secrets`
 entry and let your code use its normal HTTP client. For remote tool servers, see

package/docs/outputs.md

@@ -163,9 +163,10 @@ const stream = response.body;
 
 | 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. |
+| `queued` / `claiming` / `provisioning` | `metadata/run.json` reflects the early state; `events/` and `outputs/` are typically empty. |
+| `provider_running`, mid-session / `capturing_outputs` / `cleaning_up` | Whatever events + outputs have been captured so far. Call again after the session parks for the complete set. |
+| `idle` / `suspended` (parked between turns) | The complete archive for every turn sent so far; a later turn appends to it. |
+| `succeeded` / `failed` / `timed_out` / `cancelled` | The complete typed event archive + all captured outputs. |
 
 ## `outputs.allowedDirs` — override capture roots
 

package/docs/public-surface.json

@@ -7,7 +7,7 @@
     "label": "Alpha testing",
     "description": "Access is limited to invited testers while we harden the hosted runtime, dashboard, and SDK workflows."
   },
-  "installCommand": "bun add @aexhq/sdk",
+  "installCommand": "npm i @aexhq/sdk",
   "examples": {
     "typescriptLines": [
       "import { Aex, Models, Sizes } from \"@aexhq/sdk\";",

package/docs/quickstart.md

@@ -7,16 +7,18 @@ title: Quickstart
 ## 1. Install
 
 ```bash
-bun add @aexhq/sdk
+npm i @aexhq/sdk
 ```
 
 This installs the TypeScript SDK exports and the bundled `aex` CLI.
 
 ## 2. Set credentials
 
-In the dashboard, create a quickstart SDK token with `runs:read`, `runs:write`,
-and `outputs:read`. The examples also need your BYOK provider key for the model
-you choose. For the Claude examples below:
+aex is currently in **invite-only beta**: workspaces and API tokens are issued
+by the aex team — contact <support@aex.dev> for beta access. Once you have
+access, create a quickstart SDK token with `runs:read`, `runs:write`, and
+`outputs:read` in the dashboard at <https://aex.dev>. The examples also need
+your BYOK provider key for the model you choose. For the Claude examples below:
 
 ```bash
 export AEX_API_TOKEN="<your-aex-token>"
@@ -28,7 +30,7 @@ export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
 ```ts
 import { Aex, Models, Sizes } from "@aexhq/sdk";
 
-const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
+const aex = new Aex(process.env.AEX_API_TOKEN!);
 
 const session = await aex.openSession({
   model: Models.CLAUDE_HAIKU_4_5,
@@ -108,6 +110,7 @@ aex run \
 ## Add capabilities
 
 - Add files, skills, AGENTS.md, MCP servers, packages, and networking controls with [Composition](concepts/composition.md).
-- Use parent/child run delegation from the [Features](https://aex.dev/docs/features/#subagents) page.
+- Delegate bounded sub-tasks to child runs with [Subagents](concepts/subagents.md).
+- Get notified when a run finishes with [Webhooks](webhooks.md).
 - Narrow output capture or download individual files with [Outputs](outputs.md).
 - Check supported providers and models in the [provider/runtime capability matrix](provider-runtime-capabilities.md).

package/docs/run-config.md

@@ -16,7 +16,7 @@ Allowed fields:
 - `metadata` - non-secret structured metadata.
 - `overrides` - `{ idleTtl?, timeout?, maxSpendUsd? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap (see [Limits & quotas](limits-and-quotas.md)).
 
-`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `tools` entries built with `Tools.fromSkillDir(...)` / `Tools.fromSkillUrl(...)`, so they too are SDK-code options rather than config fields. Subagents run in-process; there is no `limits` / `parentRunId` option.
+`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `tools` entries built with `Tools.fromSkillDir(...)` / `Tools.fromSkillUrl(...)`, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentRunId` option. The wire contract carries a per-run `limits` object (the exported `RunLimits` type: `maxConcurrentChildRuns`, `maxSubagentDepth`, `maxSpendUsd`), but the session surface exposes only its spend dial — set it with `overrides.maxSpendUsd`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
 
 Secrets never live in run config. Pass provider keys through the top-level
 `apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or

package/docs/secrets.md

@@ -88,6 +88,11 @@ const metadata = await aex.secrets.get("serper-api-key");
 
 ## Inject A Workspace Secret Into A Run
 
+> **Availability note:** workspace-secret `Secret.ref(...)` injection requires
+> the next platform deploy — on the current hosted plane the referenced
+> variable can resolve empty inside the run. Per-run `Secret.value(...)`
+> secrets are unaffected. This note will be removed once the deploy lands.
+
 Reference workspace secrets with `Secret.ref(name)`. The value resolves
 server-side and is injected as the named environment variable.
 

package/docs/webhooks.md

@@ -0,0 +1,132 @@
+---
+title: Webhooks
+---
+
+# Webhooks
+
+aex can notify your endpoint when a run finishes. Webhooks are **per-run**: you
+pass a callback URL with the submission, and the platform delivers exactly one
+`run.finished` event to it when the run reaches its terminal state.
+
+> **Availability note:** terminal webhook delivery for session-based runs
+> requires the next platform deploy — on the current hosted plane a session
+> run's webhook may not fire. This note will be removed once the deploy lands.
+
+## Register a callback
+
+```ts
+import { Aex, Models } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_TOKEN!);
+
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  webhook: { url: "https://hooks.example.com/aex" },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+```bash
+aex run \
+  --api-token "$AEX_API_TOKEN" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write the report." \
+  --webhook https://hooks.example.com/aex
+```
+
+The URL must be `https`. The callback URL is an operational concern, not part
+of the submission fingerprint: retrying the same submission with the same
+idempotency key but a different callback URL never conflicts.
+
+## What gets delivered
+
+One POST carrying the terminal `run.finished` event, sent at the
+settle-consistent barrier — when you receive it, the run record is already
+terminal and its outputs are complete and readable. The body is built once at
+settle, frozen, and re-sent byte-identical on every retry or manual redelivery:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "<delivery id — matches the webhook-id header>",
+  "source": "aex",
+  "type": "run.finished",
+  "subject": "<the run id>",
+  "time": "2026-07-02T12:34:56.000Z",
+  "data": {
+    "runId": "<the run id>",
+    "status": "succeeded",
+    "terminalAt": "2026-07-02T12:34:56.000Z",
+    "reason": null,
+    "failureClass": null,
+    "costTelemetry": { "billedCostUsd": 0.42 }
+  }
+}
+```
+
+`reason` / `failureClass` carry the failure detail on non-success terminals;
+`costTelemetry` is present when the billed cost is known.
+
+## Verify deliveries
+
+Deliveries are signed [Standard Webhooks](https://www.standardwebhooks.com/)
+style: HMAC-SHA256 over `` `${webhook-id}.${webhook-timestamp}.${rawBody}` ``,
+sent in three headers — `webhook-id` (stable across retries; your dedupe key),
+`webhook-timestamp` (unix seconds), and `webhook-signature` (a space-delimited
+list of `v1,<base64>` entries).
+
+The signing key is a per-workspace secret. Reveal it (it is created on first
+use) with either surface:
+
+```bash
+aex webhooks secret --api-token "$AEX_API_TOKEN"   # prints whsec_...
+```
+
+```ts
+const { whsec } = await aex.webhookSigningSecret();
+```
+
+Verify inbound requests with the exported `verifyAexWebhook` — pure Web Crypto,
+identical under Bun and Node, and interoperable with the `standardwebhooks`
+reference library:
+
+```ts
+import { verifyAexWebhook } from "@aexhq/sdk";
+
+// In your HTTP handler — use the EXACT raw body bytes, never re-serialize.
+const ok = await verifyAexWebhook({
+  rawBody,
+  headers: request.headers,
+  secret: process.env.AEX_WEBHOOK_SECRET! // the whsec_... value
+});
+if (!ok) return new Response("bad signature", { status: 401 });
+```
+
+`verifyAexWebhook` rejects stale timestamps (default tolerance 300 seconds) and
+compares signatures constant-time. It accepts every `v1` entry in the signature
+list, so it is already rotation-ready — but **server-side rotation of the
+signing secret is not available yet**: `aex webhooks secret` reveals or creates
+the one workspace secret and there is no rotate endpoint today. If your secret
+is compromised, contact <support@aex.dev>.
+
+## Delivery ledger and redelivery
+
+Each run keeps a delivery ledger — attempts, last status code, and last error:
+
+```ts
+const deliveries = await session.webhooks().list();
+await session.webhooks().redeliver(deliveries[0]!.id);
+```
+
+```bash
+aex deliveries <session-id> --api-token "$AEX_API_TOKEN"
+```
+
+Redelivery re-sends the frozen payload with the **same** `webhook-id`, so a
+consumer that dedupes on `webhook-id` handles retries, redeliveries, and
+at-least-once delivery uniformly. An empty ledger means the run carried no
+`webhook` or has not reached a terminal state yet.
+
+For the terminal-event mechanics behind delivery timing, see
+[Events](events.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {