@aexhq/sdk 0.39.0 → 0.40.1

package/dist/_contracts/error-factory.js

@@ -0,0 +1,142 @@
+/**
+ * The SINGLE wire→exception mapping. `apiErrorFromResponse` reads a non-2xx
+ * body's stable `error` code, attaches it (typed) as `apiCode` plus the
+ * `requestId`, and dispatches to the right {@link AexApiError} subclass. Both
+ * `HttpClient.request` and `HttpClient.download` construct errors ONLY through
+ * here, so the wire→exception mapping lives in one place — no inline
+ * `new AexApiError(...)` with a hardcoded coarse code.
+ */
+import { AexApiError, AexAuthError, AexIdempotencyConflictError, AexNotFoundError, AexRateLimitError } from "./sdk-errors.js";
+import { AEX_API_ERROR_MESSAGES, isAexApiErrorCode } from "./error-codes.js";
+/**
+ * EXHAUSTIVE stable-code → subclass-kind map. There is NO `default`: adding a
+ * code to {@link AEX_API_ERROR_CODES} without a case here fails to compile
+ * (the function would fall through and return `undefined`, which the
+ * `ApiErrorKind` return type forbids). This is the whole-class guard that a new
+ * server code can never silently collapse to the base error.
+ */
+export function apiErrorKindForCode(code) {
+    switch (code) {
+        case "unauthorized":
+        case "forbidden":
+        case "insufficient_scope":
+        case "token_invalid":
+        case "token_revoked":
+        case "token_expired":
+        case "malformed_token":
+            return "auth";
+        case "idempotency_conflict":
+            return "idempotency";
+        case "not_found":
+            return "not_found";
+        case "rate_limited":
+        case "workspace_concurrency_exceeded":
+        case "workspace_submit_rate_exceeded":
+            return "rate_limit";
+        case "session_busy":
+        case "run_not_terminal":
+        case "unknown_workspace":
+        case "workspace_spend_cap_exceeded":
+        case "insufficient_balance":
+        case "upstream_error":
+        case "internal_error":
+            return "generic";
+    }
+}
+function kindForStatus(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 404)
+        return "not_found";
+    if (status === 409)
+        return "idempotency";
+    if (status === 429)
+        return "rate_limit";
+    return "generic";
+}
+export function apiErrorFromResponse(input) {
+    const apiCode = apiCodeFromBody(input.body);
+    const requestId = input.requestId ?? requestIdFromBody(input.body);
+    const message = input.message ?? fallbackMessage(apiCode, input.body);
+    const kind = apiCode !== undefined ? apiErrorKindForCode(apiCode) : kindForStatus(input.status);
+    const init = {
+        status: input.status,
+        message,
+        body: input.body,
+        apiCode,
+        requestId,
+        cause: input.cause
+    };
+    switch (kind) {
+        case "auth":
+            return new AexAuthError({ ...init, requiredScope: requiredScopeFromBody(input.body) });
+        case "idempotency":
+            return new AexIdempotencyConflictError(init);
+        case "not_found":
+            return new AexNotFoundError(init);
+        case "rate_limit":
+            return new AexRateLimitError({ ...init, retryAfterMs: retryAfterMsFromBody(input.body) });
+        case "generic":
+            return new AexApiError(input.status, message, input.body, {
+                apiCode,
+                requestId,
+                ...(input.cause !== undefined ? { cause: input.cause } : {})
+            });
+    }
+}
+function asRecord(body) {
+    return body !== null && typeof body === "object" && !Array.isArray(body)
+        ? body
+        : undefined;
+}
+function apiCodeFromBody(body) {
+    const record = asRecord(body);
+    if (!record)
+        return undefined;
+    if (isAexApiErrorCode(record.error))
+        return record.error;
+    if (isAexApiErrorCode(record.code))
+        return record.code;
+    return undefined;
+}
+function requestIdFromBody(body) {
+    const record = asRecord(body);
+    const value = record?.requestId;
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function requiredScopeFromBody(body) {
+    const record = asRecord(body);
+    if (!record)
+        return undefined;
+    for (const key of ["requiredScope", "required_scope", "scope"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function retryAfterMsFromBody(body) {
+    const record = asRecord(body);
+    if (!record)
+        return undefined;
+    if (typeof record.retryAfterMs === "number" && Number.isFinite(record.retryAfterMs)) {
+        return record.retryAfterMs;
+    }
+    if (typeof record.retryAfter === "number" && Number.isFinite(record.retryAfter)) {
+        return record.retryAfter * 1000;
+    }
+    return undefined;
+}
+function fallbackMessage(apiCode, body) {
+    if (apiCode !== undefined)
+        return AEX_API_ERROR_MESSAGES[apiCode];
+    const record = asRecord(body);
+    const message = record?.message;
+    if (typeof message === "string" && message.length > 0)
+        return message;
+    const error = record?.error;
+    if (typeof error === "string" && error.length > 0)
+        return error;
+    return "aex API request failed";
+}
+//# sourceMappingURL=error-factory.js.map

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

@@ -196,18 +196,25 @@ export declare function isRunError(e: AexEvent): boolean;
 /** A terminal event of either flavour (finished or error). */
 export declare function isRunTerminal(e: AexEvent): boolean;
 /**
- * The CUSTOM `data.name`s the MANAGED runtime emits as a run/turn's terminal.
- * A managed one-shot run PARKS (session_parked.v1 → `aex.session.idle` / `.error`
- * / `.suspended`) rather than writing a `session_finished` → RUN_FINISHED, so
- * these — not just the AG-UI RUN_FINISHED/RUN_ERROR — are what actually ends a
- * managed run's event stream. Kept in sync with the platform journal projection
- * (`journal-project.ts` session_parked.v1 mapping).
+ * The CUSTOM `data.name`s the MANAGED runtime emits as a run/turn's SETTLED
+ * terminal. A managed one-shot run PARKS (`session_parked.v1` → one of these)
+ * rather than writing a `session_finished` → RUN_FINISHED, so these — not just
+ * the AG-UI RUN_FINISHED/RUN_ERROR — are what actually end a managed run's event
+ * stream. Clean-cut (WS1): the bare `aex.session.error` park is retired in favour
+ * of the terminal OUTCOME vocabulary — a failed turn is `failed`, a wall-clock
+ * kill `timed_out`, a cancel `cancelled`, a clean finish `succeeded`; `idle`/
+ * `suspended` remain the resumable parks. Held `awaiting_approval` is NOT here:
+ * it ends the TURN stream (see `isSessionTurnTerminalEvent` in the SDK) but the
+ * RUN is not settled. Kept byte-in-sync with `@aexhq/shared` `AEX_SESSION_PARKED_NAMES`
+ * and the platform journal projection (`journal-project.ts` session_parked.v1).
  */
-export declare const AEX_SESSION_PARKED_NAMES: readonly ["aex.session.idle", "aex.session.error", "aex.session.suspended"];
+export declare const AEX_SESSION_PARKED_NAMES: readonly ["aex.session.idle", "aex.session.suspended", "aex.session.succeeded", "aex.session.failed", "aex.session.timed_out", "aex.session.cancelled"];
 /**
- * True for a managed-runtime session-park terminal (idle/error/suspended). The
- * turn's work is done and the record has reached its terminal status; a stream
- * consumer should stop here exactly as it would on RUN_FINISHED/RUN_ERROR.
+ * True for a managed-runtime session-park terminal (a resumable idle/suspended
+ * park OR a terminal succeeded/failed/timed_out/cancelled outcome). The turn's
+ * work is done and the record has reached its terminal status; a stream consumer
+ * should stop here exactly as it would on RUN_FINISHED/RUN_ERROR. (Held
+ * `awaiting_approval` is deliberately excluded — the run is paused, not settled.)
  */
 export declare function isSessionParked(e: AexEvent): boolean;
 export declare function isTextMessage(e: AexEvent): boolean;
@@ -236,6 +243,22 @@ export declare const AEX_RUN_SETTLED_NAME = "aex.run.settled";
  * the park instead of hanging forever waiting for a barrier that never arrives.
  */
 export declare function isRunSettled(e: AexEvent): boolean;
+/**
+ * The CUSTOM `data.name` of the HITL write-gate park: the run has reached the
+ * `awaiting_approval` state before a gated action and is holding for an
+ * `approve()`/`deny()`. Structural (independent of model prose).
+ */
+export declare const AEX_SESSION_AWAITING_APPROVAL_NAME = "aex.session.awaiting_approval";
+/** The CUSTOM `data.name` carrying a schema-decoded value (`{ value }`). */
+export declare const AEX_RESULT_DECODED_NAME = "aex.result.decoded";
+/** The CUSTOM `data.name` carrying a typed decode refusal (`{ reason, detail? }`). */
+export declare const AEX_RESULT_REFUSED_NAME = "aex.result.refused";
+/** True for the HITL `awaiting_approval` gate event. */
+export declare function isAwaitingApproval(e: AexEvent): boolean;
+/** True for a schema-decoded terminal result event. */
+export declare function isResultDecoded(e: AexEvent): boolean;
+/** True for a typed decode-refusal terminal result event. */
+export declare function isResultRefused(e: AexEvent): boolean;
 export declare function isFromSource(e: AexEvent, source: AexEventSource): boolean;
 /** The channel a record rides, defaulting an absent value to `"event"`. */
 export declare function channelOf(e: AexEvent): AexEventChannel;

package/dist/_contracts/event-envelope.js

@@ -213,18 +213,32 @@ export function isRunTerminal(e) {
     return e.type === "RUN_FINISHED" || e.type === "RUN_ERROR";
 }
 /**
- * The CUSTOM `data.name`s the MANAGED runtime emits as a run/turn's terminal.
- * A managed one-shot run PARKS (session_parked.v1 → `aex.session.idle` / `.error`
- * / `.suspended`) rather than writing a `session_finished` → RUN_FINISHED, so
- * these — not just the AG-UI RUN_FINISHED/RUN_ERROR — are what actually ends a
- * managed run's event stream. Kept in sync with the platform journal projection
- * (`journal-project.ts` session_parked.v1 mapping).
+ * The CUSTOM `data.name`s the MANAGED runtime emits as a run/turn's SETTLED
+ * terminal. A managed one-shot run PARKS (`session_parked.v1` → one of these)
+ * rather than writing a `session_finished` → RUN_FINISHED, so these — not just
+ * the AG-UI RUN_FINISHED/RUN_ERROR — are what actually end a managed run's event
+ * stream. Clean-cut (WS1): the bare `aex.session.error` park is retired in favour
+ * of the terminal OUTCOME vocabulary — a failed turn is `failed`, a wall-clock
+ * kill `timed_out`, a cancel `cancelled`, a clean finish `succeeded`; `idle`/
+ * `suspended` remain the resumable parks. Held `awaiting_approval` is NOT here:
+ * it ends the TURN stream (see `isSessionTurnTerminalEvent` in the SDK) but the
+ * RUN is not settled. Kept byte-in-sync with `@aexhq/shared` `AEX_SESSION_PARKED_NAMES`
+ * and the platform journal projection (`journal-project.ts` session_parked.v1).
  */
-export const AEX_SESSION_PARKED_NAMES = ["aex.session.idle", "aex.session.error", "aex.session.suspended"];
+export const AEX_SESSION_PARKED_NAMES = [
+    "aex.session.idle",
+    "aex.session.suspended",
+    "aex.session.succeeded",
+    "aex.session.failed",
+    "aex.session.timed_out",
+    "aex.session.cancelled"
+];
 /**
- * True for a managed-runtime session-park terminal (idle/error/suspended). The
- * turn's work is done and the record has reached its terminal status; a stream
- * consumer should stop here exactly as it would on RUN_FINISHED/RUN_ERROR.
+ * True for a managed-runtime session-park terminal (a resumable idle/suspended
+ * park OR a terminal succeeded/failed/timed_out/cancelled outcome). The turn's
+ * work is done and the record has reached its terminal status; a stream consumer
+ * should stop here exactly as it would on RUN_FINISHED/RUN_ERROR. (Held
+ * `awaiting_approval` is deliberately excluded — the run is paused, not settled.)
  */
 export function isSessionParked(e) {
     const name = customName(e);
@@ -268,6 +282,28 @@ export const AEX_RUN_SETTLED_NAME = "aex.run.settled";
 export function isRunSettled(e) {
     return customName(e) === AEX_RUN_SETTLED_NAME || isSessionParked(e);
 }
+/**
+ * The CUSTOM `data.name` of the HITL write-gate park: the run has reached the
+ * `awaiting_approval` state before a gated action and is holding for an
+ * `approve()`/`deny()`. Structural (independent of model prose).
+ */
+export const AEX_SESSION_AWAITING_APPROVAL_NAME = "aex.session.awaiting_approval";
+/** The CUSTOM `data.name` carrying a schema-decoded value (`{ value }`). */
+export const AEX_RESULT_DECODED_NAME = "aex.result.decoded";
+/** The CUSTOM `data.name` carrying a typed decode refusal (`{ reason, detail? }`). */
+export const AEX_RESULT_REFUSED_NAME = "aex.result.refused";
+/** True for the HITL `awaiting_approval` gate event. */
+export function isAwaitingApproval(e) {
+    return customName(e) === AEX_SESSION_AWAITING_APPROVAL_NAME;
+}
+/** True for a schema-decoded terminal result event. */
+export function isResultDecoded(e) {
+    return customName(e) === AEX_RESULT_DECODED_NAME;
+}
+/** True for a typed decode-refusal terminal result event. */
+export function isResultRefused(e) {
+    return customName(e) === AEX_RESULT_REFUSED_NAME;
+}
 export function isFromSource(e, source) {
     return e.source === source;
 }

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

@@ -0,0 +1,123 @@
+/**
+ * Event methods over the coordinator {@link AexEvent} the SDK yields.
+ *
+ * The SDK hands users an {@link AexEventView} — the coordinator envelope enriched
+ * with one type-predicate METHOD per standardized event type, so a consumer
+ * branches on the event with `event.isTextMessage()` / `event.isToolCallStart()`
+ * / … instead of a free-function guard or a raw `event.type === "…"` compare.
+ *
+ * `isTextMessage()` / `isToolCallStart()` / `isToolCallResult()` are TS type
+ * predicates: inside the guarded branch `event.data` NARROWS to that event type's
+ * payload fields (e.g. `event.data.text` is `string`), exactly what the former
+ * free `is*` guards gave. Like those guards the narrowing is DISCRIMINANT-only at
+ * runtime (it tests `type`); the narrowed `data` shape is a typing convenience,
+ * not deep runtime validation. Parse/verify the payload fields before trusting
+ * them when the producer is untrusted.
+ *
+ * The view is a thin wrapper: {@link asAexEventView} sets the prototype and
+ * copies the envelope's own fields, so every {@link AexEvent} field (`type`,
+ * `data`, `source`, `sequence`, …) reads exactly as before, the methods live on
+ * the prototype (they never serialize), and an `AexEventView` is still a
+ * structural {@link AexEvent}.
+ */
+import type { AexEvent, AexEventSource } from "./event-envelope.js";
+import type { JsonValue } from "./submission.js";
+/**
+ * A `TEXT_MESSAGE_CONTENT` event with its assistant-text payload narrowed.
+ * `delta` discriminates a per-token STREAMING delta (`delta: true`, emitted on
+ * `outputMode:'stream'`) from the final coalesced block (`delta` absent/false).
+ * Both narrow via `isTextMessage()`.
+ */
+export interface TextMessageEventView extends AexEventView {
+    readonly type: "TEXT_MESSAGE_CONTENT";
+    readonly data: Readonly<Record<string, JsonValue>> & {
+        readonly text: string;
+        readonly messageId?: string;
+        /** `true` on a per-token streaming delta; absent/false on the coalesced block. */
+        readonly delta?: boolean;
+    };
+}
+/** A `TOOL_CALL_START` event with the tool-call id/name/args narrowed. */
+export interface ToolCallStartEventView extends AexEventView {
+    readonly type: "TOOL_CALL_START";
+    readonly data: Readonly<Record<string, JsonValue>> & {
+        readonly id: string;
+        readonly name: string;
+        readonly arguments?: {
+            readonly [key: string]: JsonValue;
+        };
+    };
+    /** The tool-call correlation id (`data.id`), the cross-projection join key. */
+    toolCallId(): string;
+}
+/** A `TOOL_CALL_RESULT` event with the correlating id + result narrowed. */
+export interface ToolCallResultEventView extends AexEventView {
+    readonly type: "TOOL_CALL_RESULT";
+    readonly data: Readonly<Record<string, JsonValue>> & {
+        readonly id: string;
+        readonly content?: JsonValue;
+        readonly isError?: boolean;
+    };
+    /** The tool-call correlation id (`data.id`), the cross-projection join key. */
+    toolCallId(): string;
+}
+/**
+ * A coordinator {@link AexEvent} with the standardized-event-type guards carried
+ * as METHODS (`event.isTextMessage()`, `event.isToolCallStart()`, …). Extends
+ * {@link AexEvent} by declaration merging, so it exposes every envelope field
+ * unchanged. Construct one with {@link asAexEventView}.
+ */
+export declare class AexEventView {
+    /** True for the run-start lifecycle event. */
+    isRunStarted(): boolean;
+    /** True for the terminal success event. */
+    isRunFinished(): boolean;
+    /** True for the terminal error event. */
+    isRunError(): boolean;
+    /** True for a terminal event of either flavour (finished or error). */
+    isRunTerminal(): boolean;
+    /** True for an assistant text event; narrows `data.text` to `string`. */
+    isTextMessage(): this is TextMessageEventView;
+    /** True for a tool-call start event; narrows `data` to `{ id, name }`. */
+    isToolCallStart(): this is ToolCallStartEventView;
+    /** True for a tool-call result event; narrows `data` to `{ id, content }`. */
+    isToolCallResult(): this is ToolCallResultEventView;
+    /**
+     * The tool-call correlation id — `data.id`, the documented, stable join key
+     * that a `TOOL_CALL_START` and its `TOOL_CALL_RESULT` share (and that is
+     * IDENTICAL across the list and stream projections). Returns `undefined` on a
+     * non-tool-call event; on a tool-call view the return narrows to `string`.
+     */
+    toolCallId(): string | undefined;
+    /** True for an aex-native CUSTOM event (an `aex.*` name under `data.name`). */
+    isCustom(): boolean;
+    /** True for the HITL `awaiting_approval` write-gate event. */
+    isAwaitingApproval(): boolean;
+    /** True for a schema-decoded terminal result event (`aex.result.decoded`). */
+    isResultDecoded(): boolean;
+    /** True for a typed decode-refusal terminal result event (`aex.result.refused`). */
+    isResultRefused(): boolean;
+    /** True when the record is a log line (the `log` channel / `LOG` type). */
+    isLog(): boolean;
+    /** True when the record is a typed AG-UI event (the `event` channel). */
+    isEventChannel(): boolean;
+    /**
+     * True for the settle-consistency barrier event AND for a managed-runtime
+     * session-park terminal (idle/error/suspended) — the one check that reliably
+     * means "this stream is done and the record is authoritative".
+     */
+    isRunSettled(): boolean;
+    /** True when the record originates from the given coarse source. */
+    isFromSource(source: AexEventSource): boolean;
+}
+export interface AexEventView extends AexEvent {
+}
+/**
+ * Wrap a coordinator {@link AexEvent} as an {@link AexEventView}: the methods
+ * live on the prototype and the envelope's own fields are copied across, so the
+ * returned value reads identically to the raw envelope and serializes to the
+ * same bytes (prototype methods are not own-enumerable).
+ */
+export declare function asAexEventView(event: AexEvent): AexEventView;
+/** Wrap each event of a list as an {@link AexEventView}. */
+export declare function asAexEventViews(events: readonly AexEvent[]): AexEventView[];

package/dist/_contracts/event-view.js

@@ -0,0 +1,120 @@
+/**
+ * Event methods over the coordinator {@link AexEvent} the SDK yields.
+ *
+ * The SDK hands users an {@link AexEventView} — the coordinator envelope enriched
+ * with one type-predicate METHOD per standardized event type, so a consumer
+ * branches on the event with `event.isTextMessage()` / `event.isToolCallStart()`
+ * / … instead of a free-function guard or a raw `event.type === "…"` compare.
+ *
+ * `isTextMessage()` / `isToolCallStart()` / `isToolCallResult()` are TS type
+ * predicates: inside the guarded branch `event.data` NARROWS to that event type's
+ * payload fields (e.g. `event.data.text` is `string`), exactly what the former
+ * free `is*` guards gave. Like those guards the narrowing is DISCRIMINANT-only at
+ * runtime (it tests `type`); the narrowed `data` shape is a typing convenience,
+ * not deep runtime validation. Parse/verify the payload fields before trusting
+ * them when the producer is untrusted.
+ *
+ * The view is a thin wrapper: {@link asAexEventView} sets the prototype and
+ * copies the envelope's own fields, so every {@link AexEvent} field (`type`,
+ * `data`, `source`, `sequence`, …) reads exactly as before, the methods live on
+ * the prototype (they never serialize), and an `AexEventView` is still a
+ * structural {@link AexEvent}.
+ */
+import { channelOf, isRunSettled, isAwaitingApproval, isResultDecoded, isResultRefused } from "./event-envelope.js";
+/**
+ * A coordinator {@link AexEvent} with the standardized-event-type guards carried
+ * as METHODS (`event.isTextMessage()`, `event.isToolCallStart()`, …). Extends
+ * {@link AexEvent} by declaration merging, so it exposes every envelope field
+ * unchanged. Construct one with {@link asAexEventView}.
+ */
+export class AexEventView {
+    /** True for the run-start lifecycle event. */
+    isRunStarted() {
+        return this.type === "RUN_STARTED";
+    }
+    /** True for the terminal success event. */
+    isRunFinished() {
+        return this.type === "RUN_FINISHED";
+    }
+    /** True for the terminal error event. */
+    isRunError() {
+        return this.type === "RUN_ERROR";
+    }
+    /** True for a terminal event of either flavour (finished or error). */
+    isRunTerminal() {
+        return this.type === "RUN_FINISHED" || this.type === "RUN_ERROR";
+    }
+    /** True for an assistant text event; narrows `data.text` to `string`. */
+    isTextMessage() {
+        return this.type === "TEXT_MESSAGE_CONTENT";
+    }
+    /** True for a tool-call start event; narrows `data` to `{ id, name }`. */
+    isToolCallStart() {
+        return this.type === "TOOL_CALL_START";
+    }
+    /** True for a tool-call result event; narrows `data` to `{ id, content }`. */
+    isToolCallResult() {
+        return this.type === "TOOL_CALL_RESULT";
+    }
+    /**
+     * The tool-call correlation id — `data.id`, the documented, stable join key
+     * that a `TOOL_CALL_START` and its `TOOL_CALL_RESULT` share (and that is
+     * IDENTICAL across the list and stream projections). Returns `undefined` on a
+     * non-tool-call event; on a tool-call view the return narrows to `string`.
+     */
+    toolCallId() {
+        const id = this.data.id;
+        return typeof id === "string" ? id : undefined;
+    }
+    /** True for an aex-native CUSTOM event (an `aex.*` name under `data.name`). */
+    isCustom() {
+        return this.type === "CUSTOM";
+    }
+    /** True for the HITL `awaiting_approval` write-gate event. */
+    isAwaitingApproval() {
+        return isAwaitingApproval(this);
+    }
+    /** True for a schema-decoded terminal result event (`aex.result.decoded`). */
+    isResultDecoded() {
+        return isResultDecoded(this);
+    }
+    /** True for a typed decode-refusal terminal result event (`aex.result.refused`). */
+    isResultRefused() {
+        return isResultRefused(this);
+    }
+    /** True when the record is a log line (the `log` channel / `LOG` type). */
+    isLog() {
+        return channelOf(this) === "log";
+    }
+    /** True when the record is a typed AG-UI event (the `event` channel). */
+    isEventChannel() {
+        return channelOf(this) === "event";
+    }
+    /**
+     * True for the settle-consistency barrier event AND for a managed-runtime
+     * session-park terminal (idle/error/suspended) — the one check that reliably
+     * means "this stream is done and the record is authoritative".
+     */
+    isRunSettled() {
+        return isRunSettled(this);
+    }
+    /** True when the record originates from the given coarse source. */
+    isFromSource(source) {
+        return this.source === source;
+    }
+}
+/**
+ * Wrap a coordinator {@link AexEvent} as an {@link AexEventView}: the methods
+ * live on the prototype and the envelope's own fields are copied across, so the
+ * returned value reads identically to the raw envelope and serializes to the
+ * same bytes (prototype methods are not own-enumerable).
+ */
+export function asAexEventView(event) {
+    const view = Object.create(AexEventView.prototype);
+    return Object.assign(view, event);
+}
+/** Wrap each event of a list as an {@link AexEventView}. */
+export function asAexEventViews(events) {
+    return events.map(asAexEventView);
+}
+//# sourceMappingURL=event-view.js.map

package/dist/_contracts/http.js

@@ -1,4 +1,5 @@
-import { AexApiError, AexError, AexNetworkError, redactUrl } from "./sdk-errors.js";
+import { AexError, AexNetworkError, redactUrl } from "./sdk-errors.js";
+import { apiErrorFromResponse } from "./error-factory.js";
 import { AEX_DEFAULT_BASE_URL } from "./stable.js";
 /**
  * Thin transport used by every BFF-bound operation. The SDK class and
@@ -63,7 +64,11 @@ export class HttpClient {
         const body = await readJson(response);
         if (!response.ok) {
             const errorBody = withResponseRequestId(body, response.headers);
-            throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
+            throw apiErrorFromResponse({
+                status: response.status,
+                body: errorBody,
+                message: extractErrorMessage(errorBody)
+            });
         }
         return body;
     }
@@ -88,7 +93,11 @@ export class HttpClient {
         if (!response.ok) {
             const body = await readJson(response);
             const errorBody = withResponseRequestId(body, response.headers);
-            throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
+            throw apiErrorFromResponse({
+                status: response.status,
+                body: errorBody,
+                message: extractErrorMessage(errorBody)
+            });
         }
         return { response };
     }

package/dist/_contracts/index.d.ts

@@ -1,11 +1,12 @@
 export * from "./provider-support.js";
 export * from "./models.js";
 export * from "./status.js";
-export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
-export type { BuiltinToolName, JsonPrimitive, JsonValue, OutputMode, ParseRunSubmissionOptions, PlatformEnvironment, PlatformEnvironmentInput, PlatformInlineSecrets, PlatformInjectionConfig, PlatformMcpServerSecret, PlatformNetworking, PlatformOutputCaptureConfig, PlatformPackage, PlatformPackageEcosystem, PlatformPackageInput, PlatformRunSubmissionInput, PlatformRunSubmissionRequest, PlatformSecretEnvEntry, PlatformSubmission, RunLimits, RunMachine, RunProvider, RunWebhookSpec } from "./submission.js";
+export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RESPONSE_FORMAT_KINDS, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, STREAMABLE_SHAPES, assertStreamableOutputMode, crossValidateSecretEnvAndValues, isStreamableProvider, packageInstallString, parseApprovalGate, parseInlineSecrets, parseResponseFormat, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
+export type { ApprovalGate, BuiltinToolName, JsonPrimitive, JsonValue, OutputMode, ParseRunSubmissionOptions, PlatformEnvironment, PlatformEnvironmentInput, PlatformInlineSecrets, PlatformInjectionConfig, PlatformMcpServerSecret, PlatformNetworking, PlatformOutputCaptureConfig, PlatformPackage, PlatformPackageEcosystem, PlatformPackageInput, PlatformRunSubmissionInput, PlatformRunSubmissionRequest, PlatformSecretEnvEntry, PlatformSubmission, ResponseFormat, ResponseFormatKind, RunLimits, RunMachine, RunProvider, RunWebhookSpec, StreamableShape } from "./submission.js";
 export * from "./runtime-sizes.js";
 export * from "./runner-event.js";
 export * from "./event-envelope.js";
+export * from "./event-view.js";
 export * from "./connection-ticket.js";
 export * from "./event-stream-client.js";
 export * from "./run-unit.js";
@@ -21,11 +22,14 @@ export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";
 export * from "./run-config.js";
+export * from "./bundle-manifest.js";
 export * from "./runtime-types.js";
 export * from "./webhook-verify.js";
 export * from "./http.js";
 export * from "./run-artifacts.js";
 export * as operations from "./operations.js";
 export * from "./sse.js";
-export { isRunFinished, isTextMessage, isToolCallResult, isToolCallStart } from "./event-guards.js";
-export type { RunFinishedRunEvent, TextMessageRunEvent, ToolCallResultRunEvent, ToolCallStartRunEvent } from "./event-guards.js";
+export * from "./error-codes.js";
+export * from "./error-factory.js";
+export * from "./suggest.js";
+export * from "./api-key.js";

package/dist/_contracts/index.js

@@ -1,10 +1,11 @@
 export * from "./provider-support.js";
 export * from "./models.js";
 export * from "./status.js";
-export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
+export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RESPONSE_FORMAT_KINDS, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, STREAMABLE_SHAPES, assertStreamableOutputMode, crossValidateSecretEnvAndValues, isStreamableProvider, packageInstallString, parseApprovalGate, parseInlineSecrets, parseResponseFormat, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
 export * from "./runtime-sizes.js";
 export * from "./runner-event.js";
 export * from "./event-envelope.js";
+export * from "./event-view.js";
 export * from "./connection-ticket.js";
 export * from "./event-stream-client.js";
 export * from "./run-unit.js";
@@ -19,16 +20,19 @@ export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";
 export * from "./run-config.js";
+export * from "./bundle-manifest.js";
 export * from "./runtime-types.js";
 export * from "./webhook-verify.js";
 export * from "./http.js";
 export * from "./run-artifacts.js";
 export * as operations from "./operations.js";
 export * from "./sse.js";
-// Explicit re-export (shadows the same-named `AexEvent` guards from
-// `event-envelope.js`): the public `is*` guards narrow the loose `RunEvent`
-// snapshot shape `listEvents` returns. An `AexEvent` is assignable to `RunEvent`,
-// so envelope consumers keep working; the envelope-typed guards stay reachable
-// via the direct `event-envelope.js` module.
-export { isRunFinished, isTextMessage, isToolCallResult, isToolCallStart } from "./event-guards.js";
+// The single canonical event surface: the `is*` guards live on `AexEvent`
+// (`event-envelope.js`) and as METHODS on `AexEventView` (`event-view.js`).
+// The loose `RunEvent` type and its free-function guard mirror (`event-guards.js`)
+// are RETIRED — there is exactly one event shape.
+export * from "./error-codes.js";
+export * from "./error-factory.js";
+export * from "./suggest.js";
+export * from "./api-key.js";
 //# sourceMappingURL=index.js.map

package/dist/_contracts/models.d.ts

@@ -147,6 +147,21 @@ export declare function providerForModel(model: string): RunProvider | undefined
  * `"openai/gpt-4o-mini"`). Throws when the provider does not serve the model.
  */
 export declare function resolveProviderModelId(model: string, provider: RunProvider): string;
+/**
+ * The single model→provider resolver shared by the SDK and the CLI, wrapping
+ * {@link providersForModel} with the forward-compat unknown-model allowance:
+ *
+ *   - `provider` given: it is honored. If `model` is a KNOWN id, the provider
+ *     must serve it (else throw). If `model` is UNKNOWN, it is allowed through
+ *     so a slightly-old client can still run a newly-launched model (the server
+ *     arbitrates).
+ *   - `provider` omitted: a known model resolves to its DEFAULT provider (first
+ *     declared). An UNKNOWN model with no provider throws a `did you mean?`
+ *     hint — you must name a provider to run a model this client doesn't know.
+ *
+ * Returns the resolved {@link RunProvider}.
+ */
+export declare function resolveModelProvider(model: string, provider?: RunProvider): RunProvider;
 export declare function isRunModel(input: unknown): input is RunModel;
 export declare function parseRunModel(input: unknown, field?: string): RunModel;
 export declare function assertRunModelMatchesProvider(provider: RunProvider, model: RunModel, field?: string): void;