@aexhq/sdk 0.40.5 → 0.40.6

package/docs/public-surface.json

@@ -1,80 +1,80 @@
-{
-  "brand": "aex",
-  "productName": "Agent Executor",
-  "oneLine": "aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.",
-  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, secrets, networking controls, and subagents across the managed runtime.",
-  "alpha": {
-    "label": "Alpha testing",
-    "description": "Access is limited to invited testers while we harden the hosted runtime, dashboard, and SDK workflows."
-  },
-  "installCommand": "npm i @aexhq/sdk",
-  "examples": {
-    "typescriptLines": [
-      "import { Aex, Models, Sizes } from \"@aexhq/sdk\";",
-      "",
-      "const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });",
-      "",
-      "const session = await aex.openSession({",
-      "  model: Models.CLAUDE_HAIKU_4_5,",
-      "  system: \"You are a concise engineering assistant.\",",
-      "  runtime: Sizes.SHARED_0_25X_1GB,",
-      "  overrides: { idleTtl: \"3m\" },",
-      "  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }",
-      "});",
-      "",
-      "const result = await session.send(\"Write a short report and save it as a file.\").done();",
-      "console.log(result.status, result.text);"
-    ],
-    "cliLines": [
-      "aex run \\",
-      "  --api-key \"$AEX_API_KEY\" \\",
-      "  --anthropic-api-key \"$ANTHROPIC_API_KEY\" \\",
-      "  --model claude-haiku-4-5 \\",
-      "  --prompt \"Write a short report and save it as a file.\" \\",
-      "  --follow"
-    ]
-  },
-  "providers": [
-    { "id": "anthropic", "name": "Anthropic" },
-    { "id": "deepseek", "name": "DeepSeek" },
-    { "id": "openai", "name": "OpenAI" },
-    { "id": "gemini", "name": "Gemini" },
-    { "id": "mistral", "name": "Mistral" },
-    { "id": "openrouter", "name": "OpenRouter" },
-    { "id": "doubao", "name": "Doubao" },
-    { "id": "doubao-cn", "name": "Doubao China" }
-  ],
-  "featureAreas": [
-    {
-      "slug": "agent-runtime",
-      "href": "/docs/features/#agent-runtime",
-      "title": "Agent runtime",
-      "description": "Managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents."
-    },
-    {
-      "slug": "durable-infrastructure",
-      "href": "/docs/features/#durable-infrastructure",
-      "title": "Durable infrastructure",
-      "description": "Run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes."
-    },
-    {
-      "slug": "agent-composition",
-      "href": "/docs/features/#agent-composition",
-      "title": "Agent composition",
-      "description": "Skills, files, AGENTS.md, remote MCP servers, environment variables, packages, secrets, and networking controls."
-    },
-    {
-      "slug": "subagents",
-      "href": "/docs/features/#subagents",
-      "title": "Subagents",
-      "description": "Typed parent/child lineage for async child runs, output handoff, and bounded agent delegation."
-    },
-    {
-      "slug": "models-and-providers",
-      "href": "/docs/features/#models-and-providers",
-      "title": "Models and providers",
-      "description": "Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape."
-    },
+{
+  "brand": "aex",
+  "productName": "Agent Executor",
+  "oneLine": "aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.",
+  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, secrets, networking controls, and subagents across the managed runtime.",
+  "alpha": {
+    "label": "Alpha testing",
+    "description": "Access is limited to invited testers while we harden the hosted runtime, dashboard, and SDK workflows."
+  },
+  "installCommand": "npm i @aexhq/sdk",
+  "examples": {
+    "typescriptLines": [
+      "import { Aex, Models, Sizes } from \"@aexhq/sdk\";",
+      "",
+      "const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });",
+      "",
+      "const session = await aex.openSession({",
+      "  model: Models.CLAUDE_HAIKU_4_5,",
+      "  system: \"You are a concise engineering assistant.\",",
+      "  runtime: Sizes.SHARED_0_25X_1GB,",
+      "  overrides: { idleTtl: \"3m\" },",
+      "  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }",
+      "});",
+      "",
+      "const result = await session.send(\"Write a short report and save it as a file.\").done();",
+      "console.log(result.status, result.text);"
+    ],
+    "cliLines": [
+      "aex run \\",
+      "  --api-key \"$AEX_API_KEY\" \\",
+      "  --anthropic-api-key \"$ANTHROPIC_API_KEY\" \\",
+      "  --model claude-haiku-4-5 \\",
+      "  --prompt \"Write a short report and save it as a file.\" \\",
+      "  --follow"
+    ]
+  },
+  "providers": [
+    { "id": "anthropic", "name": "Anthropic" },
+    { "id": "deepseek", "name": "DeepSeek" },
+    { "id": "openai", "name": "OpenAI" },
+    { "id": "gemini", "name": "Gemini" },
+    { "id": "mistral", "name": "Mistral" },
+    { "id": "openrouter", "name": "OpenRouter" },
+    { "id": "doubao", "name": "Doubao" },
+    { "id": "doubao-cn", "name": "Doubao China" }
+  ],
+  "featureAreas": [
+    {
+      "slug": "agent-runtime",
+      "href": "/docs/features/#agent-runtime",
+      "title": "Agent runtime",
+      "description": "Managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents."
+    },
+    {
+      "slug": "durable-infrastructure",
+      "href": "/docs/features/#durable-infrastructure",
+      "title": "Durable infrastructure",
+      "description": "Run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes."
+    },
+    {
+      "slug": "agent-composition",
+      "href": "/docs/features/#agent-composition",
+      "title": "Agent composition",
+      "description": "Skills, files, AGENTS.md, remote MCP servers, environment variables, packages, secrets, and networking controls."
+    },
+    {
+      "slug": "subagents",
+      "href": "/docs/features/#subagents",
+      "title": "Subagents",
+      "description": "Typed parent/child lineage for async child runs, output handoff, and bounded agent delegation."
+    },
+    {
+      "slug": "models-and-providers",
+      "href": "/docs/features/#models-and-providers",
+      "title": "Models and providers",
+      "description": "Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape."
+    },
     {
       "slug": "typed-control-surface",
       "href": "/docs/features/#typed-control-surface",

package/docs/quickstart.md

@@ -1,122 +1,122 @@
----
-title: Quickstart
----
-
-# Quickstart
-
-## 1. Install
-
-```bash
-npm i @aexhq/sdk
-```
-
-This installs the TypeScript SDK exports and the bundled `aex` CLI.
-
-## 2. Set credentials
-
-aex is currently in **invite-only beta**: workspaces and API keys 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`,
-`outputs:read`, and `billing: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_KEY="<your-aex-api-key>"
-export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
-```
-
-## 3. Open a session
-
-```ts
-import { Aex, Models, Sizes } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-
-const session = await aex.openSession({
-  model: Models.CLAUDE_HAIKU_4_5,
-  system: "You are a concise engineering assistant.",
-  runtime: Sizes.SHARED_0_25X_1GB,
-  overrides: { idleTtl: "3m" },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-const first = await session.send("Write a short report and save it as a file.").done();
-console.log(first.status, first.costUsd, first.text);
-```
-
-`send().done()` (and `run()`) **await settle by default**, so the result always
-carries a terminal `status` (`succeeded` / `failed` / `timed_out` / `cancelled`
-— never a bare `idle`) plus `costUsd` and `usage`. Pass `await: 'park'` to
-return early at the render-complete park event when you don't need cost/usage.
-`costUsd` is aex runtime/storage spend and **excludes** your BYOK provider
-charges — price those from `usage` token counts against your provider's rates.
-
-The session parks as `idle` between turns and automatically moves to
-`suspended` after the idle window. Keep the session id and resume later:
-
-```ts
-const resumed = await aex.openSession(session.id);
-await resumed.send("Now run the validation command and summarize the result.").done();
-```
-
-## 4. One-shot convenience
-
-`run()` opens a session, sends `message` as one turn, and returns the collected
-result. Its `runId` is the session id.
-
-```ts
-const result = await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-  message: "Write a short report and save it as a file."
-});
-
-console.log(result.runId, result.status, result.text);
-```
-
-## 5. Session control: stream, wait, download
-
-Sessions are the low-level API. The handle a session gives you can do everything
-to itself — stream its events, wait for it to park, and download its record:
-
-```ts
-const session = await aex.openSession({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-// A turn streams its own events; iterate them, then collect the result.
-const turn = session.send("Write a short report and save it as a file.");
-for await (const event of turn) {
-  console.log(event.type);
-}
-await turn.done();
-
-const messages = await session.messages().list();
-console.log(messages.at(-1)?.text);
-
-// Poll the record until the session parks: a resumable `idle` / `suspended`,
-// or a terminal outcome (`succeeded` / `failed` / `timed_out` / `cancelled`).
-const record = await session.wait();
-console.log(record.status);
-
-// Download the whole session record (metadata, events, outputs) as a zip.
-await session.download({ to: "./session.zip" });
-```
-
-The same run from the bundled CLI (`npx aex` on a local install; or
-`npm i -g @aexhq/sdk` for a bare `aex`):
-
-```bash
-npx aex run \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --model claude-haiku-4-5 \
-  --prompt "Write a short report and save it as a file." \
-  --follow
-```
-
+---
+title: Quickstart
+---
+
+# Quickstart
+
+## 1. Install
+
+```bash
+npm i @aexhq/sdk
+```
+
+This installs the TypeScript SDK exports and the bundled `aex` CLI.
+
+## 2. Set credentials
+
+aex is currently in **invite-only beta**: workspaces and API keys 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`,
+`outputs:read`, and `billing: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_KEY="<your-aex-api-key>"
+export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
+```
+
+## 3. Open a session
+
+```ts
+import { Aex, Models, Sizes } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  system: "You are a concise engineering assistant.",
+  runtime: Sizes.SHARED_0_25X_1GB,
+  overrides: { idleTtl: "3m" },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+const first = await session.send("Write a short report and save it as a file.").done();
+console.log(first.status, first.costUsd, first.text);
+```
+
+`send().done()` (and `run()`) **await settle by default**, so the result always
+carries a terminal `status` (`succeeded` / `failed` / `timed_out` / `cancelled`
+— never a bare `idle`) plus `costUsd` and `usage`. Pass `await: 'park'` to
+return early at the render-complete park event when you don't need cost/usage.
+`costUsd` is aex runtime/storage spend and **excludes** your BYOK provider
+charges — price those from `usage` token counts against your provider's rates.
+
+The session parks as `idle` between turns and automatically moves to
+`suspended` after the idle window. Keep the session id and resume later:
+
+```ts
+const resumed = await aex.openSession(session.id);
+await resumed.send("Now run the validation command and summarize the result.").done();
+```
+
+## 4. One-shot convenience
+
+`run()` opens a session, sends `message` as one turn, and returns the collected
+result. Its `runId` is the session id.
+
+```ts
+const result = await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
+  message: "Write a short report and save it as a file."
+});
+
+console.log(result.runId, result.status, result.text);
+```
+
+## 5. Session control: stream, wait, download
+
+Sessions are the low-level API. The handle a session gives you can do everything
+to itself — stream its events, wait for it to park, and download its record:
+
+```ts
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+// A turn streams its own events; iterate them, then collect the result.
+const turn = session.send("Write a short report and save it as a file.");
+for await (const event of turn) {
+  console.log(event.type);
+}
+await turn.done();
+
+const messages = await session.messages().list();
+console.log(messages.at(-1)?.text);
+
+// Poll the record until the session parks: a resumable `idle` / `suspended`,
+// or a terminal outcome (`succeeded` / `failed` / `timed_out` / `cancelled`).
+const record = await session.wait();
+console.log(record.status);
+
+// Download the whole session record (metadata, events, outputs) as a zip.
+await session.download({ to: "./session.zip" });
+```
+
+The same run from the bundled CLI (`npx aex` on a local install; or
+`npm i -g @aexhq/sdk` for a bare `aex`):
+
+```bash
+npx aex run \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write a short report and save it as a file." \
+  --follow
+```
+
 ## Add capabilities
 
 - Add files, skills, AGENTS.md, MCP servers, packages, and networking controls with [Composition](concepts/composition.md).

package/docs/release.md

@@ -1,9 +1,9 @@
----
-title: Release
----
-
-# Release
-
+---
+title: Release
+---
+
+# Release
+
 The repository is Bun-first. Build, test, docs, package validation, user tests,
 and SDK packaging run through Bun. Registry publication uses npm on the
 Bun-packed SDK tarball so npm provenance and dist-tag controls stay explicit.
@@ -11,18 +11,18 @@ Bun-packed SDK tarball so npm provenance and dist-tag controls stay explicit.
 ## Package gate
 
 Before publishing, validate the package locally and in CI:
-
-```text
-bun ci
-bun run lint
-bun run test
-bun run test:user:offline
-bun run docs:build
+
+```text
+bun ci
+bun run lint
+bun run test
+bun run test:user:offline
+bun run docs:build
 bun run pack:sdk
 ```
-
-`bun run pack:sdk` builds the SDK, runs a Bun pack dry-run, and runs the public
-boundary gate. Offline user tests install the packed SDK into a clean Bun
+
+`bun run pack:sdk` builds the SDK, runs a Bun pack dry-run, and runs the public
+boundary gate. Offline user tests install the packed SDK into a clean Bun
 project and exercise the SDK and CLI from that install tree.
 
 ## Publish
@@ -66,28 +66,28 @@ The manual `.github/workflows/promote.yml` workflow assigns an npm dist-tag to
 an already-published `@aexhq/sdk` version, usually `latest` after canary and
 platform validation. It also runs in `npm-release`, requires `NPM_TOKEN`, and
 does not rebuild or republish the package.
-
-## What ships in the tarball
-
-The SDK tarball is self-contained. It declares zero `@aexhq/*` runtime
-dependencies and is installable from a clean Bun project with no workspace
-access:
-
-- `@aexhq/contracts` lives in `packages/sdk/package.json#devDependencies`
-  only. At build time, [`packages/sdk/scripts/inline-contracts.mjs`](../scripts/inline-contracts.mjs)
-  copies `packages/contracts/dist/**` into `packages/sdk/dist/_contracts/` and
-  rewrites `from "@aexhq/contracts"` to `from "./_contracts/index.js"` across
-  the SDK dist tree. A sanity check at the end of that script refuses to finish
-  if any bare `@aexhq/contracts` specifier survives.
-- `@aexhq/cli` is bundled at build time by
-  [`packages/sdk/scripts/bundle-cli.mjs`](../scripts/bundle-cli.mjs) into a
-  single `dist/cli.mjs`, which is the `bin: aex` entry in
-  `packages/sdk/package.json`.
-- This invariant is mechanically enforced by
-  `apps/user-tests/test/offline/install.test.ts` before publish.
-
-## Rollback
-
+
+## What ships in the tarball
+
+The SDK tarball is self-contained. It declares zero `@aexhq/*` runtime
+dependencies and is installable from a clean Bun project with no workspace
+access:
+
+- `@aexhq/contracts` lives in `packages/sdk/package.json#devDependencies`
+  only. At build time, [`packages/sdk/scripts/inline-contracts.mjs`](../scripts/inline-contracts.mjs)
+  copies `packages/contracts/dist/**` into `packages/sdk/dist/_contracts/` and
+  rewrites `from "@aexhq/contracts"` to `from "./_contracts/index.js"` across
+  the SDK dist tree. A sanity check at the end of that script refuses to finish
+  if any bare `@aexhq/contracts` specifier survives.
+- `@aexhq/cli` is bundled at build time by
+  [`packages/sdk/scripts/bundle-cli.mjs`](../scripts/bundle-cli.mjs) into a
+  single `dist/cli.mjs`, which is the `bin: aex` entry in
+  `packages/sdk/package.json`.
+- This invariant is mechanically enforced by
+  `apps/user-tests/test/offline/install.test.ts` before publish.
+
+## Rollback
+
 Published version numbers are immutable. Bad releases are fixed by publishing a
 higher version and moving dist-tags forward; source rollback alone does not
 remove an npm artifact.