@pipelex/sdk 0.25.1 → 0.27.0

package/dist/error-models.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Error-report wire models — a failed run's stored report, and the typed members of a
+ * problem document.
+ *
+ * **The runner owns these shapes; this SDK follows them.** A run that fails reports why as
+ * the runner's `ErrorReport` (`pipelex.base_exceptions`), which the hosted platform stores
+ * whole on the run row as `error` and serves as it was stored: on the status read
+ * (`RunRead.error`), on the run records (`PipelineRun.error`), and inside the problem
+ * document of the results read's `409`, where the client lifts it onto the failed arm of
+ * `RunResultState` and onto `RunFailedError.error`. The same classification fields
+ * (`error_domain`, `user_action`, …) ride a runner-rendered problem document as extension
+ * members, which is why `ApiResponseError` types its members with the models declared here.
+ *
+ * Every field is optional and every interface keeps an index signature, for the reason
+ * `TokensUsageRecord` gives: the runner adds fields without asking this SDK, and a field this
+ * version does not name still reaches the caller. The enum-ish fields (`error_domain`,
+ * `error_category`, `user_action.kind`) are open sets on the wire and stay `string`, never
+ * frozen unions, so a value the runner adds is not an SDK break; their known values are listed
+ * where they are declared.
+ *
+ * **Nothing is stripped.** The platform serves the runner's VERBOSE report, so `message` and
+ * `provider_metadata` can hold a provider's raw text. Deciding what of it a person should see
+ * is each consumer's presentation, not this SDK's; the report arrives here whole.
+ */
+import type { ValidationErrorItem } from "./models.js";
+/**
+ * The next step an error advises — the runner's `UserAction`, carried as `user_action` on a
+ * stored report and on a runner's problem document. `kind` names the category of advice, so a
+ * consumer can render consistent guidance; `detail` is the advice itself, in words (a billing
+ * URL, a retry hint, the model to change).
+ *
+ * Known `kind` values: `wait_and_retry`, `check_billing`, `check_credentials`, `change_input`,
+ * `change_model`, `contact_support`, `unknown`. The set is the runner's, so it is typed open.
+ * The shape is the one `mthds`'s `UserAction` declares, so a value moves between the two
+ * clients' errors unchanged.
+ */
+export interface UserAction {
+    kind: string;
+    detail: string;
+}
+/**
+ * What the inference provider's SDK said about a failed call — the runner's
+ * `ProviderErrorMetadata`. Present on a report whose failure came back from a model provider.
+ * `message` is the provider SDK's own text, relayed raw; the provider's response body never
+ * crosses the wire, because the runner excludes it from every serialization.
+ *
+ * **The hosted store turns its numbers into strings.** A report read back from the platform's
+ * run store carries `status_code` and `retry_after_seconds` as JSON strings (`"404"`,
+ * `"1.5"`), because the store hands its numbers back as decimals that the platform serializes
+ * as strings. A problem document rendered by a runner carries them as numbers. Both are typed,
+ * so read them with `Number(...)` when you need the value.
+ */
+export interface ProviderErrorMetadata {
+    provider?: string | null;
+    sdk_exception_type?: string | null;
+    message?: string | null;
+    /** The provider's HTTP status, when it answered one. */
+    status_code?: number | string | null;
+    /** The provider's own request id — what its support desk asks for. */
+    request_id?: string | null;
+    retry_after_seconds?: number | string | null;
+    provider_error_code?: string | null;
+    [extension: string]: unknown;
+}
+/**
+ * A pending configuration migration that explains the failure — the runner's
+ * `MigrationErrorBlock`. Present only on a configuration failure whose raiser scanned the
+ * host's configuration directories; a consumer branches on its presence. `plans` is carried
+ * opaquely: it is the shape `pipelex-agent migrate --dry-run --format json` emits, which no
+ * published package declares.
+ */
+export interface MigrationErrorBlock {
+    /** The command that applies whatever can be applied without a decision. */
+    remedy?: string | null;
+    /** Whether running `remedy` would rewrite any file. */
+    would_write?: boolean | null;
+    /** Whether something here is a person's to resolve rather than the tool's. */
+    needs_attention?: boolean | null;
+    plans?: Record<string, unknown>[] | null;
+    [extension: string]: unknown;
+}
+/**
+ * Why a run failed — the runner's `ErrorReport`, typed with every field it carries.
+ *
+ * The one type for a failed run's report wherever the SDK hands it back: `RunPublic.error`
+ * (and so `RunRead.error` on the status read), `PipelineRun.error` on the run records, `error`
+ * on the failed arm of `RunResultState` (the results read's `409`), and `RunFailedError.error`
+ * when `waitForResult`, `startAndWaitForResult` or an artifact download throws for a run that
+ * ended without a result.
+ *
+ * **Branch on `error_domain`, `type_uri` and `retryable`**, never on the wording of `message`.
+ * `error_type` is the runner's open-ended exception class name: finer than `error_domain`,
+ * useful in a support line, but not a closed set to match against. Which fault's identity a run
+ * failure's report carries, and how its `message` names the failing pipe, is the runner's to
+ * decide; read them as given.
+ *
+ * A report is `null` where the run has none — a cancelled, terminated or timed-out run, or one
+ * the platform finalized itself — so the absence of a report says nothing about why.
+ */
+export interface RunErrorReport {
+    /**
+     * The runner's exception class name (`LLMCompletionError`, `PipeRunError`, …) — an open
+     * set, for display and support, not for branching.
+     */
+    error_type?: string | null;
+    /**
+     * What went wrong, as the runner wrote it. On the VERBOSE report the platform serves, it can
+     * carry a provider's raw text.
+     */
+    message?: string | null;
+    /** A stable human label for the error class (`LLM completion`). */
+    title?: string | null;
+    /** The stable URI naming the error class — a branch field, and where its documentation lives. */
+    type_uri?: string | null;
+    /**
+     * Who can fix it, the coarse branch field. Known values: `input` (the caller — a malformed
+     * bundle, a bad input), `config` (a configuration change — a model not served, a missing
+     * secret), `runtime` (nobody beforehand — a provider outage during execution).
+     */
+    error_domain?: string | null;
+    /**
+     * A finer classification of an inference failure, when the runner has one. Known values:
+     * `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
+     */
+    error_category?: string | null;
+    /** Whether retrying the same run can succeed. Absent or `null` means unknown, never "no". */
+    retryable?: boolean | null;
+    /** The next step the runner advises. */
+    user_action?: UserAction | null;
+    /** The model the failing call used, when the failure is an inference failure. */
+    model?: string | null;
+    /** The provider the failing call reached, when the failure is an inference failure. */
+    provider?: string | null;
+    /** What the provider's SDK said, when the failure came back from a provider. */
+    provider_metadata?: ProviderErrorMetadata | null;
+    /** True when `message` was written as caller-facing copy. The runner emits it only when true. */
+    caller_facing_message?: boolean | null;
+    /**
+     * The structured diagnostics of a bundle that failed validation — the same items the
+     * validate report and a `422`'s `ApiResponseError.validationErrors` carry.
+     */
+    validation_errors?: ValidationErrorItem[] | null;
+    /** A pending configuration migration that explains the failure. */
+    migration?: MigrationErrorBlock | null;
+    /** Fields a newer runner adds, reachable before this SDK names them. */
+    [extension: string]: unknown;
+}
+/**
+ * One field-level failure of a request — an item of the platform problem document's
+ * `errors[]`. `field` is the dotted path to the offending attribute, `code` a stable sub-code
+ * (`invalid_format`, `out_of_range`, …), `detail` optional human text.
+ */
+export interface FieldError {
+    field?: string | null;
+    code?: string | null;
+    detail?: string | null;
+    [extension: string]: unknown;
+}
+/**
+ * The members of an RFC 9457 problem document that `ApiResponseError` exposes beyond its
+ * message, as the client parsed them: the standard's own `type`, `title` and `instance`, the
+ * request id, and the extension members the runner and the platform add to classify the
+ * failure. Every member is optional — a server sends what it knows, and a body that is not a
+ * problem document carries none of them.
+ *
+ * It is a superset of `mthds`'s `ProblemDetails`, member for member under the same names, so a
+ * consumer reads one vocabulary whichever client raised the error; the members past that set
+ * (`errorCategory`, `model`, `provider`, `providerMetadata`, `migration`, `errors`) are the ones
+ * the standard's client leaves to this SDK.
+ */
+export interface ProblemDetails {
+    /** RFC 9457 `type` — the stable URI of the error class. */
+    type?: string;
+    /** RFC 9457 `title` — the short human label of the error class. */
+    title?: string;
+    /** RFC 9457 `instance` — the occurrence (a request path or a request URN). */
+    instance?: string;
+    /** The request's correlation id: the body's `request_id`, else the `X-Request-ID` response header. */
+    requestId?: string;
+    /** The body's `error_domain` — `input`, `config` or `runtime`. */
+    errorDomain?: string;
+    /** The body's `error_category` — the finer classification of an inference failure. */
+    errorCategory?: string;
+    /** The body's `retryable` — whether retrying the same request can plausibly succeed. */
+    retryable?: boolean;
+    /** The body's `user_action` — what the caller should do next. */
+    userAction?: UserAction;
+    /** The body's `model` — the model an inference failure used. */
+    model?: string;
+    /** The body's `provider` — the provider an inference failure reached. */
+    provider?: string;
+    /** The body's `provider_metadata` — what the provider's SDK said. */
+    providerMetadata?: ProviderErrorMetadata;
+    /** The body's `migration` — a pending configuration migration that explains the failure. */
+    migration?: MigrationErrorBlock;
+    /** The platform's field-level `errors[]`. */
+    errors?: FieldError[];
+}

package/dist/error-models.js

@@ -0,0 +1,26 @@
+/**
+ * Error-report wire models — a failed run's stored report, and the typed members of a
+ * problem document.
+ *
+ * **The runner owns these shapes; this SDK follows them.** A run that fails reports why as
+ * the runner's `ErrorReport` (`pipelex.base_exceptions`), which the hosted platform stores
+ * whole on the run row as `error` and serves as it was stored: on the status read
+ * (`RunRead.error`), on the run records (`PipelineRun.error`), and inside the problem
+ * document of the results read's `409`, where the client lifts it onto the failed arm of
+ * `RunResultState` and onto `RunFailedError.error`. The same classification fields
+ * (`error_domain`, `user_action`, …) ride a runner-rendered problem document as extension
+ * members, which is why `ApiResponseError` types its members with the models declared here.
+ *
+ * Every field is optional and every interface keeps an index signature, for the reason
+ * `TokensUsageRecord` gives: the runner adds fields without asking this SDK, and a field this
+ * version does not name still reaches the caller. The enum-ish fields (`error_domain`,
+ * `error_category`, `user_action.kind`) are open sets on the wire and stay `string`, never
+ * frozen unions, so a value the runner adds is not an SDK break; their known values are listed
+ * where they are declared.
+ *
+ * **Nothing is stripped.** The platform serves the runner's VERBOSE report, so `message` and
+ * `provider_metadata` can hold a provider's raw text. Deciding what of it a person should see
+ * is each consumer's presentation, not this SDK's; the report arrives here whole.
+ */
+export {};
+//# sourceMappingURL=error-models.js.map

package/dist/error-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-models.js","sourceRoot":"","sources":["../src/error-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/errors.d.ts

@@ -6,6 +6,8 @@
 import { PipelineRequestError } from "mthds/protocol";
 import type { ValidationErrorItem } from "./models.js";
 import type { ArtifactScope, DownloadArtifactsResult } from "./artifacts.js";
+import type { FieldError, MigrationErrorBlock, ProblemDetails, ProviderErrorMetadata, RunErrorReport, UserAction } from "./error-models.js";
+import type { RunStatus } from "./runs.js";
 export { PipelineRequestError };
 export declare class ClientAuthenticationError extends Error {
     constructor(message: string);
@@ -225,16 +227,34 @@ export declare class PipelineExecuteTimeoutError extends PipelineRequestError {
     });
 }
 /**
- * Thrown when a run reaches a terminal state that is not `COMPLETED`
- * (`FAILED`, `CANCELLED`, `TERMINATED`, `TIMED_OUT`) — surfaced from
- * `waitForResult`/`getRunResult` when the server answers a result lookup with
- * HTTP 409. `runId` and `status` let callers report the outcome precisely.
+ * Thrown when a run reaches a terminal state that is not `COMPLETED` (`FAILED`, `CANCELLED`,
+ * `TERMINATED`, `TIMED_OUT`) — by `waitForResult`, `startAndWaitForResult` and the artifact
+ * download when the platform answers the results read with HTTP 409. (`getRunResult` returns
+ * the same facts as its `failed` arm instead of throwing.)
+ *
+ * - `status` is the run's terminal status, read from the problem's `run_status` member, or from
+ *   its `detail` sentence on a platform that predates the member.
+ * - `error` is the run's stored error report, typed whole as `RunErrorReport`: the runner's
+ *   `error_type`, `message`, `title`, `type_uri`, `error_domain`, `error_category`,
+ *   `retryable`, `user_action`, `model`, `provider`, `provider_metadata`, `validation_errors`
+ *   and anything newer through its index signature. Branch on `error.error_domain`,
+ *   `error.type_uri` and `error.retryable`; show `error.user_action` as the next step. It is
+ *   the runner's VERBOSE report, so `message` and `provider_metadata` can hold a provider's raw
+ *   text — deciding what a person sees is the consumer's. `null` when the run ended with no
+ *   stored report (a cancelled, terminated or timed-out run, or one the platform finalized
+ *   itself).
+ * - The error's own `message` is the problem's `detail`, which names the status and then the
+ *   report's message (`Run finished with status FAILED: <message>`), so printing the error
+ *   already tells the reason.
+ * - `runId` locates the run, for a status read or a support request.
  */
 export declare class RunFailedError extends PipelineRequestError {
     readonly runId: string;
-    readonly status: string;
-    constructor(message: string, runId: string, status: string, options?: {
+    readonly status: RunStatus;
+    readonly error: RunErrorReport | null;
+    constructor(message: string, runId: string, status: RunStatus, options?: {
         cause?: unknown;
+        error?: RunErrorReport | null;
     });
 }
 /**
@@ -295,15 +315,46 @@ export declare class RunLifecycleUnavailableError extends PipelineRequestError {
     });
 }
 /**
- * A non-2xx response that DID come back from the API. Carries the parsed
- * RFC 7807 problem-details (`errorType`, `serverMessage`) and, for the build
- * routes' 422s, the structured `validation_errors[]` list.
+ * The last constructor argument of `ApiResponseError`: the error's `cause`, the problem
+ * document's typed members, and the decoded document whole. The same shape as `mthds`'s
+ * `ApiResponseErrorOptions`, plus `problemDocument`.
+ */
+export interface ApiResponseErrorOptions {
+    cause?: unknown;
+    problem?: ProblemDetails;
+    problemDocument?: Record<string, unknown>;
+}
+/**
+ * A non-2xx response that DID come back from the API, with its problem document parsed.
+ *
+ * Every error the hosted API answers is an RFC 9457 `application/problem+json` document, and
+ * this error carries its members as typed fields, each `undefined` when the document did not
+ * carry it (a member of the wrong type reads as absent rather than as a wrong value):
+ *
+ * - **The branch fields.** `errorDomain` says who can fix the failure — `input` (the caller),
+ *   `config` (a configuration change), `runtime` (nobody beforehand) — and `type` is the stable
+ *   URI naming the error class. `retryable` says whether a retry can succeed, `undefined`
+ *   meaning unknown. Branch on these, never on the HTTP status or on the wording of a message.
+ * - **The native codes.** `code` is the platform's own closed code (`conflict`, `not_found`,
+ *   `pipelex_api_key_limit_reached`, …) and `errorType` the runner's open exception class
+ *   name. Each is finer than `errorDomain` and specific to the surface that emits it; the
+ *   platform's `type` is one-to-one with its `code` (`https://pipelex.com/errors/<code>`).
+ * - **For a person.** `title` is the stable label of the error class, `serverMessage` the
+ *   per-occurrence `detail`, `userAction` the advised next step, and `errorCategory`, `model`,
+ *   `provider` and `providerMetadata` describe an inference failure.
+ * - **For support.** `requestId` correlates the response with the server's logs; it is read
+ *   from the body, or from the `X-Request-ID` response header when the body has none.
+ *   `instance` is the occurrence's URN or request path.
+ * - **Per-item failures.** `errors` is the platform's field-level list (`field`, `code`,
+ *   `detail`), and `validationErrors` the structured diagnostics of a bundle that failed
+ *   validation.
  *
- * `code` is the product routes' stable RFC 9457 `problem+json` discriminant
- * (`conflict`, `not_found`, `pipelex_api_key_limit_reached`,
- * `promo_code_invalid`, …) — the field a consumer branches on, decoupled from
- * the HTTP status. `undefined` for any error body that carries no `code`
- * (the protocol/build routes' `detail`-shaped problems, auth, transport).
+ * `problemDocument` is the decoded document whole, so a member this SDK does not name stays
+ * reachable without re-parsing `responseBody`, which is the raw text; it is `undefined` when
+ * the body was not a JSON object. The members `mthds`'s own `ApiResponseError` carries have the
+ * same names and types here, and the rest (`code`, `errorCategory`, `model`, `provider`,
+ * `providerMetadata`, `migration`, `errors`) are the Pipelex members the standard's client
+ * leaves to this SDK.
  */
 export declare class ApiResponseError extends PipelineRequestError {
     readonly apiUrl: string;
@@ -312,22 +363,77 @@ export declare class ApiResponseError extends PipelineRequestError {
     readonly responseBody: string;
     readonly errorType: string | undefined;
     readonly serverMessage: string | undefined;
+    /**
+     * The platform's native code — a closed set (`conflict`, `not_found`, `run_not_found`,
+     * `pipelex_api_key_limit_reached`, …), one-to-one with `type`. Finer than `errorDomain` and
+     * specific to the platform: a runner's problem carries `errorType` instead. `undefined` for a
+     * body that carries no `code`.
+     */
     readonly code: string | undefined;
+    /**
+     * RFC 9457 `type`: the stable URI naming the error class. With `errorDomain`, the field a
+     * machine consumer branches on — the same class carries the same URI on every occurrence.
+     */
+    readonly type: string | undefined;
+    /** RFC 9457 `title`: the short human label of the error class. */
+    readonly title: string | undefined;
+    /** RFC 9457 `instance`: the occurrence — the request path, or a request URN. */
+    readonly instance: string | undefined;
+    /**
+     * The request's correlation id — the body's `request_id`, or the `X-Request-ID` response
+     * header when the body carries none. The id to hand to support: it finds the server's log
+     * lines for this request.
+     */
+    readonly requestId: string | undefined;
+    /**
+     * The body's `error_domain`: who can fix the failure. `input` — the caller (a malformed
+     * bundle, a bad argument, a missing input); `config` — a configuration change (a missing
+     * secret, a model the backend does not serve); `runtime` — nobody beforehand (a provider
+     * outage during execution). Typed open, as the server owns the vocabulary; `undefined` when
+     * the server did not classify it.
+     */
+    readonly errorDomain: string | undefined;
+    /**
+     * The body's `error_category`: the finer classification of an inference failure — known
+     * values `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
+     */
+    readonly errorCategory: string | undefined;
+    /**
+     * The body's `retryable`: whether retrying the same request can plausibly succeed.
+     * `undefined` means unknown, which is not the same as `false`.
+     */
+    readonly retryable: boolean | undefined;
+    /** The body's `user_action`: what the caller should do next, when the server can say. */
+    readonly userAction: UserAction | undefined;
+    /** The body's `model`: the model an inference failure used. */
+    readonly model: string | undefined;
+    /** The body's `provider`: the provider an inference failure reached. */
+    readonly provider: string | undefined;
+    /** The body's `provider_metadata`: what the provider's SDK said, raw text included. */
+    readonly providerMetadata: ProviderErrorMetadata | undefined;
+    /** The body's `migration`: a pending configuration migration that explains the failure. */
+    readonly migration: MigrationErrorBlock | undefined;
+    /** The platform's field-level `errors[]` — one item per offending request field. */
+    readonly errors: FieldError[] | undefined;
+    /**
+     * The decoded problem document whole — every member, named or not, such as a failed run's
+     * `run_status` and `error` or a member a newer server adds. `undefined` when the body was not
+     * a JSON object.
+     */
+    readonly problemDocument: Record<string, unknown> | undefined;
     /**
      * Structured per-error diagnostics on a problem body that carries a top-level
-     * `validation_errors[]` — the **build routes** (`POST /v1/build/*`), which still
-     * reject an invalid bundle with a 422.
+     * `validation_errors[]` — the 422 a **run route** (`execute`, `start`) answers when the
+     * runner refuses the method for its validation errors.
      *
-     * `POST /v1/validate` no longer routes content errors here: an invalid bundle is
-     * a produced verdict (a **200** `PipelexInvalidReport` whose `validation_errors[]`
-     * the caller reads off the returned value), not an `ApiResponseError`. This field
-     * stays for the build-route 422s and is `undefined` for any error that carries no
-     * per-error list (auth, transport, a request-shape 422). A consumer must NOT
-     * assume a given `error_type` implies a populated list — fall back to
-     * `serverMessage` when this is empty.
+     * Everywhere else an invalid bundle is a produced verdict, not an `ApiResponseError`:
+     * `POST /v1/validate` answers it with a **200** `PipelexInvalidReport`, and the build
+     * and crate routes with a **200** `CrateInvalidReport`, whose `validation_errors[]` the
+     * caller reads off the returned value. This field is `undefined` for any error that
+     * carries no per-error list (auth, transport, a request-shape 422, a build route's 422
+     * for a pipe it cannot build). A consumer must NOT assume a given `error_type` implies a
+     * populated list — fall back to `serverMessage` when this is empty.
      */
     readonly validationErrors: ValidationErrorItem[] | undefined;
-    constructor(message: string, apiUrl: string, status: number, statusText: string, responseBody: string, errorType: string | undefined, serverMessage: string | undefined, validationErrors: ValidationErrorItem[] | undefined, code: string | undefined, options?: {
-        cause?: unknown;
-    });
+    constructor(message: string, apiUrl: string, status: number, statusText: string, responseBody: string, errorType: string | undefined, serverMessage: string | undefined, validationErrors: ValidationErrorItem[] | undefined, code: string | undefined, options?: ApiResponseErrorOptions);
 }

package/dist/errors.js

@@ -227,19 +227,37 @@ export class PipelineExecuteTimeoutError extends PipelineRequestError {
     }
 }
 /**
- * Thrown when a run reaches a terminal state that is not `COMPLETED`
- * (`FAILED`, `CANCELLED`, `TERMINATED`, `TIMED_OUT`) — surfaced from
- * `waitForResult`/`getRunResult` when the server answers a result lookup with
- * HTTP 409. `runId` and `status` let callers report the outcome precisely.
+ * Thrown when a run reaches a terminal state that is not `COMPLETED` (`FAILED`, `CANCELLED`,
+ * `TERMINATED`, `TIMED_OUT`) — by `waitForResult`, `startAndWaitForResult` and the artifact
+ * download when the platform answers the results read with HTTP 409. (`getRunResult` returns
+ * the same facts as its `failed` arm instead of throwing.)
+ *
+ * - `status` is the run's terminal status, read from the problem's `run_status` member, or from
+ *   its `detail` sentence on a platform that predates the member.
+ * - `error` is the run's stored error report, typed whole as `RunErrorReport`: the runner's
+ *   `error_type`, `message`, `title`, `type_uri`, `error_domain`, `error_category`,
+ *   `retryable`, `user_action`, `model`, `provider`, `provider_metadata`, `validation_errors`
+ *   and anything newer through its index signature. Branch on `error.error_domain`,
+ *   `error.type_uri` and `error.retryable`; show `error.user_action` as the next step. It is
+ *   the runner's VERBOSE report, so `message` and `provider_metadata` can hold a provider's raw
+ *   text — deciding what a person sees is the consumer's. `null` when the run ended with no
+ *   stored report (a cancelled, terminated or timed-out run, or one the platform finalized
+ *   itself).
+ * - The error's own `message` is the problem's `detail`, which names the status and then the
+ *   report's message (`Run finished with status FAILED: <message>`), so printing the error
+ *   already tells the reason.
+ * - `runId` locates the run, for a status read or a support request.
  */
 export class RunFailedError extends PipelineRequestError {
     runId;
     status;
+    error;
     constructor(message, runId, status, options) {
-        super(message, options);
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
         this.name = "RunFailedError";
         this.runId = runId;
         this.status = status;
+        this.error = options?.error ?? null;
     }
 }
 /**
@@ -315,15 +333,36 @@ export class RunLifecycleUnavailableError extends PipelineRequestError {
     }
 }
 /**
- * A non-2xx response that DID come back from the API. Carries the parsed
- * RFC 7807 problem-details (`errorType`, `serverMessage`) and, for the build
- * routes' 422s, the structured `validation_errors[]` list.
+ * A non-2xx response that DID come back from the API, with its problem document parsed.
+ *
+ * Every error the hosted API answers is an RFC 9457 `application/problem+json` document, and
+ * this error carries its members as typed fields, each `undefined` when the document did not
+ * carry it (a member of the wrong type reads as absent rather than as a wrong value):
  *
- * `code` is the product routes' stable RFC 9457 `problem+json` discriminant
- * (`conflict`, `not_found`, `pipelex_api_key_limit_reached`,
- * `promo_code_invalid`, …) — the field a consumer branches on, decoupled from
- * the HTTP status. `undefined` for any error body that carries no `code`
- * (the protocol/build routes' `detail`-shaped problems, auth, transport).
+ * - **The branch fields.** `errorDomain` says who can fix the failure — `input` (the caller),
+ *   `config` (a configuration change), `runtime` (nobody beforehand) — and `type` is the stable
+ *   URI naming the error class. `retryable` says whether a retry can succeed, `undefined`
+ *   meaning unknown. Branch on these, never on the HTTP status or on the wording of a message.
+ * - **The native codes.** `code` is the platform's own closed code (`conflict`, `not_found`,
+ *   `pipelex_api_key_limit_reached`, …) and `errorType` the runner's open exception class
+ *   name. Each is finer than `errorDomain` and specific to the surface that emits it; the
+ *   platform's `type` is one-to-one with its `code` (`https://pipelex.com/errors/<code>`).
+ * - **For a person.** `title` is the stable label of the error class, `serverMessage` the
+ *   per-occurrence `detail`, `userAction` the advised next step, and `errorCategory`, `model`,
+ *   `provider` and `providerMetadata` describe an inference failure.
+ * - **For support.** `requestId` correlates the response with the server's logs; it is read
+ *   from the body, or from the `X-Request-ID` response header when the body has none.
+ *   `instance` is the occurrence's URN or request path.
+ * - **Per-item failures.** `errors` is the platform's field-level list (`field`, `code`,
+ *   `detail`), and `validationErrors` the structured diagnostics of a bundle that failed
+ *   validation.
+ *
+ * `problemDocument` is the decoded document whole, so a member this SDK does not name stays
+ * reachable without re-parsing `responseBody`, which is the raw text; it is `undefined` when
+ * the body was not a JSON object. The members `mthds`'s own `ApiResponseError` carries have the
+ * same names and types here, and the rest (`code`, `errorCategory`, `model`, `provider`,
+ * `providerMetadata`, `migration`, `errors`) are the Pipelex members the standard's client
+ * leaves to this SDK.
  */
 export class ApiResponseError extends PipelineRequestError {
     apiUrl;
@@ -332,23 +371,80 @@ export class ApiResponseError extends PipelineRequestError {
     responseBody;
     errorType;
     serverMessage;
+    /**
+     * The platform's native code — a closed set (`conflict`, `not_found`, `run_not_found`,
+     * `pipelex_api_key_limit_reached`, …), one-to-one with `type`. Finer than `errorDomain` and
+     * specific to the platform: a runner's problem carries `errorType` instead. `undefined` for a
+     * body that carries no `code`.
+     */
     code;
+    /**
+     * RFC 9457 `type`: the stable URI naming the error class. With `errorDomain`, the field a
+     * machine consumer branches on — the same class carries the same URI on every occurrence.
+     */
+    type;
+    /** RFC 9457 `title`: the short human label of the error class. */
+    title;
+    /** RFC 9457 `instance`: the occurrence — the request path, or a request URN. */
+    instance;
+    /**
+     * The request's correlation id — the body's `request_id`, or the `X-Request-ID` response
+     * header when the body carries none. The id to hand to support: it finds the server's log
+     * lines for this request.
+     */
+    requestId;
+    /**
+     * The body's `error_domain`: who can fix the failure. `input` — the caller (a malformed
+     * bundle, a bad argument, a missing input); `config` — a configuration change (a missing
+     * secret, a model the backend does not serve); `runtime` — nobody beforehand (a provider
+     * outage during execution). Typed open, as the server owns the vocabulary; `undefined` when
+     * the server did not classify it.
+     */
+    errorDomain;
+    /**
+     * The body's `error_category`: the finer classification of an inference failure — known
+     * values `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
+     */
+    errorCategory;
+    /**
+     * The body's `retryable`: whether retrying the same request can plausibly succeed.
+     * `undefined` means unknown, which is not the same as `false`.
+     */
+    retryable;
+    /** The body's `user_action`: what the caller should do next, when the server can say. */
+    userAction;
+    /** The body's `model`: the model an inference failure used. */
+    model;
+    /** The body's `provider`: the provider an inference failure reached. */
+    provider;
+    /** The body's `provider_metadata`: what the provider's SDK said, raw text included. */
+    providerMetadata;
+    /** The body's `migration`: a pending configuration migration that explains the failure. */
+    migration;
+    /** The platform's field-level `errors[]` — one item per offending request field. */
+    errors;
+    /**
+     * The decoded problem document whole — every member, named or not, such as a failed run's
+     * `run_status` and `error` or a member a newer server adds. `undefined` when the body was not
+     * a JSON object.
+     */
+    problemDocument;
     /**
      * Structured per-error diagnostics on a problem body that carries a top-level
-     * `validation_errors[]` — the **build routes** (`POST /v1/build/*`), which still
-     * reject an invalid bundle with a 422.
+     * `validation_errors[]` — the 422 a **run route** (`execute`, `start`) answers when the
+     * runner refuses the method for its validation errors.
      *
-     * `POST /v1/validate` no longer routes content errors here: an invalid bundle is
-     * a produced verdict (a **200** `PipelexInvalidReport` whose `validation_errors[]`
-     * the caller reads off the returned value), not an `ApiResponseError`. This field
-     * stays for the build-route 422s and is `undefined` for any error that carries no
-     * per-error list (auth, transport, a request-shape 422). A consumer must NOT
-     * assume a given `error_type` implies a populated list — fall back to
-     * `serverMessage` when this is empty.
+     * Everywhere else an invalid bundle is a produced verdict, not an `ApiResponseError`:
+     * `POST /v1/validate` answers it with a **200** `PipelexInvalidReport`, and the build
+     * and crate routes with a **200** `CrateInvalidReport`, whose `validation_errors[]` the
+     * caller reads off the returned value. This field is `undefined` for any error that
+     * carries no per-error list (auth, transport, a request-shape 422, a build route's 422
+     * for a pipe it cannot build). A consumer must NOT assume a given `error_type` implies a
+     * populated list — fall back to `serverMessage` when this is empty.
      */
     validationErrors;
     constructor(message, apiUrl, status, statusText, responseBody, errorType, serverMessage, validationErrors, code, options) {
-        super(message, options);
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
         this.name = "ApiResponseError";
         this.apiUrl = apiUrl;
         this.status = status;
@@ -358,6 +454,21 @@ export class ApiResponseError extends PipelineRequestError {
         this.serverMessage = serverMessage;
         this.validationErrors = validationErrors;
         this.code = code;
+        const problem = options?.problem;
+        this.type = problem?.type;
+        this.title = problem?.title;
+        this.instance = problem?.instance;
+        this.requestId = problem?.requestId;
+        this.errorDomain = problem?.errorDomain;
+        this.errorCategory = problem?.errorCategory;
+        this.retryable = problem?.retryable;
+        this.userAction = problem?.userAction;
+        this.model = problem?.model;
+        this.provider = problem?.provider;
+        this.providerMetadata = problem?.providerMetadata;
+        this.migration = problem?.migration;
+        this.errors = problem?.errors;
+        this.problemDocument = options?.problemDocument;
     }
 }
 //# sourceMappingURL=errors.js.map