@aexhq/sdk 0.40.6 → 0.40.8

package/docs/authentication.md

@@ -1,125 +1,125 @@
----
-title: Authentication
----
-
-# Authentication
-
-Every SDK and CLI call authenticates with an **aex API key**: a bearer
-credential that is **workspace-scoped** — the workspace is derived server-side
-from the token, so there is no workspace parameter anywhere in the API. A
-request either carries a valid token for a workspace or it is rejected with
-`401 unauthorized` (see [Errors](errors.md)).
-
-## Getting a token (invite-only beta)
-
-aex is currently in **invite-only beta**. Workspaces and their initial API
-tokens are provisioned by the aex team — contact <support@aex.dev> for beta
-access. Once your workspace exists, you can create and delete additional tokens
-in the dashboard at <https://aex.dev>.
-
-## Using a token
-
-Pass the token to the SDK constructor, the CLI's `--api-key` flag, or persist
-it once with `aex login`:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-```
-
-```bash
-npx aex whoami --api-key "$AEX_API_KEY"
-
-# or persist it once, then omit --api-key on later commands:
-npx aex login --api-key "$AEX_API_KEY"
-npx aex whoami
-```
-
-(`new Aex(apiKey)` is the canonical constructor; the equivalent options form is
-documented once in [Credentials](credentials.md).)
-
-The token travels as a standard `Authorization: Bearer` header. Treat it like
-any other secret: keep it in environment variables or a secret manager, never
-in run config, prompts, or committed files.
-
-## Plane routing and the `baseUrl` guard
-
-An aex API key is **self-describing**: it embeds the plane (`dev` / `prd`) and
-region it was minted for. The constructor parses the key and routes accordingly,
-with **zero network**:
-
-- **Omit `baseUrl`** and a `prd` key routes to the canonical hosted API plane
-  (`https://api.aex.dev`). A `dev` key has no stable public host yet, so a dev
-  key with no `baseUrl` throws `CredentialValidationError` asking you to pass one.
-- **Supply a `baseUrl` whose plane disagrees with the key** (e.g. a `dev` key
-  pointed at `https://api.aex.dev`) and the constructor throws
-  `CredentialValidationError` **before any request** — you no longer discover the
-  mismatch as a late `401 token_invalid` after a full round-trip.
-
-```ts
-// prd key → routes to https://api.aex.dev automatically:
-const prd = new Aex(process.env.AEX_PRD_KEY!);
-
-// dev key → pass the dev plane's baseUrl explicitly:
-const dev = new Aex(process.env.AEX_DEV_KEY!, { baseUrl: process.env.AEX_DEV_URL! });
-```
-
-## Scopes
-
-A token carries a set of **scopes**; every API route requires one, and a token
-that lacks the route's scope fails with `403 insufficient_scope` naming the
-missing scope. The customer-grantable scopes:
-
-| Scope | Grants |
-| --- | --- |
-| `runs:read` | Read sessions/runs, their events and event archives, and webhook delivery ledgers. |
-| `runs:write` | Open sessions, send turns, submit runs, suspend/resume, redeliver webhooks, reveal the webhook signing secret. |
-| `runs:cancel` | Cancel a session/run. |
-| `runs:delete` | Delete a session/run record. |
-| `outputs:read` | List, read, download, and mint links for captured outputs. |
-| `files:write` | Upload asset bytes (files, skills, AGENTS.md) staged for a run. |
-| `files:delete` | Delete workspace asset-store entries. |
-| `secrets:read` | List workspace secrets and read their metadata (never values). |
-| `secrets:write` | Create, rotate, and delete workspace secrets. |
-| `mcp:read` | List and read workspace MCP server configurations. |
-| `mcp:write` | Create workspace MCP server configurations. |
-| `mcp:delete` | Delete workspace MCP server configurations. |
-| `billing:read` | Read billing state and create hosted billing sessions. |
-| `workspaces:delete` | Owner self-service workspace hard-erase. |
-
-Tokens may additionally carry the reserved scopes `skills:read` /
-`skills:write` / `skills:delete`, `agentsmd:read` / `agentsmd:write` /
-`agentsmd:delete`, and `files:read`. No API route requires them today — skill
-and AGENTS.md asset uploads are covered by `files:write` — so treat them as
-inert placeholders for future per-asset-type routes.
-
-A typical automation token carries `runs:read`, `runs:write`, and
-`outputs:read`. Grant the rest only where the workload needs them — a read-only
-reporting token, for example, needs no `runs:write`.
-
-## Introspection: `whoami`
-
-`aex.whoami()` (CLI: `aex whoami`) validates the token and returns the
-workspace id, the token's scopes, and — on current platform deployments — a
-`limits` object with the workspace's effective admission caps
-(`maxConcurrentRuns`, `submitRatePerMinute`, `spendCapUsd`, `monthSpendUsd`,
-`balanceUsd`, `balanceGraceFloorUsd`, `paymentMethodStatus`), resolved by the
-same code the submit gates enforce. Use it as a cheap credential check and to
-anticipate `429`/`402` rejections before submitting — see
-[Limits & quotas](limits-and-quotas.md) and [Errors](errors.md).
-
-## Rotation and revocation
-
-- **Rotate** by creating a new token in the dashboard, switching your
-  deployment to it, then deleting the old one. Tokens are independent — both
-  stay valid during the switch, so rotation needs no downtime.
-- **Revoke** by deleting the token in the dashboard; deletion takes effect
-  immediately (allow up to a minute for in-flight caches to expire).
-- Token create/delete are rate-limited per workspace (see
-  [Limits & quotas](limits-and-quotas.md)).
-- If you cannot reach the dashboard (or suspect workspace-level compromise),
-  contact <support@aex.dev>.
-
-Provider keys (`apiKeys`) and runtime secrets are a separate, per-call surface —
-see [Credentials](credentials.md) and [Secrets](secrets.md).
+---
+title: Authentication
+---
+
+# Authentication
+
+Every SDK and CLI call authenticates with an **aex API key**: a bearer
+credential that is **workspace-scoped** — the workspace is derived server-side
+from the token, so there is no workspace parameter anywhere in the API. A
+request either carries a valid token for a workspace or it is rejected with
+`401 unauthorized` (see [Errors](errors.md)).
+
+## Getting a token (invite-only beta)
+
+aex is currently in **invite-only beta**. Workspaces and their initial API
+tokens are provisioned by the aex team — contact <support@aex.dev> for beta
+access. Once your workspace exists, you can create and delete additional tokens
+in the dashboard at <https://aex.dev>.
+
+## Using a token
+
+Pass the token to the SDK constructor, the CLI's `--api-key` flag, or persist
+it once with `aex login`:
+
+```ts
+import { Aex } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+```
+
+```bash
+npx aex whoami --api-key "$AEX_API_KEY"
+
+# or persist it once, then omit --api-key on later commands:
+npx aex login --api-key "$AEX_API_KEY"
+npx aex whoami
+```
+
+(`new Aex(apiKey)` is the canonical constructor; the equivalent options form is
+documented once in [Credentials](credentials.md).)
+
+The token travels as a standard `Authorization: Bearer` header. Treat it like
+any other secret: keep it in environment variables or a secret manager, never
+in run config, prompts, or committed files.
+
+## Plane routing and the `baseUrl` guard
+
+An aex API key is **self-describing**: it embeds the plane (`dev` / `prd`) and
+region it was minted for. The constructor parses the key and routes accordingly,
+with **zero network**:
+
+- **Omit `baseUrl`** and the key routes to its canonical hosted API plane:
+  `prd` keys route to `https://api.aex.dev`, and `dev` keys route to
+  `https://dev-api.aex.dev`.
+- **Supply a `baseUrl` whose plane disagrees with the key** (e.g. a `dev` key
+  pointed at `https://api.aex.dev`) and the constructor throws
+  `CredentialValidationError` **before any request** — you no longer discover the
+  mismatch as a late `401 token_invalid` after a full round-trip.
+
+```ts
+// prd key → routes to https://api.aex.dev automatically:
+const prd = new Aex(process.env.AEX_PRD_KEY!);
+
+// dev key → routes to https://dev-api.aex.dev automatically:
+const dev = new Aex(process.env.AEX_DEV_KEY!);
+```
+
+## Scopes
+
+A token carries a set of **scopes**; every API route requires one, and a token
+that lacks the route's scope fails with `403 insufficient_scope` naming the
+missing scope. The customer-grantable scopes:
+
+| Scope | Grants |
+| --- | --- |
+| `runs:read` | Read sessions/runs, their events and event archives, and webhook delivery ledgers. |
+| `runs:write` | Open sessions, send turns, submit runs, suspend/resume, redeliver webhooks, reveal the webhook signing secret. |
+| `runs:cancel` | Cancel a session/run. |
+| `runs:delete` | Delete a session/run record. |
+| `outputs:read` | List, read, download, and mint links for captured outputs. |
+| `files:write` | Upload asset bytes (files, skills, AGENTS.md) staged for a run. |
+| `files:delete` | Delete workspace asset-store entries. |
+| `secrets:read` | List workspace secrets and read their metadata (never values). |
+| `secrets:write` | Create, rotate, and delete workspace secrets. |
+| `mcp:read` | List and read workspace MCP server configurations. |
+| `mcp:write` | Create workspace MCP server configurations. |
+| `mcp:delete` | Delete workspace MCP server configurations. |
+| `billing:read` | Read billing state and create hosted billing sessions. |
+| `workspaces:delete` | Owner self-service workspace hard-erase. |
+
+Tokens may additionally carry the reserved scopes `skills:read` /
+`skills:write` / `skills:delete`, `agentsmd:read` / `agentsmd:write` /
+`agentsmd:delete`, and `files:read`. No API route requires them today — skill
+and AGENTS.md asset uploads are covered by `files:write` — so treat them as
+inert placeholders for future per-asset-type routes.
+
+A typical automation token carries `runs:read`, `runs:write`, and
+`outputs:read`. Grant the rest only where the workload needs them — a read-only
+reporting token, for example, needs no `runs:write`.
+
+## Introspection: `whoami`
+
+`aex.whoami()` (CLI: `aex whoami`) validates the token and returns the
+workspace id, the token's scopes, and — on current platform deployments — a
+`limits` object with the workspace's effective admission caps
+(`maxConcurrentRuns`, `submitRatePerMinute`, `spendCapUsd`, `monthSpendUsd`,
+`balanceUsd`, `balanceGraceFloorUsd`, `paymentMethodStatus`), resolved by the
+same code the submit gates enforce. Use it as a cheap credential check and to
+anticipate `429`/`402` rejections before submitting — see
+[Limits & quotas](limits-and-quotas.md) and [Errors](errors.md).
+
+## Rotation and revocation
+
+- **Rotate** by creating a new token in the dashboard, switching your
+  deployment to it, then deleting the old one. Tokens are independent — both
+  stay valid during the switch, so rotation needs no downtime.
+- **Revoke** by deleting the token in the dashboard; deletion takes effect
+  immediately (allow up to a minute for in-flight caches to expire).
+- Token create/delete are rate-limited per workspace (see
+  [Limits & quotas](limits-and-quotas.md)).
+- If you cannot reach the dashboard (or suspect workspace-level compromise),
+  contact <support@aex.dev>.
+
+Provider keys (`apiKeys`) and runtime secrets are a separate, per-call surface —
+see [Credentials](credentials.md) and [Secrets](secrets.md).

package/docs/billing.md

@@ -1,118 +1,118 @@
----
-title: Billing & webhook signing secret
----
-
-# Billing & webhook signing secret
-
-Workspace-level billing, subscription, and webhook verification calls are
-token-scoped like every other client call — the workspace is derived
-server-side from the API key.
-
-The billing reads — `aex.billing()`, `aex.billingLedger()`, and the CLI
-`aex billing` (and its `ledger` sub-verb) — require the **`billing:read`**
-scope; a token without it fails with `403 insufficient_scope` (see
-[Errors](errors.md)). This is why the [Quickstart](quickstart.md) mints
-`billing:read` alongside `runs:read` / `runs:write` / `outputs:read`.
-
-## Read the billing summary
-
-`aex.billing()` returns the workspace's prepaid balance, current-month spend,
-and the spend cap enforced on new runs, plus plan fields:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-const billing = await aex.billing();
-console.log(billing.balanceUsd, billing.monthSpendUsd, billing.spendCapUsd);
-```
-
-The returned `BillingSummary` is additive-tolerant: fields a newer deployment
-reports that this SDK version does not know yet pass through on the object
-instead of being rejected.
-
-CLI equivalent:
-
-```bash
-aex billing            # human-readable balance / month spend / spend cap
-aex billing --json     # the raw wire body for scripting
-```
-
-## Manage the subscription
-
-`aex.billingCheckout({ planKey })` creates a hosted checkout session for a paid
-plan. Open the returned URL in a browser; the workspace plan changes after
-checkout completes and the hosted API confirms the subscription.
-
-```ts
-const { url } = await aex.billingCheckout({
-  planKey: "pro",
-  idempotencyKey: crypto.randomUUID()
-});
-console.log(url);
-```
-
-`aex.billingPortal()` creates a hosted billing portal session for the workspace:
-
-```ts
-const { url } = await aex.billingPortal({ returnUrl: "https://aex.dev/billing" });
-console.log(url);
-```
-
-CLI equivalents:
-
-```bash
-aex billing upgrade pro
-aex billing portal
-```
-
-## Read the credit ledger
-
-`aex.billingLedger({ limit })` returns recent credit-ledger rows, newest first —
-allowance grants, adjustments, and run charges with signed `amountUsd` (credits
-positive, charges negative). `limit` is clamped server-side to [1, 100] (default
-25); the read is not cursor-paged.
-
-```ts
-const { entries } = await aex.billingLedger({ limit: 50 });
-for (const entry of entries) {
-  console.log(entry.createdAt, entry.entryType, entry.amountUsd);
-}
-```
-
-CLI equivalent:
-
-```bash
-aex billing ledger --limit 50   # JSON rows, newest first
-```
-
-## Reveal the webhook signing secret
-
-Run webhooks are signed Standard-Webhooks style with a per-workspace secret.
-`aex.webhookSigningSecret()` reveals it (creating one on first use) as the
-`whsec_<base64>` string that `verifyAexWebhook` takes as `secret`:
-
-```ts
-import { Aex, verifyAexWebhook } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-const { whsec } = await aex.webhookSigningSecret();
-
-// In your webhook receiver:
-const verified = await verifyAexWebhook({
-  rawBody,          // the exact request body bytes as a string
-  headers,          // the inbound request headers
-  secret: whsec
-});
-```
-
-Repeat calls return the SAME value — the hosted API does not rotate the
-signing secret. Treat the reveal as sensitive: store it in your secret manager
-and never log it.
-
-CLI equivalent (prints the bare `whsec_...` string, pipeable into a secret
-store; the reveal never goes to stderr or debug traces):
-
-```bash
-aex webhooks secret
-```
+---
+title: Billing & webhook signing secret
+---
+
+# Billing & webhook signing secret
+
+Workspace-level billing, subscription, and webhook verification calls are
+token-scoped like every other client call — the workspace is derived
+server-side from the API key.
+
+The billing reads — `aex.billing()`, `aex.billingLedger()`, and the CLI
+`aex billing` (and its `ledger` sub-verb) — require the **`billing:read`**
+scope; a token without it fails with `403 insufficient_scope` (see
+[Errors](errors.md)). This is why the [Quickstart](quickstart.md) mints
+`billing:read` alongside `runs:read` / `runs:write` / `outputs:read`.
+
+## Read the billing summary
+
+`aex.billing()` returns the workspace's prepaid balance, current-month spend,
+and the spend cap enforced on new runs, plus plan fields:
+
+```ts
+import { Aex } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+const billing = await aex.billing();
+console.log(billing.balanceUsd, billing.monthSpendUsd, billing.spendCapUsd);
+```
+
+The returned `BillingSummary` is additive-tolerant: fields a newer deployment
+reports that this SDK version does not know yet pass through on the object
+instead of being rejected.
+
+CLI equivalent:
+
+```bash
+aex billing            # human-readable balance / month spend / spend cap
+aex billing --json     # the raw wire body for scripting
+```
+
+## Manage the subscription
+
+`aex.billingCheckout({ planKey })` creates a hosted checkout session for a paid
+plan. Open the returned URL in a browser; the workspace plan changes after
+checkout completes and the hosted API confirms the subscription.
+
+```ts
+const { url } = await aex.billingCheckout({
+  planKey: "pro",
+  idempotencyKey: crypto.randomUUID()
+});
+console.log(url);
+```
+
+`aex.billingPortal()` creates a hosted billing portal session for the workspace:
+
+```ts
+const { url } = await aex.billingPortal({ returnUrl: "https://aex.dev/billing" });
+console.log(url);
+```
+
+CLI equivalents:
+
+```bash
+aex billing upgrade pro
+aex billing portal
+```
+
+## Read the credit ledger
+
+`aex.billingLedger({ limit })` returns recent credit-ledger rows, newest first —
+allowance grants, adjustments, and run charges with signed `amountUsd` (credits
+positive, charges negative). `limit` is clamped server-side to [1, 100] (default
+25); the read is not cursor-paged.
+
+```ts
+const { entries } = await aex.billingLedger({ limit: 50 });
+for (const entry of entries) {
+  console.log(entry.createdAt, entry.entryType, entry.amountUsd);
+}
+```
+
+CLI equivalent:
+
+```bash
+aex billing ledger --limit 50   # JSON rows, newest first
+```
+
+## Reveal the webhook signing secret
+
+Run webhooks are signed Standard-Webhooks style with a per-workspace secret.
+`aex.webhookSigningSecret()` reveals it (creating one on first use) as the
+`whsec_<base64>` string that `verifyAexWebhook` takes as `secret`:
+
+```ts
+import { Aex, verifyAexWebhook } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+const { whsec } = await aex.webhookSigningSecret();
+
+// In your webhook receiver:
+const verified = await verifyAexWebhook({
+  rawBody,          // the exact request body bytes as a string
+  headers,          // the inbound request headers
+  secret: whsec
+});
+```
+
+Repeat calls return the SAME value — the hosted API does not rotate the
+signing secret. Treat the reveal as sensitive: store it in your secret manager
+and never log it.
+
+CLI equivalent (prints the bare `whsec_...` string, pipeable into a secret
+store; the reveal never goes to stderr or debug traces):
+
+```bash
+aex webhooks secret
+```

package/docs/concepts/agent-tools.md

@@ -1,66 +1,66 @@
----
-title: Agent tools
-description: The default builtin tools available inside managed runs.
-icon: TerminalSquare
----
-
-Managed runs inject the complete builtin tool set into the agent by default:
-
-- `bash`, `code_execution` — run shell commands / model-written snippets
-- `read_file`, `write_file`, `edit_file` — file read/create/patch
-- `grep`, `glob` — search file contents and paths
-- `head`, `tail` — read bounded file slices
-- `ls`, `stat`, `wc` — list a directory, inspect path metadata, count lines/words/bytes
-- `web_fetch`, `web_search` — fetch a URL / managed web search
-- `todo_write` — maintain a todo list
-- `subagent`, `subagent_result` — delegate to and read back from child runs (see [Subagents](subagents.md))
-- `bash_output`, `bash_kill` — manage background bash jobs
-- `wait`, `git` — bounded idle-yield and first-class git
-
-## Toggling builtins
-
-Set `includeBuiltinTools: false` to inject NO builtins — useful for a pure-MCP
-or pure-custom run where every tool comes from `mcpServers` or `tools`.
-
-`includeBuiltinTools` defaults to `true`.
-
-## Cherry-picking builtins
-
-The `tools` list accepts both custom tool bundles and BUILTIN tool references
-(bare name strings, preferably `BuiltinTools.<name>`). Use builtin references
-to pick a narrow subset alongside `includeBuiltinTools: false`.
-
-The final tool list is ordered: resolved builtin tools, then custom tools, then
-MCP tools.
-
-## Custom tools
-
-Attach your own tool in `tools` as a bundle built with `Tool.fromFiles(...)` (an
-explicit `{ entry, files }`) or `Tool.fromPath(dir)` (a directory with a
-`tool.json` at its root). The bundle's **entry must be a JS module** — a
-`.js`/`.mjs`/`.cjs` file present in the bundle that **default-exports a function
-or an object with an `execute` method**. This is validated at authoring time, so
-a non-JS entry (e.g. a `run.sh`) is rejected right where you build the tool, not
-opaquely mid-run when the runtime's module loader would fail to import it.
-
-Networking is open by default within the platform's managed egress ceiling and
-a fixed SSRF deny-list. `web_fetch` and `web_search` reach the network over a
-managed, SSRF-guarded path that is **not** governed by `environment.networking`,
-so their hosts never need to be listed in a `limited` allowlist. Setting
-`environment.networking.mode` to `limited` restricts only the agent's own
-arbitrary egress (e.g. a `curl` in `bash`); the built-in web tools keep working.
-See [Networking](../networking.md) for the full two-layer model.
-
-## Disable builtins
-
-```ts
-import { Models } from "@aexhq/sdk";
-
-await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Use only the declared MCP tools.",
-  mcpServers,
-  includeBuiltinTools: false,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-```
+---
+title: Agent tools
+description: The default builtin tools available inside managed runs.
+icon: TerminalSquare
+---
+
+Managed runs inject the complete builtin tool set into the agent by default:
+
+- `bash`, `code_execution` — run shell commands / model-written snippets
+- `read_file`, `write_file`, `edit_file` — file read/create/patch
+- `grep`, `glob` — search file contents and paths
+- `head`, `tail` — read bounded file slices
+- `ls`, `stat`, `wc` — list a directory, inspect path metadata, count lines/words/bytes
+- `web_fetch`, `web_search` — fetch a URL / managed web search
+- `todo_write` — maintain a todo list
+- `subagent`, `subagent_result` — delegate to and read back from child runs (see [Subagents](subagents.md))
+- `bash_output`, `bash_kill` — manage background bash jobs
+- `wait`, `git` — bounded idle-yield and first-class git
+
+## Toggling builtins
+
+Set `includeBuiltinTools: false` to inject NO builtins — useful for a pure-MCP
+or pure-custom run where every tool comes from `mcpServers` or `tools`.
+
+`includeBuiltinTools` defaults to `true`.
+
+## Cherry-picking builtins
+
+The `tools` list accepts both custom tool bundles and BUILTIN tool references
+(bare name strings, preferably `BuiltinTools.<name>`). Use builtin references
+to pick a narrow subset alongside `includeBuiltinTools: false`.
+
+The final tool list is ordered: resolved builtin tools, then custom tools, then
+MCP tools.
+
+## Custom tools
+
+Attach your own tool in `tools` as a bundle built with `Tool.fromFiles(...)` (an
+explicit `{ entry, files }`) or `Tool.fromPath(dir)` (a directory with a
+`tool.json` at its root). The bundle's **entry must be a JS module** — a
+`.js`/`.mjs`/`.cjs` file present in the bundle that **default-exports a function
+or an object with an `execute` method**. This is validated at authoring time, so
+a non-JS entry (e.g. a `run.sh`) is rejected right where you build the tool, not
+opaquely mid-run when the runtime's module loader would fail to import it.
+
+Networking is open by default within the platform's managed egress ceiling and
+a fixed SSRF deny-list. `web_fetch` and `web_search` reach the network over a
+managed, SSRF-guarded path that is **not** governed by `environment.networking`,
+so their hosts never need to be listed in a `limited` allowlist. Setting
+`environment.networking.mode` to `limited` restricts only the agent's own
+arbitrary egress (e.g. a `curl` in `bash`); the built-in web tools keep working.
+See [Networking](../networking.md) for the full two-layer model.
+
+## Disable builtins
+
+```ts
+import { Models } from "@aexhq/sdk";
+
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Use only the declared MCP tools.",
+  mcpServers,
+  includeBuiltinTools: false,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```