@aexhq/sdk 0.30.0 → 0.31.0

package/README.md

@@ -9,7 +9,7 @@ aex is an agent execution platform for launching autonomous agents from a simple
 The package ships:
 
 - `AgentExecutor` for submit, run, wait, stream, inspect, download, cancel, and delete.
-- Typed run primitives: `Models`, `Providers`, `Regions`, `RuntimeSizes`, `Skill`, `AgentsMd`, `File`, `McpServer`, `ProxyEndpoint`, and `Secret`.
+- Typed run primitives: `Models`, `Providers`, `RuntimeSizes`, `Skill`, `AgentsMd`, `File`, `McpServer`, `ProxyEndpoint`, and `Secret`.
 - A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, whoami, and skills operations.
 
 ## Install
@@ -18,6 +18,15 @@ The package ships:
 bun add @aexhq/sdk
 ```
 
+This installs the TypeScript SDK exports and the bundled `aex` CLI. Set both
+credentials before running the examples: `AEX_API_TOKEN` authenticates to aex,
+and `ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
+
+```bash
+export AEX_API_TOKEN="<your-aex-token>"
+export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
+```
+
 ## First Run
 
 ```ts
@@ -29,7 +38,7 @@ const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 // no manual poll loop. `provider` is derived from the model.
 const { text, ok } = await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  apiKey: process.env.ANTHROPIC_API_KEY!,
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } },
   prompt: "Summarize this repo."
 });
 
@@ -41,7 +50,7 @@ Need the run id, live events, or downloads? Use `submit` + `stream` + `wait`:
 ```ts
 const runId = await aex.submit({
   model: Models.CLAUDE_HAIKU_4_5,
-  apiKey: process.env.ANTHROPIC_API_KEY!,
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } },
   prompt: "Write the report and save outputs."
 });
 
@@ -55,18 +64,23 @@ console.log(run.status);
 await aex.download(runId, { to: "./run.zip" });
 ```
 
-For multiple providers (e.g. subagents on a different model family), pass a
-`credentials` map instead of `apiKey`:
+For multiple providers (e.g. subagents on a different model family), include
+each BYOK key in `secrets.apiKeys`:
 
 ```ts
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  credentials: { anthropic: process.env.ANTHROPIC_API_KEY!, openai: process.env.OPENAI_API_KEY! },
+  secrets: {
+    apiKeys: {
+      anthropic: process.env.ANTHROPIC_API_KEY!,
+      openai: process.env.OPENAI_API_KEY!
+    }
+  },
   prompt: "Delegate research to a subagent."
 });
 ```
 
-The same request can run from the CLI:
+The same request can run from the bundled CLI:
 
 ```bash
 aex run \
@@ -104,8 +118,8 @@ aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
 Errors are typed and actionable. Every `submit()` 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`/
-`--runtime-size`/`--region` gets a "did you mean?" suggestion.
+`remedy`, and the `runId` where known, and a wrong `--model`, `--provider`, or
+`--runtime-size` gets a "did you mean?" suggestion.
 
 ## Chat over a corpus of runs
 

package/dist/_contracts/connection-ticket.d.ts

@@ -10,7 +10,7 @@
  *
  * This lives in shared so the coordinator (which verifies) and the API
  * hosted API's ticket broker (which mints, on behalf of a workspace token) use
- * ONE implementation. Pure Web Crypto — identical under Bun, Node, and workerd.
+ * ONE implementation. Pure Web Crypto — identical under Bun and Node.
  */
 export type ConnectionTicketChannel = "event" | "log" | "all";
 /** Mint a `${channel}.${exp}.${mac}` ticket valid for `ttlMs` from `nowMs`. */

package/dist/_contracts/connection-ticket.js

@@ -10,7 +10,7 @@
  *
  * This lives in shared so the coordinator (which verifies) and the API
  * hosted API's ticket broker (which mints, on behalf of a workspace token) use
- * ONE implementation. Pure Web Crypto — identical under Bun, Node, and workerd.
+ * ONE implementation. Pure Web Crypto — identical under Bun and Node.
  */
 const DEFAULT_TICKET_TTL_MS = 60_000;
 const encoder = new TextEncoder();

package/dist/_contracts/event-envelope.d.ts

@@ -21,7 +21,7 @@
  * coordinator:
  *   - `channel`   — "event" (the typed AG-UI stream) or "log" (a verbose log
  *                   line). The single axis a consumer splits the unified stream
- *                   on. Absent ⇒ "event" (back-compat for existing producers).
+ *                   on.
  *   - `sourceSeq` — a per-SOURCE monotonic counter assigned AT the source. The
  *                   DO's hard guarantee is that records of the same source are
  *                   never reordered relative to their `sourceSeq`.
@@ -33,9 +33,8 @@
  * `sequence` on arrival, which is the canonical stream order. `sourceSeq` /
  * `emittedAt` are CARRIED through broadcast + archive, not used to reorder.
  *
- * This module is **additive**: it does not change {@link RunnerEvent} or any
- * existing wire shape. It is a pure projection plus honest guards and a strict
- * AG-UI projection for consumers.
+ * This module is a pure projection plus honest guards and a strict AG-UI
+ * projection for consumers.
  */
 import type { JsonValue } from "./submission.js";
 import type { RunnerEvent } from "./runner-event.js";
@@ -51,7 +50,7 @@ export declare const AEX_EVENT_MAP_VERSION: 1;
 /**
  * Coarse origin classifier — the first axis a consumer filters on.
  *   - `agent`   — the model: text, reasoning, builtin tool calls/results.
- *   - `worker`  — the hosted aex edge itself.
+ *   - `api`     — the hosted aex API path.
  *   - `runtime` — the execution runtime: lifecycle, diagnostics, non-fatal
  *                 stream errors.
  *   - `mcp`     — an MCP server (a tool call/result routed through MCP).
@@ -60,7 +59,7 @@ export declare const AEX_EVENT_MAP_VERSION: 1;
  *   - `host`    — the managed host the runtime executes on; distinct from the
  *                 runtime process itself.
  */
-export declare const AEX_EVENT_SOURCES: readonly ["agent", "worker", "runtime", "mcp", "aex", "workflow", "host"];
+export declare const AEX_EVENT_SOURCES: readonly ["agent", "api", "runtime", "mcp", "aex", "workflow", "host"];
 export type AexEventSource = (typeof AEX_EVENT_SOURCES)[number];
 /**
  * The channel a record rides on the unified per-run stream:
@@ -134,8 +133,6 @@ export interface AexEvent {
      * as the authoritative receive marker. It does NOT need to exceed `emittedAt`:
      * the source runs on a different host with an independent clock, so cross-host
      * drift can leave `receivedAt < emittedAt` and that is expected, not an error.
-     * Absent on records produced before this field existed (back-compat with
-     * archived records).
      */
     readonly receivedAt?: number;
     /**

package/dist/_contracts/event-envelope.js

@@ -21,7 +21,7 @@
  * coordinator:
  *   - `channel`   — "event" (the typed AG-UI stream) or "log" (a verbose log
  *                   line). The single axis a consumer splits the unified stream
- *                   on. Absent ⇒ "event" (back-compat for existing producers).
+ *                   on.
  *   - `sourceSeq` — a per-SOURCE monotonic counter assigned AT the source. The
  *                   DO's hard guarantee is that records of the same source are
  *                   never reordered relative to their `sourceSeq`.
@@ -33,9 +33,8 @@
  * `sequence` on arrival, which is the canonical stream order. `sourceSeq` /
  * `emittedAt` are CARRIED through broadcast + archive, not used to reorder.
  *
- * This module is **additive**: it does not change {@link RunnerEvent} or any
- * existing wire shape. It is a pure projection plus honest guards and a strict
- * AG-UI projection for consumers.
+ * This module is a pure projection plus honest guards and a strict AG-UI
+ * projection for consumers.
  */
 /** CloudEvents `specversion` the envelope conforms to. */
 export const AEX_EVENT_SPECVERSION = "1.0";
@@ -49,7 +48,7 @@ export const AEX_EVENT_MAP_VERSION = 1;
 /**
  * Coarse origin classifier — the first axis a consumer filters on.
  *   - `agent`   — the model: text, reasoning, builtin tool calls/results.
- *   - `worker`  — the hosted aex edge itself.
+ *   - `api`     — the hosted aex API path.
  *   - `runtime` — the execution runtime: lifecycle, diagnostics, non-fatal
  *                 stream errors.
  *   - `mcp`     — an MCP server (a tool call/result routed through MCP).
@@ -58,7 +57,7 @@ export const AEX_EVENT_MAP_VERSION = 1;
  *   - `host`    — the managed host the runtime executes on; distinct from the
  *                 runtime process itself.
  */
-export const AEX_EVENT_SOURCES = ["agent", "worker", "runtime", "mcp", "aex", "workflow", "host"];
+export const AEX_EVENT_SOURCES = ["agent", "api", "runtime", "mcp", "aex", "workflow", "host"];
 /**
  * The channel a record rides on the unified per-run stream:
  *   - `event` — the typed, low-volume, fully-replayed AG-UI event stream.

package/dist/_contracts/event-stream-client.d.ts

@@ -65,7 +65,7 @@ export interface CoordinatorStreamOptions {
     readonly idleTimeoutMs?: number;
     /**
      * Client keep-alive ping cadence. The client sends {@link COORDINATOR_PING},
-     * which the coordinator auto-responds to WITHOUT waking the durable object, so
+     * which the coordinator auto-responds to WITHOUT waking the stateful coordinator, so
      * a legitimately quiet run keeps the socket measurably alive and does not trip
      * the watchdog. Default 15s. Set 0 to disable (then only real events reset the
      * watchdog → quiet runs may reconnect).

package/dist/_contracts/http.js

@@ -103,7 +103,7 @@ function extractErrorMessage(body) {
             if (typeof message === "string")
                 return message;
         }
-        // aex Worker error envelope: `{ ok:false, code, message }`. Surface
+        // aex API error envelope: `{ ok:false, code, message }`. Surface
         // the server's message so structured rejections (e.g. runtime support)
         // aren't flattened to the generic fallback below.
         if (typeof obj.message === "string")

package/dist/_contracts/operations.d.ts

@@ -132,62 +132,17 @@ export declare function downloadEvents(http: HttpClient, runId: string): Promise
  */
 export declare function downloadMetadata(http: HttpClient, runId: string): Promise<Uint8Array>;
 export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionInput): Promise<Run>;
-/**
- * Multipart variant of `submitRun` for runs that carry transient
- * (per-run) skill bundles and/or transient AgentsMd content.
- *
- * The JSON submission travels as the `submission` part; each
- * `InlineSkillRef.slot` in `request.submission.skills` MUST be
- * mirrored by exactly one `skill:<slot>` part with the bundle bytes.
- * Each `InlineAgentsMdRef.slot` in `request.submission.agentsMd`
- * MUST be mirrored by exactly one `agentsmd:<slot>` part with the
- * markdown text.
- *
- * The BFF re-canonicalises and re-hashes each bundle/file; a
- * `contentHash` mismatch is rejected with a deterministic error.
- *
- * At least one of `bundles` or `agentsMdParts` must be non-empty.
- */
-export declare function submitRunMultipart(http: HttpClient, request: PlatformRunSubmissionInput, bundles: ReadonlyArray<{
-    readonly slot: string;
-    readonly bytes: Uint8Array;
-    readonly filename: string;
-}>, agentsMdParts?: ReadonlyArray<{
-    readonly slot: string;
-    readonly content: string;
-    readonly filename: string;
-}>, fileParts?: ReadonlyArray<{
-    readonly slot: string;
-    readonly bytes: Uint8Array;
-    readonly filename: string;
-}>): Promise<Run>;
-/**
- * Upload a workspace skill bundle as a zip blob. The hosted API runs
- * the two-phase flow internally (insert pending row, stream bytes into
- * object storage, validate manifest, transition to ready) and returns
- * the finalized `Skill`. Use `Skill.fromPath` / `Skill.upload` in the
- * SDK to build the body; this transport function only knows about
- * bytes.
- */
-export declare function createSkillBundle(http: HttpClient, args: {
-    readonly name: string;
-    readonly body: Blob | ArrayBuffer | Uint8Array;
-    readonly contentType?: string;
-    readonly filename?: string;
-}): Promise<Skill>;
 /**
  * Upload a workspace skill bundle DIRECTLY to object storage via the presign
  * flow, so the bytes never transit the hosted API (bundle size bounded by the
- * object store, not API memory). Falls back to the buffered multipart
- * `createSkillBundle` when the hosted API has no object-store upload
- * credentials (503 `presign_unconfigured`).
+ * object store, not API memory). Presign errors are terminal.
  *
  *   1. POST /api/skills/presign     { name, hash, sizeBytes } → { uploadUrl, requiredHeaders, skillId }
  *   2. PUT bytes → uploadUrl        (signed checksum; the store rejects a mismatch)
  *   3. POST /api/skills/:id/finalize { manifest } → finalized Skill
  *
  * `manifest` is the client-computed bundle manifest (the caller already
- * validated the zip shape before hashing); the Worker records it on finalize
+ * validated the zip shape before hashing); the hosted API records it on finalize
  * without re-buffering the object.
  */
 export declare function createSkillBundleDirect(http: HttpClient, fetchImpl: (input: string, init?: RequestInit) => Promise<{

package/dist/_contracts/operations.js

@@ -628,130 +628,25 @@ export async function submitRun(http, request) {
         body: JSON.stringify(request)
     });
 }
-/**
- * Multipart variant of `submitRun` for runs that carry transient
- * (per-run) skill bundles and/or transient AgentsMd content.
- *
- * The JSON submission travels as the `submission` part; each
- * `InlineSkillRef.slot` in `request.submission.skills` MUST be
- * mirrored by exactly one `skill:<slot>` part with the bundle bytes.
- * Each `InlineAgentsMdRef.slot` in `request.submission.agentsMd`
- * MUST be mirrored by exactly one `agentsmd:<slot>` part with the
- * markdown text.
- *
- * The BFF re-canonicalises and re-hashes each bundle/file; a
- * `contentHash` mismatch is rejected with a deterministic error.
- *
- * At least one of `bundles` or `agentsMdParts` must be non-empty.
- */
-export async function submitRunMultipart(http, request, bundles, agentsMdParts, fileParts) {
-    const hasBundles = Array.isArray(bundles) && bundles.length > 0;
-    const hasAgentsMd = Array.isArray(agentsMdParts) && agentsMdParts.length > 0;
-    const hasFiles = Array.isArray(fileParts) && fileParts.length > 0;
-    if (!hasBundles && !hasAgentsMd && !hasFiles) {
-        throw new Error("submitRunMultipart: bundles, agentsMdParts, or fileParts must be non-empty");
-    }
-    const form = new FormData();
-    // Submission rides as a typed JSON Blob so the BFF reads
-    // `multipart["submission"]` with the right content-type and never
-    // has to re-detect the body shape.
-    form.append("submission", new Blob([JSON.stringify(request)], { type: "application/json" }), "submission.json");
-    const seen = new Set();
-    for (const bundle of bundles) {
-        if (typeof bundle.slot !== "string" || !bundle.slot) {
-            throw new Error("submitRunMultipart: each bundle must have a non-empty slot id");
-        }
-        if (seen.has(bundle.slot)) {
-            throw new Error(`submitRunMultipart: duplicate inline skill slot "${bundle.slot}"`);
-        }
-        seen.add(bundle.slot);
-        const blob = toBlob(bundle.bytes, "application/zip");
-        form.append(`skill:${bundle.slot}`, blob, bundle.filename);
-    }
-    for (const part of agentsMdParts ?? []) {
-        if (typeof part.slot !== "string" || !part.slot) {
-            throw new Error("submitRunMultipart: each agentsMd part must have a non-empty slot id");
-        }
-        const partKey = `agentsmd:${part.slot}`;
-        if (seen.has(partKey)) {
-            throw new Error(`submitRunMultipart: duplicate agentsMd slot "${part.slot}"`);
-        }
-        seen.add(partKey);
-        const blob = new Blob([part.content], { type: "text/plain" });
-        form.append(partKey, blob, part.filename);
-    }
-    for (const part of fileParts ?? []) {
-        if (typeof part.slot !== "string" || !part.slot) {
-            throw new Error("submitRunMultipart: each file part must have a non-empty slot id");
-        }
-        const partKey = `file:${part.slot}`;
-        if (seen.has(partKey)) {
-            throw new Error(`submitRunMultipart: duplicate file slot "${part.slot}"`);
-        }
-        seen.add(partKey);
-        const blob = toBlob(part.bytes, "application/zip");
-        form.append(partKey, blob, part.filename);
-    }
-    return http.request("/api/runs", {
-        method: "POST",
-        body: form
-    });
-}
-/**
- * Upload a workspace skill bundle as a zip blob. The hosted API runs
- * the two-phase flow internally (insert pending row, stream bytes into
- * object storage, validate manifest, transition to ready) and returns
- * the finalized `Skill`. Use `Skill.fromPath` / `Skill.upload` in the
- * SDK to build the body; this transport function only knows about
- * bytes.
- */
-export async function createSkillBundle(http, args) {
-    const form = new FormData();
-    form.append("name", args.name);
-    const blobBody = toBlob(args.body, args.contentType ?? "application/zip");
-    form.append("bundle", blobBody, args.filename ?? `${args.name}.zip`);
-    const result = await http.request("/api/skills", {
-        method: "POST",
-        body: form
-    });
-    return unwrapSkill(result);
-}
 /**
  * Upload a workspace skill bundle DIRECTLY to object storage via the presign
  * flow, so the bytes never transit the hosted API (bundle size bounded by the
- * object store, not API memory). Falls back to the buffered multipart
- * `createSkillBundle` when the hosted API has no object-store upload
- * credentials (503 `presign_unconfigured`).
+ * object store, not API memory). Presign errors are terminal.
  *
  *   1. POST /api/skills/presign     { name, hash, sizeBytes } → { uploadUrl, requiredHeaders, skillId }
  *   2. PUT bytes → uploadUrl        (signed checksum; the store rejects a mismatch)
  *   3. POST /api/skills/:id/finalize { manifest } → finalized Skill
  *
  * `manifest` is the client-computed bundle manifest (the caller already
- * validated the zip shape before hashing); the Worker records it on finalize
+ * validated the zip shape before hashing); the hosted API records it on finalize
  * without re-buffering the object.
  */
 export async function createSkillBundleDirect(http, fetchImpl, args) {
-    let presign;
-    try {
-        presign = await http.request("/api/skills/presign", {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ name: args.name, hash: args.contentHash, sizeBytes: args.body.byteLength })
-        });
-    }
-    catch (err) {
-        const status = err.status;
-        const code = (err.details ?? {}).code;
-        if (status === 503 && code === "presign_unconfigured") {
-            return createSkillBundle(http, {
-                name: args.name,
-                body: args.body,
-                ...(args.contentType ? { contentType: args.contentType } : {})
-            });
-        }
-        throw err;
-    }
+    const presign = await http.request("/api/skills/presign", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: args.name, hash: args.contentHash, sizeBytes: args.body.byteLength })
+    });
     const putRes = await fetchImpl(presign.uploadUrl, {
         method: "PUT",
         headers: { "content-type": args.contentType ?? "application/zip", ...(presign.requiredHeaders ?? {}) },