@aexhq/sdk 0.40.4 → 0.40.6

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-69afec2c7ee384766adc78235feb061b99c41ff3243bbec208f63f06f11fbd99  cli.mjs
+a67b2cbba2818c579806f112ebfbfddb975b028d0950381985e0e6aa73d259ee  cli.mjs

package/dist/fetch-archive.js

@@ -14,6 +14,8 @@ import { SKILL_BUNDLE_LIMITS } from "./_contracts/index.js";
  * in error messages.
  */
 const DEFAULT_TIMEOUT_MS = 30_000;
+class SkillArchiveDownloadError extends Error {
+}
 export async function fetchSkillArchive(url, opts = {}) {
     if (typeof url !== "string" || url.length === 0) {
         throw new Error("Skill.fromUrl: url is required");
@@ -36,35 +38,93 @@ export async function fetchSkillArchive(url, opts = {}) {
 async function download(url, fetchImpl, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
-    let res;
     try {
-        res = await fetchImpl(url, { signal: controller.signal });
+        const res = await fetchImpl(url, { signal: controller.signal });
+        if (!res.ok) {
+            throw new SkillArchiveDownloadError(`Skill.fromUrl: fetch for ${redactUrl(url)} returned HTTP ${res.status}`);
+        }
+        // Early guard on a declared size so a clearly-too-big archive fails before
+        // we buffer it. The authoritative caps are re-checked by bundleSkillFiles.
+        const declaredRaw = res.headers.get("content-length");
+        const declared = declaredRaw !== null && /^\d+$/.test(declaredRaw) ? Number(declaredRaw) : undefined;
+        if (declared !== undefined && declared > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
+            throw new SkillArchiveDownloadError(`Skill.fromUrl: archive at ${redactUrl(url)} declares ${declared} bytes, ` +
+                `exceeding the ${SKILL_BUNDLE_LIMITS.maxCompressedBytes}-byte compressed cap`);
+        }
+        const bytes = await readResponseBytes(res, url, controller.signal);
+        if (bytes.byteLength === 0) {
+            throw new SkillArchiveDownloadError(`Skill.fromUrl: archive at ${redactUrl(url)} is empty`);
+        }
+        return bytes;
     }
     catch (err) {
+        if (err instanceof SkillArchiveDownloadError)
+            throw err;
         throw new Error(`Skill.fromUrl: fetch failed for ${redactUrl(url)}: ${errMessage(err)}`);
     }
     finally {
         clearTimeout(timer);
     }
-    if (!res.ok) {
-        throw new Error(`Skill.fromUrl: fetch for ${redactUrl(url)} returned HTTP ${res.status}`);
+}
+async function readResponseBytes(res, url, signal) {
+    if (!res.body) {
+        const bytes = new Uint8Array(await withAbort(res.arrayBuffer(), signal));
+        ensureWithinCompressedCap(bytes.byteLength, url);
+        return bytes;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await withAbort(reader.read(), signal);
+            if (done)
+                break;
+            if (!value || value.byteLength === 0)
+                continue;
+            total += value.byteLength;
+            ensureWithinCompressedCap(total, url);
+            chunks.push(value);
+        }
     }
-    // Early guard on a declared size so a clearly-too-big archive fails before
-    // we buffer it. The authoritative caps are re-checked by bundleSkillFiles.
-    const declared = Number(res.headers.get("content-length"));
-    if (Number.isFinite(declared) && declared > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
-        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} declares ${declared} bytes, ` +
-            `exceeding the ${SKILL_BUNDLE_LIMITS.maxCompressedBytes}-byte compressed cap`);
+    finally {
+        await reader.cancel().catch(() => { });
     }
-    const bytes = new Uint8Array(await res.arrayBuffer());
-    if (bytes.byteLength > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
-        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} is ${bytes.byteLength} bytes, ` +
+    return concatBytes(chunks, total);
+}
+function ensureWithinCompressedCap(bytes, url) {
+    if (bytes > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
+        throw new SkillArchiveDownloadError(`Skill.fromUrl: archive at ${redactUrl(url)} is ${bytes} bytes, ` +
             `exceeding the ${SKILL_BUNDLE_LIMITS.maxCompressedBytes}-byte compressed cap`);
     }
-    if (bytes.byteLength === 0) {
-        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} is empty`);
+}
+function concatBytes(chunks, total) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function withAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+function abortError() {
+    if (typeof DOMException === "function") {
+        return new DOMException("The operation was aborted", "AbortError");
     }
-    return bytes;
+    const err = new Error("The operation was aborted");
+    err.name = "AbortError";
+    return err;
 }
 async function verifySha256(bytes, expected, url) {
     const want = (expected.startsWith("sha256:") ? expected.slice("sha256:".length) : expected).toLowerCase();

package/dist/fetch-archive.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-archive.js","sourceRoot":"","sources":["../src/fetch-archive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fetch-archive.js","sourceRoot":"","sources":["../src/fetch-archive.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.40.4";
+export declare const SDK_VERSION = "0.40.6";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.40.4";
+export const SDK_VERSION = "0.40.6";
 //# sourceMappingURL=version.js.map

package/docs/authentication.md

@@ -1,125 +1,125 @@
----
-title: Authentication
----
-
-# Authentication
-
-Every SDK and CLI call authenticates with an **aex API key**: a bearer
-credential that is **workspace-scoped** — the workspace is derived server-side
-from the token, so there is no workspace parameter anywhere in the API. A
-request either carries a valid token for a workspace or it is rejected with
-`401 unauthorized` (see [Errors](errors.md)).
-
-## Getting a token (invite-only beta)
-
-aex is currently in **invite-only beta**. Workspaces and their initial API
-tokens are provisioned by the aex team — contact <support@aex.dev> for beta
-access. Once your workspace exists, you can create and delete additional tokens
-in the dashboard at <https://aex.dev>.
-
-## Using a token
-
-Pass the token to the SDK constructor, the CLI's `--api-key` flag, or persist
-it once with `aex login`:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-```
-
-```bash
-npx aex whoami --api-key "$AEX_API_KEY"
-
-# or persist it once, then omit --api-key on later commands:
-npx aex login --api-key "$AEX_API_KEY"
-npx aex whoami
-```
-
-(`new Aex(apiKey)` is the canonical constructor; the equivalent options form is
-documented once in [Credentials](credentials.md).)
-
-The token travels as a standard `Authorization: Bearer` header. Treat it like
-any other secret: keep it in environment variables or a secret manager, never
-in run config, prompts, or committed files.
-
-## Plane routing and the `baseUrl` guard
-
-An aex API key is **self-describing**: it embeds the plane (`dev` / `prd`) and
-region it was minted for. The constructor parses the key and routes accordingly,
-with **zero network**:
-
-- **Omit `baseUrl`** and a `prd` key routes to the canonical hosted API plane
-  (`https://api.aex.dev`). A `dev` key has no stable public host yet, so a dev
-  key with no `baseUrl` throws `CredentialValidationError` asking you to pass one.
-- **Supply a `baseUrl` whose plane disagrees with the key** (e.g. a `dev` key
-  pointed at `https://api.aex.dev`) and the constructor throws
-  `CredentialValidationError` **before any request** — you no longer discover the
-  mismatch as a late `401 token_invalid` after a full round-trip.
-
-```ts
-// prd key → routes to https://api.aex.dev automatically:
-const prd = new Aex(process.env.AEX_PRD_KEY!);
-
-// dev key → pass the dev plane's baseUrl explicitly:
-const dev = new Aex(process.env.AEX_DEV_KEY!, { baseUrl: process.env.AEX_DEV_URL! });
-```
-
-## Scopes
-
-A token carries a set of **scopes**; every API route requires one, and a token
-that lacks the route's scope fails with `403 insufficient_scope` naming the
-missing scope. The customer-grantable scopes:
-
-| Scope | Grants |
-| --- | --- |
-| `runs:read` | Read sessions/runs, their events and event archives, and webhook delivery ledgers. |
-| `runs:write` | Open sessions, send turns, submit runs, suspend/resume, redeliver webhooks, reveal the webhook signing secret. |
-| `runs:cancel` | Cancel a session/run. |
-| `runs:delete` | Delete a session/run record. |
-| `outputs:read` | List, read, download, and mint links for captured outputs. |
-| `files:write` | Upload asset bytes (files, skills, AGENTS.md) staged for a run. |
-| `files:delete` | Delete workspace asset-store entries. |
-| `secrets:read` | List workspace secrets and read their metadata (never values). |
-| `secrets:write` | Create, rotate, and delete workspace secrets. |
-| `mcp:read` | List and read workspace MCP server configurations. |
-| `mcp:write` | Create workspace MCP server configurations. |
-| `mcp:delete` | Delete workspace MCP server configurations. |
-| `billing:read` | Read billing state and create hosted billing sessions. |
-| `workspaces:delete` | Owner self-service workspace hard-erase. |
-
-Tokens may additionally carry the reserved scopes `skills:read` /
-`skills:write` / `skills:delete`, `agentsmd:read` / `agentsmd:write` /
-`agentsmd:delete`, and `files:read`. No API route requires them today — skill
-and AGENTS.md asset uploads are covered by `files:write` — so treat them as
-inert placeholders for future per-asset-type routes.
-
-A typical automation token carries `runs:read`, `runs:write`, and
-`outputs:read`. Grant the rest only where the workload needs them — a read-only
-reporting token, for example, needs no `runs:write`.
-
-## Introspection: `whoami`
-
-`aex.whoami()` (CLI: `aex whoami`) validates the token and returns the
-workspace id, the token's scopes, and — on current platform deployments — a
-`limits` object with the workspace's effective admission caps
-(`maxConcurrentRuns`, `submitRatePerMinute`, `spendCapUsd`, `monthSpendUsd`,
-`balanceUsd`, `balanceGraceFloorUsd`, `paymentMethodStatus`), resolved by the
-same code the submit gates enforce. Use it as a cheap credential check and to
-anticipate `429`/`402` rejections before submitting — see
-[Limits & quotas](limits-and-quotas.md) and [Errors](errors.md).
-
-## Rotation and revocation
-
-- **Rotate** by creating a new token in the dashboard, switching your
-  deployment to it, then deleting the old one. Tokens are independent — both
-  stay valid during the switch, so rotation needs no downtime.
-- **Revoke** by deleting the token in the dashboard; deletion takes effect
-  immediately (allow up to a minute for in-flight caches to expire).
-- Token create/delete are rate-limited per workspace (see
-  [Limits & quotas](limits-and-quotas.md)).
-- If you cannot reach the dashboard (or suspect workspace-level compromise),
-  contact <support@aex.dev>.
-
-Provider keys (`apiKeys`) and runtime secrets are a separate, per-call surface —
-see [Credentials](credentials.md) and [Secrets](secrets.md).
+---
+title: Authentication
+---
+
+# Authentication
+
+Every SDK and CLI call authenticates with an **aex API key**: a bearer
+credential that is **workspace-scoped** — the workspace is derived server-side
+from the token, so there is no workspace parameter anywhere in the API. A
+request either carries a valid token for a workspace or it is rejected with
+`401 unauthorized` (see [Errors](errors.md)).
+
+## Getting a token (invite-only beta)
+
+aex is currently in **invite-only beta**. Workspaces and their initial API
+tokens are provisioned by the aex team — contact <support@aex.dev> for beta
+access. Once your workspace exists, you can create and delete additional tokens
+in the dashboard at <https://aex.dev>.
+
+## Using a token
+
+Pass the token to the SDK constructor, the CLI's `--api-key` flag, or persist
+it once with `aex login`:
+
+```ts
+import { Aex } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+```
+
+```bash
+npx aex whoami --api-key "$AEX_API_KEY"
+
+# or persist it once, then omit --api-key on later commands:
+npx aex login --api-key "$AEX_API_KEY"
+npx aex whoami
+```
+
+(`new Aex(apiKey)` is the canonical constructor; the equivalent options form is
+documented once in [Credentials](credentials.md).)
+
+The token travels as a standard `Authorization: Bearer` header. Treat it like
+any other secret: keep it in environment variables or a secret manager, never
+in run config, prompts, or committed files.
+
+## Plane routing and the `baseUrl` guard
+
+An aex API key is **self-describing**: it embeds the plane (`dev` / `prd`) and
+region it was minted for. The constructor parses the key and routes accordingly,
+with **zero network**:
+
+- **Omit `baseUrl`** and a `prd` key routes to the canonical hosted API plane
+  (`https://api.aex.dev`). A `dev` key has no stable public host yet, so a dev
+  key with no `baseUrl` throws `CredentialValidationError` asking you to pass one.
+- **Supply a `baseUrl` whose plane disagrees with the key** (e.g. a `dev` key
+  pointed at `https://api.aex.dev`) and the constructor throws
+  `CredentialValidationError` **before any request** — you no longer discover the
+  mismatch as a late `401 token_invalid` after a full round-trip.
+
+```ts
+// prd key → routes to https://api.aex.dev automatically:
+const prd = new Aex(process.env.AEX_PRD_KEY!);
+
+// dev key → pass the dev plane's baseUrl explicitly:
+const dev = new Aex(process.env.AEX_DEV_KEY!, { baseUrl: process.env.AEX_DEV_URL! });
+```
+
+## Scopes
+
+A token carries a set of **scopes**; every API route requires one, and a token
+that lacks the route's scope fails with `403 insufficient_scope` naming the
+missing scope. The customer-grantable scopes:
+
+| Scope | Grants |
+| --- | --- |
+| `runs:read` | Read sessions/runs, their events and event archives, and webhook delivery ledgers. |
+| `runs:write` | Open sessions, send turns, submit runs, suspend/resume, redeliver webhooks, reveal the webhook signing secret. |
+| `runs:cancel` | Cancel a session/run. |
+| `runs:delete` | Delete a session/run record. |
+| `outputs:read` | List, read, download, and mint links for captured outputs. |
+| `files:write` | Upload asset bytes (files, skills, AGENTS.md) staged for a run. |
+| `files:delete` | Delete workspace asset-store entries. |
+| `secrets:read` | List workspace secrets and read their metadata (never values). |
+| `secrets:write` | Create, rotate, and delete workspace secrets. |
+| `mcp:read` | List and read workspace MCP server configurations. |
+| `mcp:write` | Create workspace MCP server configurations. |
+| `mcp:delete` | Delete workspace MCP server configurations. |
+| `billing:read` | Read billing state and create hosted billing sessions. |
+| `workspaces:delete` | Owner self-service workspace hard-erase. |
+
+Tokens may additionally carry the reserved scopes `skills:read` /
+`skills:write` / `skills:delete`, `agentsmd:read` / `agentsmd:write` /
+`agentsmd:delete`, and `files:read`. No API route requires them today — skill
+and AGENTS.md asset uploads are covered by `files:write` — so treat them as
+inert placeholders for future per-asset-type routes.
+
+A typical automation token carries `runs:read`, `runs:write`, and
+`outputs:read`. Grant the rest only where the workload needs them — a read-only
+reporting token, for example, needs no `runs:write`.
+
+## Introspection: `whoami`
+
+`aex.whoami()` (CLI: `aex whoami`) validates the token and returns the
+workspace id, the token's scopes, and — on current platform deployments — a
+`limits` object with the workspace's effective admission caps
+(`maxConcurrentRuns`, `submitRatePerMinute`, `spendCapUsd`, `monthSpendUsd`,
+`balanceUsd`, `balanceGraceFloorUsd`, `paymentMethodStatus`), resolved by the
+same code the submit gates enforce. Use it as a cheap credential check and to
+anticipate `429`/`402` rejections before submitting — see
+[Limits & quotas](limits-and-quotas.md) and [Errors](errors.md).
+
+## Rotation and revocation
+
+- **Rotate** by creating a new token in the dashboard, switching your
+  deployment to it, then deleting the old one. Tokens are independent — both
+  stay valid during the switch, so rotation needs no downtime.
+- **Revoke** by deleting the token in the dashboard; deletion takes effect
+  immediately (allow up to a minute for in-flight caches to expire).
+- Token create/delete are rate-limited per workspace (see
+  [Limits & quotas](limits-and-quotas.md)).
+- If you cannot reach the dashboard (or suspect workspace-level compromise),
+  contact <support@aex.dev>.
+
+Provider keys (`apiKeys`) and runtime secrets are a separate, per-call surface —
+see [Credentials](credentials.md) and [Secrets](secrets.md).