@aexhq/sdk 0.46.4-canary → 0.50.0

package/dist/_contracts/sse.js

@@ -1,227 +0,0 @@
-/**
- * Tiny SSE (text/event-stream) parser used by the SDK / CLI to consume
- * the dashboard's `/api/sessions/:id/events/stream` endpoint without
- * pulling in a DOM `EventSource` dependency. Node's `fetch` returns a
- * web `ReadableStream<Uint8Array>` body; this parser turns that into
- * an async iterable of `SseFrame`s.
- *
- * The wire grammar follows the WHATWG HTML spec § Server-sent events:
- *
- *   - Lines are separated by `\n`, `\r`, or `\r\n`.
- *   - A `:` prefix marks a comment — ignored.
- *   - `field: value` (or `field:value`, with no space) — leading space
- *     after the colon is stripped.
- *   - Recognised fields: `event`, `data`, `id`, `retry`.
- *   - Multiple `data:` lines join with `\n`.
- *   - A blank line dispatches the current frame and resets the buffer.
- *   - `event:` defaults to `"message"` when absent.
- *
- * The parser is deliberately a free function so it can be unit-tested
- * against synthesized chunk boundaries (one byte at a time, mid-frame,
- * across UTF-8 multi-byte sequences) without spinning up a real
- * connection.
- */
-/**
- * Stateful parser: feed in chunks (in any size), pull out completed
- * frames. Designed for `for await` consumption — see `iterateSse`.
- */
-export class SseParser {
-    #buffer = "";
-    #decoder = new TextDecoder("utf-8");
-    #eventType = "";
-    #dataLines = [];
-    #lastEventId;
-    #retry;
-    /**
-     * Push a chunk of raw bytes through the parser. Returns any frames
-     * that completed during this chunk. Chunks may contain zero, one,
-     * or many frame boundaries — the parser handles partial trailing
-     * data internally.
-     */
-    pushBytes(chunk) {
-        return this.pushText(this.#decoder.decode(chunk, { stream: true }));
-    }
-    /**
-     * Push a text chunk directly. Used by the parser tests so they can
-     * exercise byte-boundary edge cases without manufacturing a
-     * `TextDecoder` round-trip.
-     */
-    pushText(text) {
-        this.#buffer += text;
-        const frames = [];
-        let idx;
-        // SSE accepts \n, \r\n, or \r as the line terminator. Normalize by
-        // splitting on any of them — but only split on a complete line
-        // (we leave trailing partial bytes in the buffer).
-        while ((idx = findLineBreak(this.#buffer)) !== -1) {
-            const line = this.#buffer.slice(0, idx);
-            // A trailing CR may be the first half of a CRLF split across chunks.
-            // A blank trailing CR can dispatch immediately without splitting data.
-            if (this.#buffer[idx] === "\r" && idx === this.#buffer.length - 1 && line.length > 0)
-                break;
-            const skip = this.#buffer[idx] === "\r" && this.#buffer[idx + 1] === "\n" ? 2 : 1;
-            this.#buffer = this.#buffer.slice(idx + skip);
-            const frame = this.#consumeLine(line);
-            if (frame)
-                frames.push(frame);
-        }
-        return frames;
-    }
-    /**
-     * Indicate end-of-stream. Returns any final frame that the dispatcher
-     * was holding when the stream closed mid-frame (no trailing blank
-     * line). The dispatcher pattern is: blank line dispatches; if the
-     * remote closes after a partial frame, that frame is dropped per the
-     * spec.
-     */
-    flush() {
-        // No-op for now — partial frames are discarded per spec. Kept as
-        // an extension point in case callers want a "soft flush" later.
-    }
-    #consumeLine(line) {
-        if (line.length === 0) {
-            // Blank line → dispatch the current frame.
-            return this.#dispatch();
-        }
-        if (line.startsWith(":")) {
-            // Comment — ignored.
-            return null;
-        }
-        const colonIdx = line.indexOf(":");
-        let field;
-        let value;
-        if (colonIdx === -1) {
-            field = line;
-            value = "";
-        }
-        else {
-            field = line.slice(0, colonIdx);
-            value = line.slice(colonIdx + 1);
-            if (value.startsWith(" "))
-                value = value.slice(1);
-        }
-        switch (field) {
-            case "event":
-                this.#eventType = value;
-                break;
-            case "data":
-                this.#dataLines.push(value);
-                break;
-            case "id":
-                // Per spec: empty id sets last id to empty string; ids
-                // containing U+0000 are ignored. We adopt the simple
-                // policy and just store the verbatim value.
-                if (!value.includes("\0")) {
-                    this.#lastEventId = value;
-                }
-                break;
-            case "retry": {
-                const parsed = Number.parseInt(value, 10);
-                if (Number.isFinite(parsed) && parsed >= 0)
-                    this.#retry = parsed;
-                break;
-            }
-            default:
-                // Unknown field — ignored per spec.
-                break;
-        }
-        return null;
-    }
-    #dispatch() {
-        if (this.#dataLines.length === 0 && this.#eventType === "") {
-            // Nothing to dispatch — a blank line on its own resets nothing.
-            return null;
-        }
-        const data = this.#dataLines.join("\n");
-        const event = this.#eventType === "" ? "message" : this.#eventType;
-        const frame = {
-            event,
-            data,
-            ...(this.#lastEventId !== undefined ? { id: this.#lastEventId } : {}),
-            ...(this.#retry !== undefined ? { retry: this.#retry } : {})
-        };
-        // Reset per-frame state. `lastEventId` and `retry` PERSIST across
-        // frames per spec — they are connection-level, not frame-level.
-        this.#eventType = "";
-        this.#dataLines = [];
-        this.#retry = undefined;
-        return frame;
-    }
-    /**
-     * Current "last event id" — the cursor the SSE spec instructs the
-     * client to replay on automatic reconnection. Callers use this to
-     * resume after a disconnect.
-     */
-    get lastEventId() {
-        return this.#lastEventId;
-    }
-}
-/**
- * Convert a web `ReadableStream<Uint8Array>` (the body of a fetch
- * Response) into an async iterable of SSE frames. The stream is
- * consumed exactly once; the caller is responsible for cancelling
- * the underlying reader on abort.
- *
- * The reader is raced against the abort signal so a long-blocked
- * server (no chunks for many seconds) still releases the loop
- * promptly when the consumer aborts.
- */
-export async function* iterateSse(body, signal) {
-    const reader = body.getReader();
-    const parser = new SseParser();
-    const ABORT_SENTINEL = Symbol("aborted");
-    try {
-        while (true) {
-            if (signal?.aborted)
-                return;
-            const readPromise = reader.read();
-            let result;
-            if (signal) {
-                result = await Promise.race([
-                    readPromise,
-                    new Promise((resolve) => {
-                        const onAbort = () => resolve(ABORT_SENTINEL);
-                        if (signal.aborted) {
-                            resolve(ABORT_SENTINEL);
-                            return;
-                        }
-                        signal.addEventListener("abort", onAbort, { once: true });
-                    })
-                ]);
-            }
-            else {
-                result = await readPromise;
-            }
-            if (result === ABORT_SENTINEL)
-                return;
-            if (result.done) {
-                parser.flush();
-                return;
-            }
-            const value = result.value;
-            if (!value)
-                continue;
-            const frames = parser.pushBytes(value);
-            for (const frame of frames) {
-                yield frame;
-            }
-        }
-    }
-    finally {
-        try {
-            await reader.cancel();
-        }
-        catch {
-            // Cancel can throw if the stream is already closed — ignore.
-        }
-    }
-}
-function findLineBreak(buffer) {
-    // Returns the index of the first \n or \r in `buffer`, or -1.
-    for (let i = 0; i < buffer.length; i++) {
-        const code = buffer.charCodeAt(i);
-        if (code === 0x0a || code === 0x0d)
-            return i;
-    }
-    return -1;
-}

package/dist/_contracts/stable.d.ts

@@ -1,45 +0,0 @@
-/**
- * Canonical hosted aex API plane URL. Used as the default `baseUrl`
- * for the SDK `Aex` client and the host-side CLI `--aex-url`
- * flag.
- *
- * Pinned to `api.aex.dev` on purpose: the dashboard at
- * `aex.dev` is the human UX surface, while `api.aex.dev`
- * owns the runtime/API plane (session submission, provider proxy, MCP
- * proxy, runner callbacks). Both the apex `aex.dev` and `www.` host
- * may issue redirects, and HTTP clients strip the `Authorization`
- * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
- * would make authenticated calls land as 401s. Always go direct to
- * the API plane.
- *
- * A single canonical default is not a "footnote mode" — it is the
- * canonical product. Self-hosted deployments override via the
- * explicit `baseUrl` / `--aex-url` parameter. The value lives in
- * source (no env-var override) so the agent reading the SDK call site
- * can see exactly where the call goes.
- *
- * Kept in source with no env-var override so callers and agents can see the
- * 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 routes to `dev-api.aex.dev` and a prd key routes to
- * `api.aex.dev`.
- *
- * 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: "https://dev-api.aex.dev";
-    readonly prd: "https://api.aex.dev";
-};
-export declare function stableStringify(value: unknown): string;
-export declare function sha256(value: unknown): string;

package/dist/_contracts/stable.js

@@ -1,62 +0,0 @@
-import { createHash } from "node:crypto";
-/**
- * Canonical hosted aex API plane URL. Used as the default `baseUrl`
- * for the SDK `Aex` client and the host-side CLI `--aex-url`
- * flag.
- *
- * Pinned to `api.aex.dev` on purpose: the dashboard at
- * `aex.dev` is the human UX surface, while `api.aex.dev`
- * owns the runtime/API plane (session submission, provider proxy, MCP
- * proxy, runner callbacks). Both the apex `aex.dev` and `www.` host
- * may issue redirects, and HTTP clients strip the `Authorization`
- * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
- * would make authenticated calls land as 401s. Always go direct to
- * the API plane.
- *
- * A single canonical default is not a "footnote mode" — it is the
- * canonical product. Self-hosted deployments override via the
- * explicit `baseUrl` / `--aex-url` parameter. The value lives in
- * source (no env-var override) so the agent reading the SDK call site
- * can see exactly where the call goes.
- *
- * Kept in source with no env-var override so callers and agents can see the
- * 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 routes to `dev-api.aex.dev` and a prd key routes to
- * `api.aex.dev`.
- *
- * 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: AEX_DEV_BASE_URL,
-    prd: AEX_DEFAULT_BASE_URL
-};
-export function stableStringify(value) {
-    return JSON.stringify(sortValue(value));
-}
-export function sha256(value) {
-    return createHash("sha256").update(typeof value === "string" ? value : stableStringify(value)).digest("hex");
-}
-function sortValue(value) {
-    if (Array.isArray(value)) {
-        return value.map(sortValue);
-    }
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value)
-            .filter(([, item]) => item !== undefined)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([key, item]) => [key, sortValue(item)]));
-    }
-    return value;
-}

package/dist/_contracts/status.d.ts

@@ -1,25 +0,0 @@
-/**
- * The RESUMABLE / in-flight lifecycle half of a session's status. A session
- * whose status is one of these is either transitioning, parked and resumable,
- * or being removed. A prior run's verdict is not projected into this field;
- * read `lastRun.outcome` or the terminal RUN event instead. In particular,
- * `error` means the most recent run failed while the thread remains resumable.
- */
-export declare const SESSION_LIFECYCLE_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "awaiting_approval", "error", "cancelling", "deleting", "deleted", "expired"];
-export type SessionLifecycleStatus = typeof SESSION_LIFECYCLE_STATUSES[number];
-/**
- * Terminal RUN outcomes. These describe a completed run, not the lifecycle
- * status of its resumable session thread.
- */
-export declare const SESSION_TERMINAL_OUTCOMES: readonly ["succeeded", "failed", "timed_out", "cancelled", "interrupted"];
-export type SessionTerminalOutcome = typeof SESSION_TERMINAL_OUTCOMES[number];
-/**
- * The full closed set of session lifecycle statuses. Run outcomes deliberately
- * remain separate so a resumable session never reports `succeeded`/`failed`.
- */
-export declare const SESSION_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "awaiting_approval", "error", "cancelling", "deleting", "deleted", "expired"];
-export type SessionStatus = SessionLifecycleStatus;
-/** True when a session thread has been deleted or expired. */
-export declare function isTerminalSessionStatus(status: SessionStatus): boolean;
-export declare const CLEANUP_STATUSES: readonly ["not_started", "pending", "running", "succeeded", "failed_retryable", "failed_terminal", "skipped"];
-export type CleanupStatus = typeof CLEANUP_STATUSES[number];

package/dist/_contracts/status.js

@@ -1,57 +0,0 @@
-/**
- * The RESUMABLE / in-flight lifecycle half of a session's status. A session
- * whose status is one of these is either transitioning, parked and resumable,
- * or being removed. A prior run's verdict is not projected into this field;
- * read `lastRun.outcome` or the terminal RUN event instead. In particular,
- * `error` means the most recent run failed while the thread remains resumable.
- */
-export const SESSION_LIFECYCLE_STATUSES = [
-    "creating",
-    "running",
-    "idle",
-    "suspending",
-    "suspended",
-    "awaiting_approval",
-    "error",
-    "cancelling",
-    "deleting",
-    "deleted",
-    "expired"
-];
-/**
- * Terminal RUN outcomes. These describe a completed run, not the lifecycle
- * status of its resumable session thread.
- */
-export const SESSION_TERMINAL_OUTCOMES = [
-    "succeeded",
-    "failed",
-    "timed_out",
-    "cancelled",
-    "interrupted"
-];
-/**
- * The full closed set of session lifecycle statuses. Run outcomes deliberately
- * remain separate so a resumable session never reports `succeeded`/`failed`.
- */
-export const SESSION_STATUSES = SESSION_LIFECYCLE_STATUSES;
-/**
- * Only removal makes a session thread terminal. Run outcomes are intentionally
- * not session statuses.
- */
-const SESSION_TERMINAL_STATUSES = new Set([
-    "deleted",
-    "expired"
-]);
-/** True when a session thread has been deleted or expired. */
-export function isTerminalSessionStatus(status) {
-    return SESSION_TERMINAL_STATUSES.has(status);
-}
-export const CLEANUP_STATUSES = [
-    "not_started",
-    "pending",
-    "running",
-    "succeeded",
-    "failed_retryable",
-    "failed_terminal",
-    "skipped"
-];

package/dist/_contracts/submission-limits.d.ts

@@ -1,61 +0,0 @@
-/**
- * Bounds and patterns the submission schemas enforce.
- *
- * A leaf module with no imports. It exists so `schemas/submission-environment.ts`
- * can read these without importing `submission.ts`, which imports the schema
- * back — a cycle that would leave the constants `undefined` at the moment the
- * schemas are constructed at module load.
- *
- * `submission.ts` re-exports every public name from here, so the published
- * surface is unchanged.
- */
-/**
- * Reserved prefix for aex-set runtime env vars (`AEX_CLI`,
- * `AEX_RUNTIME_JSON`, …). Customer `environment.envVars` keys carrying this
- * prefix are rejected at submission parse time so platform-set values
- * cannot be silently overwritten.
- */
-export declare const AEX_RESERVED_ENV_PREFIX = "AEX_";
-/**
- * Maximum number of `environment.envVars` entries accepted per
- * submission. Picked to be generous for real customer config bags
- * (the broll case ships a handful — `BROLL_STORE`, `BROLL_OUTPUTS`,
- * `BROLL_MODE`, …) while still bounding the size of every RUNTIME
- * file we mount into the container.
- */
-export declare const ENV_VARS_MAX_ENTRIES = 64;
-/** Maximum byte length of a single `environment.envVars` value. */
-export declare const ENV_VARS_MAX_VALUE_BYTES = 4096;
-/** Maximum total byte length of all `environment.envVars` keys+values combined. */
-export declare const ENV_VARS_MAX_TOTAL_BYTES = 65536;
-/**
- * POSIX-shell-portable env var key: starts with `A-Z` or `_`, body is
- * `A-Z`, `0-9`, `_`. We deliberately reject lowercase to keep
- * `RUNTIME.env` readable and consistent with platform conventions; if
- * a customer has lowercase keys today, they uppercase them at the
- * call site.
- */
-export declare const ENV_VAR_KEY_PATTERN: RegExp;
-/**
- * Package-manager ecosystems accepted by the public submission schema.
- * The customer encodes the target manager as a `name` prefix
- * `"<eco>:<pkg>"` (e.g. "pip:pandas", "npm:express", "apt:ffmpeg"); an
- * UNPREFIXED name defaults to `apt`. After parsing, `PlatformPackage.name`
- * is the bare package and `PlatformPackage.ecosystem` is the resolved
- * manager.
- */
-export declare const PLATFORM_PACKAGE_ECOSYSTEMS: readonly ["apt", "npm", "pip"];
-export type PlatformPackageEcosystem = (typeof PLATFORM_PACKAGE_ECOSYSTEMS)[number];
-/** POSIX-style env var name a `secretEnv` entry binds to (e.g. `SERPER_API_KEY`). */
-export declare const SECRET_ENV_NAME_PATTERN: RegExp;
-/**
- * Workspace secret handle a `secretEnv` ref points at (and the name
- * `secret.upload` persists to).
- */
-export declare const SECRET_HANDLE_PATTERN: RegExp;
-/**
- * Namespace reserved for platform-set values inside the secrets channel. A
- * caller-supplied key carrying it is rejected with its own message rather than
- * the generic unknown-field one, so the reason is legible.
- */
-export declare const PLATFORM_INTERNAL_SECRET_PREFIX = "__aex_";

package/dist/_contracts/submission-limits.js

@@ -1,60 +0,0 @@
-/**
- * Bounds and patterns the submission schemas enforce.
- *
- * A leaf module with no imports. It exists so `schemas/submission-environment.ts`
- * can read these without importing `submission.ts`, which imports the schema
- * back — a cycle that would leave the constants `undefined` at the moment the
- * schemas are constructed at module load.
- *
- * `submission.ts` re-exports every public name from here, so the published
- * surface is unchanged.
- */
-/**
- * Reserved prefix for aex-set runtime env vars (`AEX_CLI`,
- * `AEX_RUNTIME_JSON`, …). Customer `environment.envVars` keys carrying this
- * prefix are rejected at submission parse time so platform-set values
- * cannot be silently overwritten.
- */
-export const AEX_RESERVED_ENV_PREFIX = "AEX_";
-/**
- * Maximum number of `environment.envVars` entries accepted per
- * submission. Picked to be generous for real customer config bags
- * (the broll case ships a handful — `BROLL_STORE`, `BROLL_OUTPUTS`,
- * `BROLL_MODE`, …) while still bounding the size of every RUNTIME
- * file we mount into the container.
- */
-export const ENV_VARS_MAX_ENTRIES = 64;
-/** Maximum byte length of a single `environment.envVars` value. */
-export const ENV_VARS_MAX_VALUE_BYTES = 4096;
-/** Maximum total byte length of all `environment.envVars` keys+values combined. */
-export const ENV_VARS_MAX_TOTAL_BYTES = 65536;
-/**
- * POSIX-shell-portable env var key: starts with `A-Z` or `_`, body is
- * `A-Z`, `0-9`, `_`. We deliberately reject lowercase to keep
- * `RUNTIME.env` readable and consistent with platform conventions; if
- * a customer has lowercase keys today, they uppercase them at the
- * call site.
- */
-export const ENV_VAR_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
-/**
- * Package-manager ecosystems accepted by the public submission schema.
- * The customer encodes the target manager as a `name` prefix
- * `"<eco>:<pkg>"` (e.g. "pip:pandas", "npm:express", "apt:ffmpeg"); an
- * UNPREFIXED name defaults to `apt`. After parsing, `PlatformPackage.name`
- * is the bare package and `PlatformPackage.ecosystem` is the resolved
- * manager.
- */
-export const PLATFORM_PACKAGE_ECOSYSTEMS = ["apt", "npm", "pip"];
-/** POSIX-style env var name a `secretEnv` entry binds to (e.g. `SERPER_API_KEY`). */
-export const SECRET_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
-/**
- * Workspace secret handle a `secretEnv` ref points at (and the name
- * `secret.upload` persists to).
- */
-export const SECRET_HANDLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-/**
- * Namespace reserved for platform-set values inside the secrets channel. A
- * caller-supplied key carrying it is rejected with its own message rather than
- * the generic unknown-field one, so the reason is legible.
- */
-export const PLATFORM_INTERNAL_SECRET_PREFIX = "__aex_";