@aexhq/sdk 0.40.6 → 0.40.8

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.

package/docs/concepts/subagents.md

@@ -1,88 +1,88 @@
----
-title: Subagents
-description: Delegate bounded sub-tasks to child agent runs with the subagent tool.
-icon: GitFork
----
-
-A run can delegate bounded sub-tasks to **child agent runs** with the built-in
-`subagent` tool. Delegation is agent-driven: the model decides to fan work out,
-each child is a real run with its own record, and the parent collects results
-as the children finish. There is no client-side parent/child API — lineage is
-session-internal.
-
-## How the tool works
-
-The agent calls `subagent` with a `prompt` and a `model` (both required), plus
-optional `system`, `provider`, `runtimeSize`, `timeout`,
-`includeBuiltinTools`, `tools` (builtin-tool names for the child), `skills`,
-and `files`. The call is **always async**: on a successful spawn it returns
-immediately with the child run id, and the parent keeps working while the child
-runs. When a child settles, the parent is notified in its loop, and it reads
-the child's status and captured outputs on demand with the companion
-`subagent_result` tool.
-
-Children inherit the parent's vaulted BYOK provider keys server-side — the
-child submission carries no secrets. Include a provider key for every provider
-your subagents may use when you open the parent session (a parent holding no
-key for the child's provider gets a clear `parent_missing_provider_key` tool
-error). See [Credentials](../credentials.md).
-
-## Depth and breadth limits
-
-Delegation is bounded by two server-enforced lineage limits:
-
-| Limit | Value | Behavior at the limit |
-| --- | --- | --- |
-| Max depth | **5** — the root run is depth 0 and may spawn down to depth 5; a depth-5 run may not spawn further | The spawn is rejected with a `depth_exceeded` tool error (the parent keeps running). |
-| Concurrent children per lineage root | **1000** live (non-terminal) descendants by default; hard platform ceiling **4096** | Further spawns are refused until a child settles. |
-
-The whole descendant subtree of one root shares a single depth and breadth
-budget, enforced server-side at every level — a grandchild spawn counts against
-the same root budget as a direct child. Values are mirrored in
-[Limits & quotas](../limits-and-quotas.md).
-
-## Where children run: `in-process` vs `container`
-
-By default a child runs **in-process**: it executes as a sibling agent process
-inside the parent's own machine, sharing the parent's CPU, memory, and
-lifetime. This is the platform default shipped today.
-
-- **No extra runtime cost.** The parent's machine is the billable unit, so
-  in-process children bill **$0 of additional runtime** — fan-out is priced by
-  the parent box, however many children it hosts. (Model-token spend is still
-  whatever each child's provider calls cost on your BYOK key.)
-- **Shared capacity.** N children share the parent's fixed CPU/memory. For
-  large fan-outs, size the parent up (`runtime`) rather than assuming each
-  child gets its own machine.
-- **Joined lifecycle.** The parent's terminal waits for its in-process children,
-  and their results are folded into the parent's per-child accounting. Platform
-  recovery re-spawns in-process children exactly once if the parent's machine
-  is replaced mid-run — settled children are never re-run.
-
-The escape valve is `host: "container"`: the child is dispatched to its **own
-isolated machine** with its own runtime size and its own runtime billing, and
-the parent does not host it. Use it when a child needs guaranteed capacity,
-isolation from the parent's filesystem/CPU, or a different machine size than
-the parent can share.
-
-## Lineage and observability
-
-Every child — in-process or container — is a first-class run record:
-
-- The parent's transcript logs each spawn with the child's run id.
-- Each child has its own status, typed event timeline, and captured outputs.
-  The child's events and outputs are readable by id
-  (`aex.sessions.outputs(id)` in the SDK, or the CLI's `aex events` /
-  `aex outputs`). Child runs are not served by the session read surface
-  today — `aex.sessions.get(id)` / `aex sessions` / the CLI's `aex status`
-  answer `not_found` for a child id.
-- The child's outputs are handed back to the parent via `subagent_result`, and
-  they remain independently downloadable after the lineage finishes.
-
-## Bounding delegation
-
-- Turn delegation off for a run by cherry-picking builtins without `subagent`
-  (see [Agent tools](agent-tools.md)) or setting `includeBuiltinTools: false`.
-- A per-session spend cap (`overrides.maxSpendUsd`) bounds the parent's spend.
-- The depth/breadth limits above are platform defaults and are not settable
-  per-session today.
+---
+title: Subagents
+description: Delegate bounded sub-tasks to child agent runs with the subagent tool.
+icon: GitFork
+---
+
+A run can delegate bounded sub-tasks to **child agent runs** with the built-in
+`subagent` tool. Delegation is agent-driven: the model decides to fan work out,
+each child is a real run with its own record, and the parent collects results
+as the children finish. There is no client-side parent/child API — lineage is
+session-internal.
+
+## How the tool works
+
+The agent calls `subagent` with a `prompt` and a `model` (both required), plus
+optional `system`, `provider`, `runtimeSize`, `timeout`,
+`includeBuiltinTools`, `tools` (builtin-tool names for the child), `skills`,
+and `files`. The call is **always async**: on a successful spawn it returns
+immediately with the child run id, and the parent keeps working while the child
+runs. When a child settles, the parent is notified in its loop, and it reads
+the child's status and captured outputs on demand with the companion
+`subagent_result` tool.
+
+Children inherit the parent's vaulted BYOK provider keys server-side — the
+child submission carries no secrets. Include a provider key for every provider
+your subagents may use when you open the parent session (a parent holding no
+key for the child's provider gets a clear `parent_missing_provider_key` tool
+error). See [Credentials](../credentials.md).
+
+## Depth and breadth limits
+
+Delegation is bounded by two server-enforced lineage limits:
+
+| Limit | Value | Behavior at the limit |
+| --- | --- | --- |
+| Max depth | **5** — the root run is depth 0 and may spawn down to depth 5; a depth-5 run may not spawn further | The spawn is rejected with a `depth_exceeded` tool error (the parent keeps running). |
+| Concurrent children per lineage root | **1000** live (non-terminal) descendants by default; hard platform ceiling **4096** | Further spawns are refused until a child settles. |
+
+The whole descendant subtree of one root shares a single depth and breadth
+budget, enforced server-side at every level — a grandchild spawn counts against
+the same root budget as a direct child. Values are mirrored in
+[Limits & quotas](../limits-and-quotas.md).
+
+## Where children run: `in-process` vs `container`
+
+By default a child runs **in-process**: it executes as a sibling agent process
+inside the parent's own machine, sharing the parent's CPU, memory, and
+lifetime. This is the platform default shipped today.
+
+- **No extra runtime cost.** The parent's machine is the billable unit, so
+  in-process children bill **$0 of additional runtime** — fan-out is priced by
+  the parent box, however many children it hosts. (Model-token spend is still
+  whatever each child's provider calls cost on your BYOK key.)
+- **Shared capacity.** N children share the parent's fixed CPU/memory. For
+  large fan-outs, size the parent up (`runtime`) rather than assuming each
+  child gets its own machine.
+- **Joined lifecycle.** The parent's terminal waits for its in-process children,
+  and their results are folded into the parent's per-child accounting. Platform
+  recovery re-spawns in-process children exactly once if the parent's machine
+  is replaced mid-run — settled children are never re-run.
+
+The escape valve is `host: "container"`: the child is dispatched to its **own
+isolated machine** with its own runtime size and its own runtime billing, and
+the parent does not host it. Use it when a child needs guaranteed capacity,
+isolation from the parent's filesystem/CPU, or a different machine size than
+the parent can share.
+
+## Lineage and observability
+
+Every child — in-process or container — is a first-class run record:
+
+- The parent's transcript logs each spawn with the child's run id.
+- Each child has its own status, typed event timeline, and captured outputs.
+  The child's events and outputs are readable by id
+  (`aex.sessions.outputs(id)` in the SDK, or the CLI's `aex events` /
+  `aex outputs`). Child runs are not served by the session read surface
+  today — `aex.sessions.get(id)` / `aex sessions` / the CLI's `aex status`
+  answer `not_found` for a child id.
+- The child's outputs are handed back to the parent via `subagent_result`, and
+  they remain independently downloadable after the lineage finishes.
+
+## Bounding delegation
+
+- Turn delegation off for a run by cherry-picking builtins without `subagent`
+  (see [Agent tools](agent-tools.md)) or setting `includeBuiltinTools: false`.
+- A per-session spend cap (`overrides.maxSpendUsd`) bounds the parent's spend.
+- The depth/breadth limits above are platform defaults and are not settable
+  per-session today.