@aexhq/sdk 0.40.6 → 0.40.7

package/README.md

@@ -1,159 +1,159 @@
----
-title: aex
----
-
-# @aexhq/sdk
-
-aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
-
-The package ships:
-
-- `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
-- `sessions` / `openSession()` for durable, resumable agent sessions.
-- Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
-- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
-
-## Install
-
-```bash
-npm i @aexhq/sdk
-```
-
-This installs the TypeScript SDK exports and the bundled `aex` CLI. The CLI
-ships inside the package — invoke it with `npx aex …` after a local install, or
-`npm i -g @aexhq/sdk` to put a bare `aex` on your PATH. Set both credentials
-before running the examples: `AEX_API_KEY` authenticates to aex, and
-`ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
-
-```bash
-export AEX_API_KEY="<your-aex-api-key>"
-export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
-```
-
-## First 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,
-  // Default is "3m"; set it explicitly when you want a different idle window.
-  overrides: { idleTtl: "3m" },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-// done() awaits settle by default, so status is the terminal outcome
-// ("succeeded"), and costUsd/usage are populated.
-const first = await session.send("Summarize this repo.").done();
-console.log(first.status, first.costUsd, first.text);
-
-const resumed = await aex.openSession(session.id);
-await resumed.send("Continue with the follow-up validation.").done();
-```
-
-Need a one-shot convenience? `run()` opens a session, sends `message` as one
-turn, and returns the collected result. The returned `runId` is the session id,
-so it can be resumed later with `openSession(runId)`.
-
-```ts
-const result = await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-  message: "Write the report and save outputs."
-});
-
-console.log(result.runId, result.status, result.text);
-```
-
-For multiple providers, include each BYOK key in `apiKeys`:
-
-```ts
-await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: {
-    anthropic: process.env.ANTHROPIC_API_KEY!,
-    openai: process.env.OPENAI_API_KEY!
-  },
-  message: "Delegate research to a subagent."
-});
-```
-
-The same request can run from the bundled CLI (`npx aex` on a local install):
-
-```bash
-npx aex run \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --model claude-haiku-4-5 \
-  --prompt "Write the report and save outputs." \
-  --follow
-```
-
-## CLI: login, discovery, typed errors
-
-Stop re-passing `--api-key` on every command — log in once and the token (plus
-your default `--aex-url`) is persisted to a `0600` config file
-(`$XDG_CONFIG_HOME/aex/config.json` or `~/.config/aex/config.json`; `%APPDATA%\aex\config.json`
-on Windows). An explicit `--api-key` flag always overrides the stored one.
-
-```bash
-npx aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
-npx aex whoami            # no --api-key needed after login
-npx aex whoami --json     # machine-readable workspace + scopes + limits
-npx aex auth status       # show the resolved config (the token value is never printed)
-npx aex logout            # clear the stored token
-```
-
-Discover the closed sets the platform accepts — no token, no network (human table
-by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
-
-```bash
-npx aex models list           # canonical models + their default provider
-npx aex providers list        # providers + the models each serves
-npx aex tools list            # complete builtin tool set
-npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
-npx aex run --help            # flags for one verb (no API key required)
-```
-
-Errors are typed and actionable. Every `openSession()` / `run()` config-validation
-failure throws a `RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`)
-you can `catch` by code; CLI failures print a JSON envelope carrying the HTTP
-`status`, a one-line `remedy`, and the `runId` where known, and a wrong `--model`,
-`--provider`, or `--runtime-size` gets a "did you mean?" suggestion.
-
-## Continue with sessions
-
-Use sessions for conversational flows. `run()` is the one-shot convenience; a
-`SessionHandle` is the lower-level surface when you want multiple turns,
-streaming, messages, events, outputs, or downloads.
-
-```ts
-const session = await aex.openSession(result.runId);
-const next = await session.send("Turn this into a checklist.").done();
-console.log(next.text);
-
-const messages = await session.messages().list();
-const outputs = await aex.sessions.outputs(session.id).list();
-```
-
-## Feature Areas
-
-- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
-- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
-- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, environment variables, packages, and networking controls.
-- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
-- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
-- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes.
-
-## Docs
-
-- [Quickstart](docs/quickstart.md)
-- [Run configuration](docs/run-config.md)
-- [Composition](docs/concepts/composition.md)
-- [Secrets](docs/secrets.md)
-- [Limits](docs/limits.md)
-- [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)
+---
+title: aex
+---
+
+# @aexhq/sdk
+
+aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
+
+The package ships:
+
+- `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
+- `sessions` / `openSession()` for durable, resumable agent sessions.
+- Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
+- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
+
+## Install
+
+```bash
+npm i @aexhq/sdk
+```
+
+This installs the TypeScript SDK exports and the bundled `aex` CLI. The CLI
+ships inside the package — invoke it with `npx aex …` after a local install, or
+`npm i -g @aexhq/sdk` to put a bare `aex` on your PATH. Set both credentials
+before running the examples: `AEX_API_KEY` authenticates to aex, and
+`ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
+
+```bash
+export AEX_API_KEY="<your-aex-api-key>"
+export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
+```
+
+## First 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,
+  // Default is "3m"; set it explicitly when you want a different idle window.
+  overrides: { idleTtl: "3m" },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+// done() awaits settle by default, so status is the terminal outcome
+// ("succeeded"), and costUsd/usage are populated.
+const first = await session.send("Summarize this repo.").done();
+console.log(first.status, first.costUsd, first.text);
+
+const resumed = await aex.openSession(session.id);
+await resumed.send("Continue with the follow-up validation.").done();
+```
+
+Need a one-shot convenience? `run()` opens a session, sends `message` as one
+turn, and returns the collected result. The returned `runId` is the session id,
+so it can be resumed later with `openSession(runId)`.
+
+```ts
+const result = await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
+  message: "Write the report and save outputs."
+});
+
+console.log(result.runId, result.status, result.text);
+```
+
+For multiple providers, include each BYOK key in `apiKeys`:
+
+```ts
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: {
+    anthropic: process.env.ANTHROPIC_API_KEY!,
+    openai: process.env.OPENAI_API_KEY!
+  },
+  message: "Delegate research to a subagent."
+});
+```
+
+The same request can run from the bundled CLI (`npx aex` on a local install):
+
+```bash
+npx aex run \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write the report and save outputs." \
+  --follow
+```
+
+## CLI: login, discovery, typed errors
+
+Stop re-passing `--api-key` on every command — log in once and the token (plus
+your default `--aex-url`) is persisted to a `0600` config file
+(`$XDG_CONFIG_HOME/aex/config.json` or `~/.config/aex/config.json`; `%APPDATA%\aex\config.json`
+on Windows). An explicit `--api-key` flag always overrides the stored one.
+
+```bash
+npx aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
+npx aex whoami            # no --api-key needed after login
+npx aex whoami --json     # machine-readable workspace + scopes + limits
+npx aex auth status       # show the resolved config (the token value is never printed)
+npx aex logout            # clear the stored token
+```
+
+Discover the closed sets the platform accepts — no token, no network (human table
+by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
+
+```bash
+npx aex models list           # canonical models + their default provider
+npx aex providers list        # providers + the models each serves
+npx aex tools list            # complete builtin tool set
+npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
+npx aex run --help            # flags for one verb (no API key required)
+```
+
+Errors are typed and actionable. Every `openSession()` / `run()` config-validation
+failure throws a `RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`)
+you can `catch` by code; CLI failures print a JSON envelope carrying the HTTP
+`status`, a one-line `remedy`, and the `runId` where known, and a wrong `--model`,
+`--provider`, or `--runtime-size` gets a "did you mean?" suggestion.
+
+## Continue with sessions
+
+Use sessions for conversational flows. `run()` is the one-shot convenience; a
+`SessionHandle` is the lower-level surface when you want multiple turns,
+streaming, messages, events, outputs, or downloads.
+
+```ts
+const session = await aex.openSession(result.runId);
+const next = await session.send("Turn this into a checklist.").done();
+console.log(next.text);
+
+const messages = await session.messages().list();
+const outputs = await aex.sessions.outputs(session.id).list();
+```
+
+## Feature Areas
+
+- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
+- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, environment variables, packages, and networking controls.
+- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes.
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Run configuration](docs/run-config.md)
+- [Composition](docs/concepts/composition.md)
+- [Secrets](docs/secrets.md)
+- [Limits](docs/limits.md)
+- [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)

package/dist/_contracts/stable.d.ts

@@ -22,18 +22,23 @@
  * exact default API plane.
  */
 export declare const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Canonical hosted dev API plane URL. Used when a self-describing dev API key is
+ * passed with no explicit `baseUrl`.
+ */
+export declare const AEX_DEV_BASE_URL = "https://dev-api.aex.dev";
 /**
  * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
  * it DERIVES the target from the API key's embedded plane (see
  * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
- * prod — so a dev key never silently 401s against `api.aex.dev`.
+ * prod — so a dev key routes to `dev-api.aex.dev` and a prd key routes to
+ * `api.aex.dev`.
  *
- * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
- * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
- * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ * The plane-mismatch guard still fires when a key is pointed at the wrong
+ * canonical host (for example, a dev key with `baseUrl=https://api.aex.dev`).
  */
 export declare const PLANE_BASE_URLS: {
-    readonly dev: null;
+    readonly dev: "https://dev-api.aex.dev";
     readonly prd: "https://api.aex.dev";
 };
 export declare function stableStringify(value: unknown): string;

package/dist/_contracts/stable.js

@@ -23,18 +23,23 @@ import { createHash } from "node:crypto";
  * exact default API plane.
  */
 export const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Canonical hosted dev API plane URL. Used when a self-describing dev API key is
+ * passed with no explicit `baseUrl`.
+ */
+export const AEX_DEV_BASE_URL = "https://dev-api.aex.dev";
 /**
  * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
  * it DERIVES the target from the API key's embedded plane (see
  * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
- * prod — so a dev key never silently 401s against `api.aex.dev`.
+ * prod — so a dev key routes to `dev-api.aex.dev` and a prd key routes to
+ * `api.aex.dev`.
  *
- * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
- * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
- * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ * The plane-mismatch guard still fires when a key is pointed at the wrong
+ * canonical host (for example, a dev key with `baseUrl=https://api.aex.dev`).
  */
 export const PLANE_BASE_URLS = {
-    dev: null,
+    dev: AEX_DEV_BASE_URL,
     prd: AEX_DEFAULT_BASE_URL
 };
 export function stableStringify(value) {

package/dist/client.js

@@ -1766,11 +1766,9 @@ export class Aex {
  * Resolve the effective `baseUrl` from a self-describing API key (ZERO-network):
  *   - key omitted-of-shape (opaque/legacy): return the caller's `baseUrl`
  *     unchanged (HttpClient falls back to the prd default).
- *   - `baseUrl` omitted: DERIVE it from the key's plane; a plane with no default
- *     host (dev) requires an explicit `baseUrl` — throw with that guidance.
+ *   - `baseUrl` omitted: DERIVE it from the key's plane.
  *   - `baseUrl` supplied but its plane DISAGREES with the key's plane: throw
- *     {@link CredentialValidationError} BEFORE any request (the exact `dev key
- *     against the prd default → bare token_invalid` trap).
+ *     {@link CredentialValidationError} BEFORE any request.
  */
 function resolveBaseUrlForKey(apiKey, baseUrl) {
     const parsed = parseApiKey(apiKey);
@@ -1778,15 +1776,11 @@ function resolveBaseUrlForKey(apiKey, baseUrl) {
         return baseUrl;
     const planeUrl = PLANE_BASE_URLS[parsed.plane];
     if (baseUrl === undefined) {
-        if (planeUrl === null) {
-            throw new CredentialValidationError(`Aex: this API key is for the ${parsed.plane} plane, which has no default host — pass baseUrl explicitly.`, { plane: parsed.plane });
-        }
         return planeUrl;
     }
-    // The only client-detectable mismatch: a non-prd key pointed at the canonical
-    // prd host (dev has no canonical host to compare a prd key against).
-    if (baseUrl === PLANE_BASE_URLS.prd && parsed.plane !== "prd") {
-        throw new CredentialValidationError(`Aex: this API key is for the ${parsed.plane} plane but baseUrl targets the prd plane (${PLANE_BASE_URLS.prd}) — ` +
+    const canonicalPlane = baseUrl === PLANE_BASE_URLS.dev ? "dev" : baseUrl === PLANE_BASE_URLS.prd ? "prd" : undefined;
+    if (canonicalPlane !== undefined && canonicalPlane !== parsed.plane) {
+        throw new CredentialValidationError(`Aex: this API key is for the ${parsed.plane} plane but baseUrl targets the ${canonicalPlane} plane (${baseUrl}) — ` +
             `pass the ${parsed.plane} plane baseUrl, or omit baseUrl to auto-route.`, { plane: parsed.plane, baseUrl });
     }
     return baseUrl;