@aexhq/sdk 0.40.6 → 0.40.7

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! }
+});
+```

package/docs/concepts/composition.md

@@ -1,40 +1,40 @@
----
-title: Composition
-description: The primitives used to assemble each run.
-icon: Blocks
----
-
-aex composes an agent from explicit per-session inputs. The SDK materializes local
-bytes before the session lands and the platform mounts them into the managed
-runtime before the first agent turn.
-
-| Need | Primitive |
-| --- | --- |
+---
+title: Composition
+description: The primitives used to assemble each run.
+icon: Blocks
+---
+
+aex composes an agent from explicit per-session inputs. The SDK materializes local
+bytes before the session lands and the platform mounts them into the managed
+runtime before the first agent turn.
+
+| Need | Primitive |
+| --- | --- |
 | Instructional skill bundles | `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles` |
-| Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
-| Reference files and folders | `File.fromPath`, `File.fromBytes` |
-| Remote tools | `McpServer.remote`, `McpServer.fromId` |
-| Non-secret runtime settings | `environment.variables`, `environment.packages`, `environment.networking` |
-| Runtime secrets for your code | `Secret.value`, `Secret.ref`, `environment.secrets` |
-
-```ts
+| Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
+| Reference files and folders | `File.fromPath`, `File.fromBytes` |
+| Remote tools | `McpServer.remote`, `McpServer.fromId` |
+| Non-secret runtime settings | `environment.variables`, `environment.packages`, `environment.networking` |
+| Runtime secrets for your code | `Secret.value`, `Secret.ref`, `environment.secrets` |
+
+```ts
 import { AgentsMd, File, McpServer, Models, Secret, Skill } from "@aexhq/sdk";
-
-await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Use the attached docs and tools to produce a report.",
-  agentsMd: [await AgentsMd.fromContent("Follow the repo conventions.", { name: "repo-rules" })],
-  files: [await File.fromPath("./input")],
+
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Use the attached docs and tools to produce a report.",
+  agentsMd: [await AgentsMd.fromContent("Follow the repo conventions.", { name: "repo-rules" })],
+  files: [await File.fromPath("./input")],
   skills: [await Skill.fromDir("./skills/report-writer", { name: "report-writer" })],
-  mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
-  environment: {
-    secrets: { INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!) },
-    networking: { mode: "limited", allowedHosts: ["api.example.com"] }
-  },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-Secrets stay out of reusable configs. Provider keys go in the top-level `apiKeys`
-map; reusable or per-run values for your own code go in `environment.secrets`.
-Your code then makes normal HTTP calls with the standard client for that service.
+  mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
+  environment: {
+    secrets: { INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!) },
+    networking: { mode: "limited", allowedHosts: ["api.example.com"] }
+  },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+Secrets stay out of reusable configs. Provider keys go in the top-level `apiKeys`
+map; reusable or per-run values for your own code go in `environment.secrets`.
+Your code then makes normal HTTP calls with the standard client for that service.

package/docs/concepts/providers-and-runtimes.md

@@ -1,54 +1,54 @@
----
-title: Providers & runtimes
-description: How provider selection maps to managed runtime execution.
-icon: Network
----
-
-aex exposes one submission shape across supported providers:
-
-| Provider | Selector |
-| --- | --- |
-| Anthropic | `Providers.ANTHROPIC` |
-| DeepSeek | `Providers.DEEPSEEK` |
-| OpenAI | `Providers.OPENAI` |
-| Gemini | `Providers.GEMINI` |
-| Mistral | `Providers.MISTRAL` |
-| OpenRouter | `Providers.OPENROUTER` |
-| Doubao | `Providers.DOUBAO` |
-| Doubao China | `Providers.DOUBAO_CN` |
-
-All submissions run on the managed runtime. The optional `runtime` option picks
-a managed machine-size preset — use `Sizes.*` in TypeScript (e.g.
-`runtime: Sizes.SHARED_0_25X_1GB`) or `--runtime-size` in the CLI. Omit it for
-the default size; there is no alternative runtime backend to select.
-
-## Selection
-
-### TypeScript
-
-```ts
-import { Models, Providers } from "@aexhq/sdk";
-
-await aex.run({
-  provider: Providers.OPENAI,
-  model: Models.GPT_4_1,
-  message: "Summarise the attached files.",
-  apiKeys: { openai: process.env.OPENAI_API_KEY! }
-});
-```
-
-### CLI
-
-```bash
-aex run \
-  --api-key "$AEX_API_KEY" \
-  --provider openai \
-  --openai-api-key "$OPENAI_API_KEY" \
-  --model gpt-4.1 \
-  --prompt "Summarise the attached files." \
-  --follow
-```
-
-Events, outputs, cleanup, and downloads use the same SDK and CLI surface for
-every provider. For the exact supported model list, use the generated
-[provider/runtime capability matrix](../provider-runtime-capabilities.md).
+---
+title: Providers & runtimes
+description: How provider selection maps to managed runtime execution.
+icon: Network
+---
+
+aex exposes one submission shape across supported providers:
+
+| Provider | Selector |
+| --- | --- |
+| Anthropic | `Providers.ANTHROPIC` |
+| DeepSeek | `Providers.DEEPSEEK` |
+| OpenAI | `Providers.OPENAI` |
+| Gemini | `Providers.GEMINI` |
+| Mistral | `Providers.MISTRAL` |
+| OpenRouter | `Providers.OPENROUTER` |
+| Doubao | `Providers.DOUBAO` |
+| Doubao China | `Providers.DOUBAO_CN` |
+
+All submissions run on the managed runtime. The optional `runtime` option picks
+a managed machine-size preset — use `Sizes.*` in TypeScript (e.g.
+`runtime: Sizes.SHARED_0_25X_1GB`) or `--runtime-size` in the CLI. Omit it for
+the default size; there is no alternative runtime backend to select.
+
+## Selection
+
+### TypeScript
+
+```ts
+import { Models, Providers } from "@aexhq/sdk";
+
+await aex.run({
+  provider: Providers.OPENAI,
+  model: Models.GPT_4_1,
+  message: "Summarise the attached files.",
+  apiKeys: { openai: process.env.OPENAI_API_KEY! }
+});
+```
+
+### CLI
+
+```bash
+aex run \
+  --api-key "$AEX_API_KEY" \
+  --provider openai \
+  --openai-api-key "$OPENAI_API_KEY" \
+  --model gpt-4.1 \
+  --prompt "Summarise the attached files." \
+  --follow
+```
+
+Events, outputs, cleanup, and downloads use the same SDK and CLI surface for
+every provider. For the exact supported model list, use the generated
+[provider/runtime capability matrix](../provider-runtime-capabilities.md).

package/docs/concepts/runs.md

@@ -1,49 +1,49 @@
----
-title: Runs
-description: The durable unit aex submits, observes, and archives.
-icon: Play
----
-
-A run is a durable, resumable **session**: the model, system message, composition
-primitives, output policy, and per-provider keys you open it with, plus every
-turn you send to it. aex snapshots the non-secret inputs, holds secrets for the
-session lifecycle, dispatches each turn through the managed runtime, and records
-status, typed events, and outputs. Sessions are the low-level API; `run()` is the
-one-shot convenience wrapper over them.
-
-```ts
-import { Aex, Models } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-const session = await aex.openSession({
-  provider: "anthropic",
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-const turn = session.send("Write the report and save it as a file.");
-for await (const event of turn) {
-  console.log(event.type);
-}
-await turn.done();
-
-await session.wait();
-await session.download({ to: "./session.zip" });
-```
-
-The same durable record backs SDK and CLI reads. From the handle use `refresh`,
-`unit`, `wait`, and `download` for lifecycle, plus the grouped read accessors —
-`messages()`, `events()`, and `outputs()` (each with `list()`/`last()`/`first()`,
-and `events().stream()` / `events().streamEnvelopes()` / `outputs().read(...)` for
-streaming and byte-capped reads) — to inspect the session live or after it parks;
-from the client, `aex.sessions.list()` / `aex.sessions.get(id)` read across the
-workspace (CLI mirrors: `aex sessions` and `aex runs` list the workspace's
-sessions/runs newest-first).
-
-Use `idempotencyKey` when retrying `openSession` or `send` from your own
-workflow. aex hashes the normalized non-secret submission, so a retry with the
-same key and same body returns the existing session while a mismatched body fails
-with an idempotency conflict.
-
-aex selects product placement server-side. There is no region selector.
+---
+title: Runs
+description: The durable unit aex submits, observes, and archives.
+icon: Play
+---
+
+A run is a durable, resumable **session**: the model, system message, composition
+primitives, output policy, and per-provider keys you open it with, plus every
+turn you send to it. aex snapshots the non-secret inputs, holds secrets for the
+session lifecycle, dispatches each turn through the managed runtime, and records
+status, typed events, and outputs. Sessions are the low-level API; `run()` is the
+one-shot convenience wrapper over them.
+
+```ts
+import { Aex, Models } from "@aexhq/sdk";
+
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+
+const session = await aex.openSession({
+  provider: "anthropic",
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+const turn = session.send("Write the report and save it as a file.");
+for await (const event of turn) {
+  console.log(event.type);
+}
+await turn.done();
+
+await session.wait();
+await session.download({ to: "./session.zip" });
+```
+
+The same durable record backs SDK and CLI reads. From the handle use `refresh`,
+`unit`, `wait`, and `download` for lifecycle, plus the grouped read accessors —
+`messages()`, `events()`, and `outputs()` (each with `list()`/`last()`/`first()`,
+and `events().stream()` / `events().streamEnvelopes()` / `outputs().read(...)` for
+streaming and byte-capped reads) — to inspect the session live or after it parks;
+from the client, `aex.sessions.list()` / `aex.sessions.get(id)` read across the
+workspace (CLI mirrors: `aex sessions` and `aex runs` list the workspace's
+sessions/runs newest-first).
+
+Use `idempotencyKey` when retrying `openSession` or `send` from your own
+workflow. aex hashes the normalized non-secret submission, so a retry with the
+same key and same body returns the existing session while a mismatched body fails
+with an idempotency conflict.
+
+aex selects product placement server-side. There is no region selector.