@aexhq/sdk 0.13.6

package/dist/_contracts/event-stream-client.js

@@ -0,0 +1,141 @@
+/**
+ * Client-side consumer of the event coordinator's WebSocket stream.
+ *
+ * One mechanism for catch-up + resume + live: subscribe = read-from-cursor +
+ * tail. The consumer opens a WS to the coordinator with a connection ticket,
+ * replays from its cursor, and yields {@link AexEvent}s as they arrive.
+ * On a transport drop it reconnects with backoff and resumes from the last
+ * sequence it saw — `from = lastSeq + 1` — so delivery is exactly-once across
+ * reconnects (no gap, no duplicate). It stops on a terminal event, on abort,
+ * or when the caller breaks the iterator.
+ *
+ * Filtering and projection are the client's concern (the wire carries the
+ * whole run): compose {@link filterStream} with the envelope guards, and
+ * {@link mapStream} with {@link toAGUI}, on top of this stream.
+ *
+ * The WebSocket is injectable so the SDK/CLI use the Node/global `WebSocket`
+ * (Node 22+ ships it; no dependency) and tests drive a fake.
+ */
+const isTerminalType = (t) => t === "RUN_FINISHED" || t === "RUN_ERROR";
+export async function* streamCoordinatorEvents(opts) {
+    const makeWs = opts.webSocketFactory ?? ((url) => new WebSocket(url));
+    const reconnectDelayMs = opts.reconnectDelayMs ?? 500;
+    const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
+    let cursor = (opts.from ?? 0) - 1;
+    let attempts = 0;
+    let done = false;
+    while (!done && !opts.signal?.aborted) {
+        const ticket = await opts.fetchTicket();
+        const url = `${opts.wsUrl}?ticket=${encodeURIComponent(ticket)}&from=${cursor + 1}`;
+        const ws = makeWs(url);
+        const queue = [];
+        let closed = false;
+        let disconnectReason = "";
+        let resolveNext = null;
+        const wake = () => {
+            if (resolveNext) {
+                const r = resolveNext;
+                resolveNext = null;
+                r();
+            }
+        };
+        ws.addEventListener("message", (ev) => {
+            const data = typeof ev.data === "string" ? ev.data : "";
+            if (!data)
+                return;
+            try {
+                const evt = JSON.parse(data);
+                if (typeof evt.sequence === "number" && evt.sequence > cursor) {
+                    queue.push(evt);
+                    wake();
+                }
+            }
+            catch {
+                // ignore a non-JSON frame
+            }
+        });
+        ws.addEventListener("close", (ev) => {
+            closed = true;
+            const code = ev?.code;
+            disconnectReason = `close${typeof code === "number" ? ` code=${code}` : ""}`;
+            wake();
+        });
+        ws.addEventListener("error", () => {
+            closed = true;
+            disconnectReason = "error";
+            wake();
+        });
+        const onAbort = () => {
+            closeQuietly(ws);
+            closed = true;
+            wake();
+        };
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            while (true) {
+                while (queue.length > 0) {
+                    const evt = queue.shift();
+                    cursor = evt.sequence;
+                    yield evt;
+                    if (isTerminalType(evt.type))
+                        done = true;
+                }
+                if (done || opts.signal?.aborted) {
+                    closeQuietly(ws);
+                    break;
+                }
+                if (closed)
+                    break; // transport ended → fall through to reconnect
+                await new Promise((resolve) => {
+                    resolveNext = resolve;
+                });
+            }
+        }
+        finally {
+            opts.signal?.removeEventListener("abort", onAbort);
+        }
+        if (done || opts.signal?.aborted)
+            return;
+        attempts += 1;
+        // Don't let the stream die silently — a give-up before the terminal event
+        // is exactly the case a caller needs to see (it looks like a clean end
+        // otherwise). Reconnects are rare, so the warn volume is bounded.
+        if (attempts > maxReconnects) {
+            console.warn(`[aex] event stream gave up after ${maxReconnects} reconnect attempt(s) (last: ${disconnectReason || "unknown"}); ended before a terminal event at seq ${cursor + 1}`);
+            return;
+        }
+        console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
+        await sleep(reconnectDelayMs, opts.signal);
+    }
+}
+/** Async-iterable filter — keep only events matching the predicate. */
+export async function* filterStream(stream, predicate) {
+    for await (const event of stream) {
+        if (predicate(event))
+            yield event;
+    }
+}
+/** Async-iterable map — project each event (e.g. with `toAGUI`). */
+export async function* mapStream(stream, project) {
+    for await (const event of stream) {
+        yield project(event);
+    }
+}
+function closeQuietly(ws) {
+    try {
+        ws.close();
+    }
+    catch {
+        // already closed
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=event-stream-client.js.map

package/dist/_contracts/http.d.ts

@@ -0,0 +1,35 @@
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Sink for local debug traces. Receives one preformatted line per HTTP
+ * round-trip (method, path, status, elapsed). NEVER carries the auth
+ * header, request/response bodies, or query string — purely a local
+ * diagnostic; nothing is uploaded. The SDK wires this to `console.error`
+ * when `debug` is set; the CLI wires it to stderr under `--debug`.
+ */
+export type DebugSink = (line: string) => void;
+export interface HttpClientOptions {
+    /**
+     * API plane root. Optional — defaults to `AEX_DEFAULT_BASE_URL`
+     * (`https://api.aex.dev`). Self-hosted deployments override with their
+     * own URL; no env var consults this value.
+     */
+    readonly baseUrl?: string;
+    readonly apiToken: string;
+    readonly fetch?: FetchLike;
+    /** When set, every request emits a redacted one-line trace here. */
+    readonly debug?: DebugSink;
+}
+/**
+ * Thin transport used by every BFF-bound operation. The SDK class and
+ * the CLI subcommands BOTH build an `HttpClient` and pass it to the
+ * operations module — so they cannot drift in how they auth, encode
+ * query parameters, or decode error responses.
+ */
+export declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    request<T>(path: string, init?: RequestInit, query?: Record<string, string>): Promise<T>;
+    download(path: string, init?: RequestInit, query?: Record<string, string>): Promise<{
+        readonly response: Response;
+    }>;
+}

package/dist/_contracts/http.js

@@ -0,0 +1,114 @@
+import { AexApiError } from "./sdk-errors.js";
+import { AEX_DEFAULT_BASE_URL } from "./stable.js";
+/**
+ * Thin transport used by every BFF-bound operation. The SDK class and
+ * the CLI subcommands BOTH build an `HttpClient` and pass it to the
+ * operations module — so they cannot drift in how they auth, encode
+ * query parameters, or decode error responses.
+ */
+export class HttpClient {
+    #baseUrl;
+    #apiToken;
+    #fetch;
+    #debug;
+    constructor(options) {
+        if (!options.apiToken) {
+            throw new Error("HttpClient: apiToken is required");
+        }
+        const raw = options.baseUrl ?? AEX_DEFAULT_BASE_URL;
+        const normalized = raw.endsWith("/") ? raw : `${raw}/`;
+        this.#baseUrl = new URL(normalized);
+        this.#apiToken = options.apiToken;
+        this.#fetch = options.fetch ?? fetch;
+        this.#debug = options.debug;
+    }
+    /** Emit a redacted round-trip trace (no auth header, body, or query). */
+    #trace(method, url, status, startedMs) {
+        this.#debug?.(`[aex] ${(method ?? "GET").toUpperCase()} ${url.pathname} -> ${status} ${Date.now() - startedMs}ms`);
+    }
+    async request(path, init = {}, query = {}) {
+        const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
+        for (const [key, value] of Object.entries(query)) {
+            url.searchParams.set(key, value);
+        }
+        const headers = {
+            accept: "application/json",
+            authorization: `Bearer ${this.#apiToken}`,
+            ...normalizeHeaders(init.headers)
+        };
+        if (init.body !== undefined && init.body !== null && !headers["content-type"]) {
+            // Default to JSON only for string-shaped bodies. FormData / Blob /
+            // ArrayBuffer / streams set their own content-type (and FormData
+            // specifically needs fetch to compute the multipart boundary), so
+            // we leave content-type untouched for non-string bodies.
+            if (typeof init.body === "string") {
+                headers["content-type"] = "application/json";
+            }
+        }
+        const startedMs = Date.now();
+        const response = await this.#fetch(url, { ...init, headers });
+        this.#trace(init.method, url, response.status, startedMs);
+        const body = await readJson(response);
+        if (!response.ok) {
+            throw new AexApiError(response.status, extractErrorMessage(body), body);
+        }
+        return body;
+    }
+    async download(path, init = {}, query = {}) {
+        const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
+        for (const [key, value] of Object.entries(query)) {
+            url.searchParams.set(key, value);
+        }
+        const headers = {
+            authorization: `Bearer ${this.#apiToken}`,
+            ...normalizeHeaders(init.headers)
+        };
+        const startedMs = Date.now();
+        const response = await this.#fetch(url, { ...init, headers });
+        this.#trace(init.method, url, response.status, startedMs);
+        if (!response.ok) {
+            const body = await readJson(response);
+            throw new AexApiError(response.status, extractErrorMessage(body), body);
+        }
+        return { response };
+    }
+}
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return headers;
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function extractErrorMessage(body) {
+    if (body && typeof body === "object") {
+        const obj = body;
+        if (typeof obj.error === "string")
+            return obj.error;
+        if (obj.error && typeof obj.error === "object" && "message" in obj.error) {
+            const message = obj.error.message;
+            if (typeof message === "string")
+                return message;
+        }
+        // aex Worker 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")
+            return obj.message;
+    }
+    return "aex API request failed";
+}
+//# sourceMappingURL=http.js.map

package/dist/_contracts/index.d.ts

@@ -0,0 +1,28 @@
+export * from "./proxy-protocol.js";
+export * from "./provider-support.js";
+export * from "./status.js";
+export * from "./submission.js";
+export * from "./runtime-sizes.js";
+export * from "./runner-event.js";
+export * from "./event-envelope.js";
+export * from "./connection-ticket.js";
+export * from "./event-stream-client.js";
+export * from "./run-unit.js";
+export * from "./runtime-manifest.js";
+export * from "./runtime-security-profile.js";
+export * from "./run-record.js";
+export * from "./run-cost.js";
+export * from "./run-custody.js";
+export * from "./run-retention.js";
+export * from "./side-effect-audit.js";
+export * from "./managed-key.js";
+export * from "./stable.js";
+export * from "./sdk-secrets.js";
+export * from "./sdk-errors.js";
+export * from "./run-config.js";
+export * from "./runtime-types.js";
+export * from "./http.js";
+export * from "./run-artifacts.js";
+export * as operations from "./operations.js";
+export * from "./proxy-validation.js";
+export * from "./sse.js";

package/dist/_contracts/index.js

@@ -0,0 +1,29 @@
+export * from "./proxy-protocol.js";
+export * from "./provider-support.js";
+export * from "./status.js";
+export * from "./submission.js";
+export * from "./runtime-sizes.js";
+export * from "./runner-event.js";
+export * from "./event-envelope.js";
+export * from "./connection-ticket.js";
+export * from "./event-stream-client.js";
+export * from "./run-unit.js";
+export * from "./runtime-manifest.js";
+export * from "./runtime-security-profile.js";
+export * from "./run-record.js";
+export * from "./run-cost.js";
+export * from "./run-custody.js";
+export * from "./run-retention.js";
+export * from "./side-effect-audit.js";
+export * from "./managed-key.js";
+export * from "./stable.js";
+export * from "./sdk-secrets.js";
+export * from "./sdk-errors.js";
+export * from "./run-config.js";
+export * from "./runtime-types.js";
+export * from "./http.js";
+export * from "./run-artifacts.js";
+export * as operations from "./operations.js";
+export * from "./proxy-validation.js";
+export * from "./sse.js";
+//# sourceMappingURL=index.js.map

package/dist/_contracts/managed-key.d.ts

@@ -0,0 +1,74 @@
+import type { RunProvider, RuntimeKind } from "./submission.js";
+export declare const CREDENTIAL_MODES: readonly ["byok", "managed"];
+export type CredentialMode = (typeof CREDENTIAL_MODES)[number];
+export declare const DEFAULT_CREDENTIAL_MODE: CredentialMode;
+export declare const MANAGED_KEY_POLICY_SCHEMA_VERSION = 1;
+export declare const MANAGED_KEY_LAUNCH_STAGES: readonly ["blocked", "pilot", "ga"];
+export type ManagedKeyLaunchStage = (typeof MANAGED_KEY_LAUNCH_STAGES)[number];
+export declare const MANAGED_KEY_FEATURE_DECISIONS: readonly ["disabled", "allowed"];
+export type ManagedKeyFeatureDecision = (typeof MANAGED_KEY_FEATURE_DECISIONS)[number];
+export interface ManagedKeyFeaturePolicyV1 {
+    readonly files: ManagedKeyFeatureDecision;
+    readonly packages: ManagedKeyFeatureDecision;
+    readonly builtins: ManagedKeyFeatureDecision;
+    readonly mcpServers: ManagedKeyFeatureDecision;
+    readonly proxyEndpoints: ManagedKeyFeatureDecision;
+    readonly openNetworking: ManagedKeyFeatureDecision;
+}
+/**
+ * Public managed-key policy contract. Concrete policy values, account
+ * selection, financial calculation, and deployment wiring live outside this
+ * public module.
+ */
+export interface ManagedKeyPolicyV1 {
+    readonly schemaVersion: typeof MANAGED_KEY_POLICY_SCHEMA_VERSION;
+    readonly credentialMode: "managed";
+    readonly launchStage: ManagedKeyLaunchStage;
+    readonly serviceAvailable: boolean;
+    readonly billingRequired: true;
+    readonly providers: readonly RunProvider[];
+    readonly runtimes: readonly RuntimeKind[];
+    readonly models?: readonly string[];
+    readonly features: ManagedKeyFeaturePolicyV1;
+}
+export declare const BLOCKED_MANAGED_KEY_FEATURE_POLICY_V1: ManagedKeyFeaturePolicyV1;
+export declare const BLOCKED_MANAGED_KEY_POLICY_V1: ManagedKeyPolicyV1;
+export declare class ManagedKeyUnavailableError extends Error {
+    readonly code = "managed_key_unavailable";
+    constructor(message?: string);
+}
+export declare function parseCredentialMode(input: unknown): CredentialMode;
+export declare function credentialModeOrDefault(input: CredentialMode | undefined): CredentialMode;
+export declare function isCredentialMode(input: unknown): input is CredentialMode;
+export declare function isManagedKeyGenerallyAvailable(policy: ManagedKeyPolicyV1): boolean;
+export declare function isManagedKeyAdmissionAllowed(policy: ManagedKeyPolicyV1): boolean;
+export declare function assertManagedKeyModeAvailable(policy?: ManagedKeyPolicyV1): void;
+export declare function assertManagedKeyAdmissionAllowed(policy?: ManagedKeyPolicyV1): void;
+export interface ManagedCredentialResolutionInput {
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly provider: RunProvider;
+    readonly runtime: RuntimeKind;
+    readonly model: string;
+    readonly policy: ManagedKeyPolicyV1;
+}
+export interface ManagedCredentialLease {
+    readonly credentialMode: "managed";
+    readonly provider: RunProvider;
+    readonly runtime: RuntimeKind;
+    readonly custodyClass: "managed-provider-credential";
+}
+export type ManagedCredentialResolution = {
+    readonly ok: true;
+    readonly lease: ManagedCredentialLease;
+} | {
+    readonly ok: false;
+    readonly code: "managed_key_unavailable" | "provider_not_allowed" | "runtime_not_allowed" | "model_not_allowed";
+    readonly message: string;
+};
+export interface ManagedCredentialResolver {
+    resolveManagedCredential(input: ManagedCredentialResolutionInput): Promise<ManagedCredentialResolution>;
+}
+export declare class FakeManagedCredentialResolver implements ManagedCredentialResolver {
+    resolveManagedCredential(input: ManagedCredentialResolutionInput): Promise<ManagedCredentialResolution>;
+}

package/dist/_contracts/managed-key.js

@@ -0,0 +1,110 @@
+export const CREDENTIAL_MODES = ["byok", "managed"];
+export const DEFAULT_CREDENTIAL_MODE = "byok";
+export const MANAGED_KEY_POLICY_SCHEMA_VERSION = 1;
+export const MANAGED_KEY_LAUNCH_STAGES = ["blocked", "pilot", "ga"];
+export const MANAGED_KEY_FEATURE_DECISIONS = ["disabled", "allowed"];
+export const BLOCKED_MANAGED_KEY_FEATURE_POLICY_V1 = Object.freeze({
+    files: "disabled",
+    packages: "disabled",
+    builtins: "disabled",
+    mcpServers: "disabled",
+    proxyEndpoints: "disabled",
+    openNetworking: "disabled"
+});
+export const BLOCKED_MANAGED_KEY_POLICY_V1 = Object.freeze({
+    schemaVersion: MANAGED_KEY_POLICY_SCHEMA_VERSION,
+    credentialMode: "managed",
+    launchStage: "blocked",
+    serviceAvailable: false,
+    billingRequired: true,
+    providers: Object.freeze([]),
+    runtimes: Object.freeze([]),
+    features: BLOCKED_MANAGED_KEY_FEATURE_POLICY_V1
+});
+export class ManagedKeyUnavailableError extends Error {
+    code = "managed_key_unavailable";
+    constructor(message = "credentialMode: \"managed\" is not available") {
+        super(message);
+        this.name = "ManagedKeyUnavailableError";
+    }
+}
+export function parseCredentialMode(input) {
+    if (input === undefined) {
+        return DEFAULT_CREDENTIAL_MODE;
+    }
+    if (!isCredentialMode(input)) {
+        throw new Error(`credentialMode must be one of: ${CREDENTIAL_MODES.join(", ")} (got ${JSON.stringify(input)})`);
+    }
+    return input;
+}
+export function credentialModeOrDefault(input) {
+    return input ?? DEFAULT_CREDENTIAL_MODE;
+}
+export function isCredentialMode(input) {
+    return typeof input === "string" && CREDENTIAL_MODES.includes(input);
+}
+export function isManagedKeyGenerallyAvailable(policy) {
+    return policy.launchStage === "ga" && policy.serviceAvailable;
+}
+export function isManagedKeyAdmissionAllowed(policy) {
+    return policy.launchStage !== "blocked" && policy.serviceAvailable;
+}
+export function assertManagedKeyModeAvailable(policy = BLOCKED_MANAGED_KEY_POLICY_V1) {
+    if (!isManagedKeyGenerallyAvailable(policy)) {
+        throw new ManagedKeyUnavailableError();
+    }
+}
+export function assertManagedKeyAdmissionAllowed(policy = BLOCKED_MANAGED_KEY_POLICY_V1) {
+    if (!isManagedKeyAdmissionAllowed(policy)) {
+        throw new ManagedKeyUnavailableError();
+    }
+}
+export class FakeManagedCredentialResolver {
+    async resolveManagedCredential(input) {
+        const denial = resolvePolicyDenial(input);
+        if (denial) {
+            return denial;
+        }
+        return {
+            ok: true,
+            lease: Object.freeze({
+                credentialMode: "managed",
+                provider: input.provider,
+                runtime: input.runtime,
+                custodyClass: "managed-provider-credential"
+            })
+        };
+    }
+}
+function resolvePolicyDenial(input) {
+    if (!isManagedKeyGenerallyAvailable(input.policy)) {
+        return {
+            ok: false,
+            code: "managed_key_unavailable",
+            message: "managed-key mode is not generally available for this public policy"
+        };
+    }
+    if (!input.policy.providers.includes(input.provider)) {
+        return {
+            ok: false,
+            code: "provider_not_allowed",
+            message: `provider ${input.provider} is not allowed by managed-key policy`
+        };
+    }
+    if (!input.policy.runtimes.includes(input.runtime)) {
+        return {
+            ok: false,
+            code: "runtime_not_allowed",
+            message: `runtime ${input.runtime} is not allowed by managed-key policy`
+        };
+    }
+    if (input.policy.models && !input.policy.models.includes(input.model)) {
+        return {
+            ok: false,
+            code: "model_not_allowed",
+            message: "model is not allowed by managed-key policy"
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=managed-key.js.map