@aexhq/sdk 0.46.4-canary → 0.50.0

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

@@ -1,445 +0,0 @@
-/**
- * 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 AexStreamEvent}s as they arrive.
- * On a transport drop it reconnects with backoff and resumes from the last
- * durable sequence it saw — `from = lastSeq + 1`. Provisional
- * {@link AexLiveEvent}s are deduplicated by stable `id` but never advance that
- * replay cursor. It stops on a durable terminal event, on abort,
- * or when the caller breaks the iterator.
- *
- * A silently half-open socket (no close/error, no frames) is the dangerous
- * case: the read loop would block forever and MISS a terminal that was already
- * persisted server-side. So the client sends a post-open replay trigger plus a
- * tiny keep-alive ping the coordinator answers with a matching pong, and uses an idle
- * watchdog: if no frame arrives within {@link CoordinatorStreamOptions.idleTimeoutMs},
- * the socket is treated as dead and reconnected — resume-from-cursor then
- * replays the terminal.
- *
- * Filtering and projection are the client's concern (the wire carries the
- * whole session): 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 global `WebSocket`
- * (Bun and Node 22+ ship it; no dependency) and tests drive a fake. The timers
- * are injectable the same way ({@link TimerPort}) so the watchdog/backoff
- * clocks are deterministic under test.
- */
-import { isReplayableEvent } from "./event-envelope.js";
-/**
- * True for either run-terminal discriminant, including a malformed payload.
- *
- * Streaming uses this weaker boundary so a malformed terminal still ends the
- * read loop and reaches the canonical payload validation/error path. Consumers
- * that need validated terminal data must use `isRunTerminal` instead.
- * Internal-only: intentionally omitted from the public contracts barrel.
- */
-export function hasRunTerminalType(event) {
-    return event.type === "RUN_FINISHED" || event.type === "RUN_ERROR";
-}
-/**
- * Keep-alive ping the client sends; the coordinator answers it with the matching
- * pong in its WebSocket message handler. Must stay byte-identical to
- * the coordinator's pair (platform `packages/shared/src/event-stream-client.ts`).
- */
-const COORDINATOR_PING = "aex:ping";
-/**
- * Pull request for everything from `nextSequence` onward.
- *
- * Sent on open ($connect cannot safely PostToConnection before the handshake
- * completes) and again whenever a frame declares a predecessor this client has
- * not reached. Catch-up is PULL-based because the connection row holds only the
- * server's BELIEF about what reached the socket: a frame that was posted but
- * never arrived leaves the client behind that belief with no way for the server
- * to notice. Naming the cursor makes the client authoritative about what it
- * actually holds. An older coordinator ignores the extra field and falls back to
- * its own high-water, so sending it is safe against any deployed server.
- */
-const replayFrom = (nextSequence) => JSON.stringify({ action: "replay", from: nextSequence });
-/** Default half-open watchdog window — 3× the ping cadence, so 2 pongs can be lost. */
-const DEFAULT_IDLE_TIMEOUT_MS = 45_000;
-/** Default client keep-alive ping cadence. */
-const DEFAULT_PING_INTERVAL_MS = 15_000;
-/** Default event-quiet recheck window (a silent reconnect, so the cost of a false positive is small). */
-const DEFAULT_EVENT_QUIET_RECHECK_MS = 90_000;
-/** Recent best-effort frames retained across reconnects for duplicate suppression. */
-const MAX_SEEN_LIVE_IDS = 4096;
-/** Host timers, resolved at call time so environment-level fakes still apply. */
-const HOST_TIMERS = {
-    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
-    clearTimeout: (handle) => clearTimeout(handle),
-    setInterval: (callback, delayMs) => setInterval(callback, delayMs),
-    clearInterval: (handle) => clearInterval(handle)
-};
-export async function* streamCoordinatorEvents(opts) {
-    const makeWs = opts.webSocketFactory ?? ((url) => new WebSocket(url));
-    const isTerminal = opts.isTerminal ?? hasRunTerminalType;
-    const reconnectDelayMs = opts.reconnectDelayMs ?? 500;
-    const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
-    const idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    const pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
-    const eventQuietRecheckMs = opts.eventQuietRecheckMs ?? DEFAULT_EVENT_QUIET_RECHECK_MS;
-    const timerPort = opts.timers ?? HOST_TIMERS;
-    let cursor = (opts.from ?? 0) - 1;
-    let attempts = 0;
-    let done = false;
-    // Live frames have no replay cursor. Retain a bounded reconnect window of
-    // stable ids; durable frames remain exactly deduplicated by their cursor.
-    const seenLiveIds = new Map();
-    const rememberLiveId = (id) => {
-        if (seenLiveIds.delete(id)) {
-            seenLiveIds.set(id, true);
-            return false;
-        }
-        seenLiveIds.set(id, true);
-        if (seenLiveIds.size > MAX_SEEN_LIVE_IDS) {
-            const oldest = seenLiveIds.keys().next().value;
-            if (oldest !== undefined)
-                seenLiveIds.delete(oldest);
-        }
-        return true;
-    };
-    while (!done && !opts.signal?.aborted) {
-        const ticket = await opts.fetchTicket();
-        const url = new URL(opts.wsUrl);
-        url.searchParams.set("ticket", ticket);
-        url.searchParams.set("from", String(cursor + 1));
-        const ws = makeWs(url.toString());
-        const pending = [];
-        const seenSequences = new Set();
-        const catchUp = createCatchUp(ws, cursor);
-        let closed = false;
-        let disconnectReason = "";
-        let resolveNext = null;
-        const wake = () => {
-            if (resolveNext) {
-                const r = resolveNext;
-                resolveNext = null;
-                r();
-            }
-        };
-        const waitForWake = (timeoutMs) => new Promise((resolve) => {
-            let timer = null;
-            const finish = () => {
-                if (timer !== null) {
-                    timerPort.clearTimeout(timer);
-                    timer = null;
-                }
-                if (resolveNext === finish)
-                    resolveNext = null;
-                resolve();
-            };
-            resolveNext = finish;
-            if (typeof timeoutMs === "number")
-                timer = timerPort.setTimeout(finish, timeoutMs);
-        });
-        const takeNextPending = () => {
-            const first = pending[0];
-            if (!isReplayableEvent(first))
-                return pending.shift();
-            // A live frame does not participate in the durable cursor. Select the
-            // lowest durable sequence for this durable slot without moving live
-            // frames, so a higher sequence cannot advance the cursor past a pending
-            // lower sequence merely because a live frame separated their arrival.
-            let lowestIndex = 0;
-            let lowestSequence = first.sequence;
-            for (let index = 1; index < pending.length; index += 1) {
-                const candidate = pending[index];
-                if (isReplayableEvent(candidate) && candidate.sequence < lowestSequence) {
-                    lowestIndex = index;
-                    lowestSequence = candidate.sequence;
-                }
-            }
-            if (lowestIndex > 0) {
-                pending[0] = pending[lowestIndex];
-                pending[lowestIndex] = first;
-            }
-            return pending.shift();
-        };
-        let idleTimer = null;
-        let pingTimer = null;
-        let quietTimer = null;
-        const stopTimers = () => {
-            if (idleTimer !== null) {
-                timerPort.clearTimeout(idleTimer);
-                idleTimer = null;
-            }
-            if (pingTimer !== null) {
-                timerPort.clearInterval(pingTimer);
-                pingTimer = null;
-            }
-            if (quietTimer !== null) {
-                timerPort.clearTimeout(quietTimer);
-                quietTimer = null;
-            }
-        };
-        // Re-arm on every inbound frame. On expiry the socket is presumed half-open
-        // → close it and let the loop fall through to reconnect (resume from cursor).
-        const armIdle = () => {
-            if (idleTimeoutMs <= 0)
-                return;
-            if (idleTimer !== null)
-                timerPort.clearTimeout(idleTimer);
-            idleTimer = timerPort.setTimeout(() => {
-                idleTimer = null;
-                if (closed)
-                    return;
-                closed = true;
-                disconnectReason = "idle";
-                closeQuietly(ws);
-                wake();
-            }, idleTimeoutMs);
-        };
-        // Re-arm only on REAL event frames. On expiry: silent reconnect (resume from
-        // cursor) — self-heals a dead server-side subscription a pong can't expose.
-        const armQuiet = () => {
-            if (eventQuietRecheckMs <= 0)
-                return;
-            if (quietTimer !== null)
-                timerPort.clearTimeout(quietTimer);
-            quietTimer = timerPort.setTimeout(() => {
-                quietTimer = null;
-                if (closed)
-                    return;
-                closed = true;
-                disconnectReason = "quiet_recheck";
-                closeQuietly(ws);
-                wake();
-            }, eventQuietRecheckMs);
-        };
-        ws.addEventListener("open", () => {
-            armIdle();
-            catchUp.request();
-            if (pingIntervalMs > 0 && typeof ws.send === "function") {
-                pingTimer = timerPort.setInterval(() => {
-                    try {
-                        ws.send(COORDINATOR_PING);
-                    }
-                    catch {
-                        // socket not open / send unsupported — the idle watchdog still covers it
-                    }
-                }, pingIntervalMs);
-            }
-        });
-        ws.addEventListener("message", (ev) => {
-            armIdle();
-            const data = typeof ev.data === "string" ? ev.data : "";
-            if (!data)
-                return;
-            try {
-                const evt = JSON.parse(data);
-                if (!isCoordinatorStreamEvent(evt))
-                    return;
-                armQuiet(); // a real event frame proves the delivery pipeline, not just the socket
-                if (isReplayableEvent(evt)) {
-                    if (evt.sequence <= cursor || seenSequences.has(evt.sequence))
-                        return;
-                    // A frame the client cannot chain is refused, leaving both the cursor
-                    // and `seenSequences` untouched so the pull's copy of it is not later
-                    // suppressed as a duplicate.
-                    if (!catchUp.chains(evt))
-                        return;
-                    seenSequences.add(evt.sequence);
-                }
-                else if (!rememberLiveId(evt.id)) {
-                    return;
-                }
-                pending.push(evt);
-                wake();
-            }
-            catch {
-                // ignore a non-JSON frame
-            }
-        });
-        ws.addEventListener("close", (ev) => {
-            stopTimers();
-            // Don't clobber a reason already decided (idle/abort closes the socket too).
-            if (!closed) {
-                closed = true;
-                const code = ev?.code;
-                disconnectReason = `close${typeof code === "number" ? ` code=${code}` : ""}`;
-            }
-            wake();
-        });
-        ws.addEventListener("error", () => {
-            stopTimers();
-            if (!closed) {
-                closed = true;
-                disconnectReason = "error";
-            }
-            wake();
-        });
-        const onAbort = () => {
-            closeQuietly(ws);
-            closed = true;
-            stopTimers();
-            wake();
-        };
-        opts.signal?.addEventListener("abort", onAbort, { once: true });
-        // Arm immediately: a connect that never reaches "open" (and fakes that
-        // never emit it) must still time out rather than hang forever. The quiet
-        // recheck arms here too so a socket fed only by pongs still recycles.
-        armIdle();
-        armQuiet();
-        try {
-            while (true) {
-                while (pending.length > 0) {
-                    const evt = takeNextPending();
-                    if (isReplayableEvent(evt)) {
-                        seenSequences.delete(evt.sequence);
-                        if (evt.sequence <= cursor)
-                            continue;
-                        cursor = evt.sequence;
-                    }
-                    yield evt;
-                    if (isReplayableEvent(evt) && isTerminal(evt))
-                        done = true;
-                }
-                if (done || opts.signal?.aborted) {
-                    closeQuietly(ws);
-                    break;
-                }
-                if (closed)
-                    break; // transport ended → fall through to reconnect
-                await waitForWake();
-            }
-        }
-        finally {
-            stopTimers();
-            opts.signal?.removeEventListener("abort", onAbort);
-            // A caller that `break`s the iterator triggers the generator's `return()`,
-            // which lands here with the socket still OPEN (the yield was suspended, no
-            // terminal/abort/transport-close ran). Close it so an early break never
-            // leaks a live WebSocket. Idempotent: the terminal/abort/reconnect paths
-            // have already closed it, and closeQuietly swallows a double close.
-            closeQuietly(ws);
-        }
-        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;
-        }
-        // The quiet recheck is a routine self-heal on a legitimately quiet stream —
-        // reconnecting silently keeps a long tool call from spamming the console.
-        if (disconnectReason !== "quiet_recheck") {
-            console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
-        }
-        await sleep(reconnectDelayMs, timerPort, opts.signal);
-    }
-}
-/**
- * The exclusive lower bound the coordinator declared for a durable frame: the
- * sequence of the public event immediately preceding it in journal projection
- * order (`-1` when the frame opens the session).
- *
- * Transport-only — it describes this frame's position in the stream, not the
- * event, so it is never part of the durable {@link AexEvent} the archive returns.
- * Absent means the producer made no claim (an older coordinator, or a path that
- * cannot prove what came before it), and an unproven link is not a gap: the
- * frame is accepted exactly as it was before this check existed.
- */
-function declaredPredecessor(frame) {
-    const value = frame.prevSequence;
-    return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
-}
-/**
- * Per-connection catch-up bookkeeping.
- *
- * The high-water is RECEIPT-side — the highest durable sequence admitted on this
- * connection, including frames still queued for the consumer. The gap check has
- * to run against that and not against the yield-side cursor, which lags while
- * the consumer drains: a contiguous burst landing in one turn would otherwise
- * report every frame after the first as a hole.
- *
- * One pull is outstanding per high-water position, so a run of unchainable
- * frames costs one request rather than one per frame; it re-arms by
- * construction, since the next gap at a moved position names a different one.
- */
-function createCatchUp(ws, cursor) {
-    let accepted = cursor;
-    let pulledFrom = null;
-    const request = () => {
-        const from = accepted + 1;
-        if (pulledFrom === from || typeof ws.send !== "function")
-            return;
-        pulledFrom = from;
-        try {
-            ws.send(replayFrom(from));
-        }
-        catch {
-            // socket not open / send unsupported — the idle + quiet watchdogs still
-            // reconnect, and a reconnect resumes from the cursor anyway.
-        }
-    };
-    return {
-        request,
-        chains: (frame) => {
-            const predecessor = declaredPredecessor(frame);
-            if (predecessor !== undefined && predecessor > accepted) {
-                request();
-                return false;
-            }
-            if (frame.sequence > accepted)
-                accepted = frame.sequence;
-            return true;
-        }
-    };
-}
-function isCoordinatorStreamEvent(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const event = value;
-    if (typeof event.id !== "string" ||
-        typeof event.type !== "string" ||
-        typeof event.runId !== "string" ||
-        !event.data ||
-        typeof event.data !== "object" ||
-        Array.isArray(event.data)) {
-        return false;
-    }
-    if (event.replayable === false) {
-        return event.sequence === undefined && Number.isSafeInteger(event.liveSequence) && event.liveSequence >= 0;
-    }
-    return Number.isSafeInteger(event.sequence) && event.sequence >= 0;
-}
-/** 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, timerPort, signal) {
-    return new Promise((resolve) => {
-        const onAbort = () => {
-            timerPort.clearTimeout(timer);
-            resolve();
-        };
-        const timer = timerPort.setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}

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

@@ -1,44 +0,0 @@
-/** Guard-bearing views over durable and provisional coordinator events. */
-import type { AexCustomEvent, AexEvent, AexEventBase, AexEventSource, AexLiveEvent, AexLogEvent, AexRunErrorEvent, AexRunFinishedEvent, AexRunStartedEvent, AexStreamEvent, AexTextMessageEvent, AexToolCallResultEvent, AexToolCallStartEvent } from "./event-envelope.js";
-import { AEX_RESULT_DECODED_NAME, AEX_RESULT_REFUSED_NAME, AEX_SESSION_AWAITING_APPROVAL_NAME } from "./event-envelope.js";
-type ToolCallIdMethod = {
-    toolCallId(): string;
-};
-/** Shared methods mixed into both durable and live-only event views. */
-declare class EventViewPrototype {
-    isRunStarted(): this is EventViewPrototype & AexRunStartedEvent;
-    isRunFinished(): this is EventViewPrototype & AexRunFinishedEvent;
-    isRunError(): this is EventViewPrototype & AexRunErrorEvent;
-    isRunTerminal(): this is EventViewPrototype & (AexRunFinishedEvent | AexRunErrorEvent);
-    isTextMessage(): this is EventViewPrototype & AexTextMessageEvent;
-    isToolCallStart(): this is EventViewPrototype & AexToolCallStartEvent & ToolCallIdMethod;
-    isToolCallResult(): this is EventViewPrototype & AexToolCallResultEvent & ToolCallIdMethod;
-    toolCallId(): string | undefined;
-    isCustom(): this is EventViewPrototype & AexCustomEvent;
-    isAwaitingApproval(): this is EventViewPrototype & AexCustomEvent<typeof AEX_SESSION_AWAITING_APPROVAL_NAME>;
-    isResultDecoded(): this is EventViewPrototype & AexCustomEvent<typeof AEX_RESULT_DECODED_NAME>;
-    isResultRefused(): this is EventViewPrototype & AexCustomEvent<typeof AEX_RESULT_REFUSED_NAME>;
-    isLog(): this is EventViewPrototype & AexLogEvent;
-    isEventChannel(): boolean;
-    isFromSource(source: AexEventSource): boolean;
-}
-interface EventViewPrototype extends AexEventBase {
-}
-/** A durable event view. List, archive, and finished-result APIs return this. */
-export type AexEventView = EventViewPrototype & AexEvent;
-/** A provisional live-only event view with no durable `sequence`. */
-export type AexLiveEventView = EventViewPrototype & AexLiveEvent;
-/** A view yielded by live coordinator streams. */
-export type AexStreamEventView = AexEventView | AexLiveEventView;
-export type TextMessageEventView = AexStreamEventView & AexTextMessageEvent;
-export type ToolCallStartEventView = AexStreamEventView & AexToolCallStartEvent & ToolCallIdMethod;
-export type ToolCallResultEventView = AexStreamEventView & AexToolCallResultEvent & ToolCallIdMethod;
-/** Constructor value for `instanceof`; event fields are mixed in. */
-export declare const AexEventView: typeof EventViewPrototype;
-/** Wrap a durable coordinator event while preserving its precise replayable type. */
-export declare function asAexEventView(event: AexEvent): AexEventView;
-/** Wrap a live stream event while preserving durable-vs-live discrimination. */
-export declare function asAexStreamEventView(event: AexStreamEvent): AexStreamEventView;
-/** Wrap each durable event in a list. */
-export declare function asAexEventViews(events: readonly AexEvent[]): AexEventView[];
-export {};

package/dist/_contracts/event-view.js

@@ -1,69 +0,0 @@
-/** Guard-bearing views over durable and provisional coordinator events. */
-import { isAwaitingApproval as canonicalIsAwaitingApproval, isCustom as canonicalIsCustom, isEventChannel as canonicalIsEventChannel, isFromSource as canonicalIsFromSource, isLog as canonicalIsLog, isResultDecoded as canonicalIsResultDecoded, isResultRefused as canonicalIsResultRefused, isRunError as canonicalIsRunError, isRunFinished as canonicalIsRunFinished, isRunStarted as canonicalIsRunStarted, isRunTerminal as canonicalIsRunTerminal, isTextMessage as canonicalIsTextMessage, isToolCallResult as canonicalIsToolCallResult, isToolCallStart as canonicalIsToolCallStart } from "./event-envelope.js";
-/** Shared methods mixed into both durable and live-only event views. */
-class EventViewPrototype {
-    isRunStarted() {
-        return canonicalIsRunStarted(this);
-    }
-    isRunFinished() {
-        return canonicalIsRunFinished(this);
-    }
-    isRunError() {
-        return canonicalIsRunError(this);
-    }
-    isRunTerminal() {
-        return canonicalIsRunTerminal(this);
-    }
-    isTextMessage() {
-        return canonicalIsTextMessage(this);
-    }
-    isToolCallStart() {
-        return canonicalIsToolCallStart(this);
-    }
-    isToolCallResult() {
-        return canonicalIsToolCallResult(this);
-    }
-    toolCallId() {
-        const id = this.data.id;
-        return typeof id === "string" ? id : undefined;
-    }
-    isCustom() {
-        return canonicalIsCustom(this);
-    }
-    isAwaitingApproval() {
-        return canonicalIsAwaitingApproval(this);
-    }
-    isResultDecoded() {
-        return canonicalIsResultDecoded(this);
-    }
-    isResultRefused() {
-        return canonicalIsResultRefused(this);
-    }
-    isLog() {
-        return canonicalIsLog(this);
-    }
-    isEventChannel() {
-        return canonicalIsEventChannel(this);
-    }
-    isFromSource(source) {
-        return canonicalIsFromSource(this, source);
-    }
-}
-/** Constructor value for `instanceof`; event fields are mixed in. */
-export const AexEventView = EventViewPrototype;
-/** Wrap a durable coordinator event while preserving its precise replayable type. */
-export function asAexEventView(event) {
-    return wrap(event);
-}
-/** Wrap a live stream event while preserving durable-vs-live discrimination. */
-export function asAexStreamEventView(event) {
-    return wrap(event);
-}
-/** Wrap each durable event in a list. */
-export function asAexEventViews(events) {
-    return events.map(asAexEventView);
-}
-function wrap(event) {
-    const view = Object.create(EventViewPrototype.prototype);
-    return Object.assign(view, event);
-}

package/dist/_contracts/failure-class.d.ts

@@ -1,29 +0,0 @@
-/**
- * SSoT for the CUSTOMER-FACING failure taxonomy carried by `RUN_ERROR`.
- *
- * `AexRunErrorData.failureClass` used to be an open `string`, so a customer
- * could not branch on WHY a session ended — every exhaustion looked like an
- * opaque `failed`. This tuple closes it. The hosted platform keeps a larger
- * PRIVATE taxonomy (orchestration detail) and projects it onto exactly this
- * union before the value reaches a customer; the platform's
- * `PUBLIC_FAILURE_CLASSES` is this array, imported, never a hand-copied mirror.
- *
- * Resource exhaustion is a first-class customer-facing outcome here:
- * `out_of_memory`, `disk_full`, and `quota_exhausted` say what ran out. There is
- * deliberately NO `resource_exhausted` — a code that teaches the customer
- * nothing is worse than the `failed` it replaces.
- */
-export declare const AEX_FAILURE_CLASSES: readonly ["wall_clock_exceeded", "max_turns", "budget_exhausted", "step_budget_exceeded", "step_failed", "loop_detected", "invalid_submission", "invalid_model", "workspace_restore_incomplete", "llm_response_stream_failed", "capacity_exhausted", "out_of_memory", "disk_full", "quota_exhausted", "transient-provider", "provider-permanent", "cancelled", "internal_error"];
-/** The closed customer-facing failure taxonomy carried by `RUN_ERROR`. */
-export type AexFailureClass = (typeof AEX_FAILURE_CLASSES)[number];
-/** Narrow an arbitrary value to a known {@link AexFailureClass}. */
-export declare function isAexFailureClass(value: unknown): value is AexFailureClass;
-/**
- * The subset that means "a resource ran out". Customers branch on this to
- * decide between retrying smaller, upgrading, and paging a human — the whole
- * reason the three codes exist as distinct values rather than one vague one.
- */
-export declare const AEX_RESOURCE_EXHAUSTION_FAILURE_CLASSES: readonly ["out_of_memory", "disk_full", "quota_exhausted"];
-export type AexResourceExhaustionFailureClass = (typeof AEX_RESOURCE_EXHAUSTION_FAILURE_CLASSES)[number];
-/** True when the failure was a resource running out rather than a logic fault. */
-export declare function isResourceExhaustionFailureClass(value: unknown): value is AexResourceExhaustionFailureClass;

package/dist/_contracts/failure-class.js

@@ -1,73 +0,0 @@
-/**
- * SSoT for the CUSTOMER-FACING failure taxonomy carried by `RUN_ERROR`.
- *
- * `AexRunErrorData.failureClass` used to be an open `string`, so a customer
- * could not branch on WHY a session ended — every exhaustion looked like an
- * opaque `failed`. This tuple closes it. The hosted platform keeps a larger
- * PRIVATE taxonomy (orchestration detail) and projects it onto exactly this
- * union before the value reaches a customer; the platform's
- * `PUBLIC_FAILURE_CLASSES` is this array, imported, never a hand-copied mirror.
- *
- * Resource exhaustion is a first-class customer-facing outcome here:
- * `out_of_memory`, `disk_full`, and `quota_exhausted` say what ran out. There is
- * deliberately NO `resource_exhausted` — a code that teaches the customer
- * nothing is worse than the `failed` it replaces.
- */
-export const AEX_FAILURE_CLASSES = [
-    /** The session exceeded its wall-clock deadline. */
-    "wall_clock_exceeded",
-    /** The session exhausted its agent-turn budget. */
-    "max_turns",
-    /** The session exhausted its spend budget. */
-    "budget_exhausted",
-    /** A single turn exhausted its per-turn step budget. */
-    "step_budget_exceeded",
-    /** An agent step failed and could not be recovered. */
-    "step_failed",
-    /** Legacy public projection for already-persisted sessions; new runs never produce it. */
-    "loop_detected",
-    /** The submission was rejected as invalid before any work started. */
-    "invalid_submission",
-    /** The requested model is not servable. */
-    "invalid_model",
-    /** The workspace could not be restored to the state the session required. */
-    "workspace_restore_incomplete",
-    /** The provider's response stream broke mid-completion. */
-    "llm_response_stream_failed",
-    /** The platform had no capacity to place this session. */
-    "capacity_exhausted",
-    /** The runtime was killed for exceeding its memory allocation. */
-    "out_of_memory",
-    /** A write failed because the runtime's filesystem was full. */
-    "disk_full",
-    /** A metered usage grant was exhausted and there was no billable path. */
-    "quota_exhausted",
-    /** A transient provider fault; the same request may succeed on retry. */
-    "transient-provider",
-    /** A permanent provider fault; retrying the same request will not help. */
-    "provider-permanent",
-    /** The session was cancelled. */
-    "cancelled",
-    /** An unclassified platform fault. */
-    "internal_error"
-];
-const FAILURE_CLASS_SET = new Set(AEX_FAILURE_CLASSES);
-/** Narrow an arbitrary value to a known {@link AexFailureClass}. */
-export function isAexFailureClass(value) {
-    return typeof value === "string" && FAILURE_CLASS_SET.has(value);
-}
-/**
- * The subset that means "a resource ran out". Customers branch on this to
- * decide between retrying smaller, upgrading, and paging a human — the whole
- * reason the three codes exist as distinct values rather than one vague one.
- */
-export const AEX_RESOURCE_EXHAUSTION_FAILURE_CLASSES = [
-    "out_of_memory",
-    "disk_full",
-    "quota_exhausted"
-];
-const RESOURCE_EXHAUSTION_SET = new Set(AEX_RESOURCE_EXHAUSTION_FAILURE_CLASSES);
-/** True when the failure was a resource running out rather than a logic fault. */
-export function isResourceExhaustionFailureClass(value) {
-    return typeof value === "string" && RESOURCE_EXHAUSTION_SET.has(value);
-}