@tanstack/ai/dist/esm/activities/error-payload.d.ts

Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.

/**
 * True when a thrown value is an abort-shaped error (DOM `AbortError`, OpenAI
 * `APIUserAbortError`, OpenRouter `RequestAbortedError`) — i.e. user-initiated
 * cancellation rather than a genuine failure. Matches on the error `name` so
 * callers can discriminate aborts without depending on a signal's state or on
 * provider-specific message strings.
 */
export declare function isAbortShapedError(error: unknown): boolean;
/**
 * The `RUN_ERROR.code` a text adapter sets when the provider says the input
 * does not fit in the model's context window. Shorten the messages, then call
 * the model again. The provider's own text stays in `message`.
 */
export declare const CONTEXT_OVERFLOW_CODE = "context_overflow";
export declare function toRunErrorPayload(error: unknown, fallbackMessage?: string): {
    message: string;
    code: string | undefined;
};
/**
 * Extract the provider's *structured error body* from a thrown value, to attach
 * as the AG-UI `rawEvent` on a RUN_ERROR event. This is the recoverable upstream
 * detail (provider name, the upstream model's error JSON, rate-limit/overload
 * codes, etc.) that `toRunErrorPayload`'s `{ message, code }` deliberately drops.
 *
 * Security boundary: only known provider-response-body fields are forwarded —
 * never the raw SDK exception object, which can carry request metadata such as
 * auth headers. (A request id is not a secret: `toRunErrorDetails` puts it on
 * the event as `requestId`.) The recognized sources, in priority order:
 *
 *  - `error.rawEvent` — a provider body an adapter attached explicitly (e.g. the
 *    OpenRouter mid-stream `chunk.error`).
 *  - `error.error` (object) — the parsed provider response body exposed by SDK
 *    `APIError` instances (OpenAI/Anthropic `{ type, message, code, param }`,
 *    OpenRouter typed errors whose `.error` carries `.metadata`). This is
 *    provider-shaped data, distinct from `.headers` / `.request_id`.
 *  - `error.metadata` — OpenRouter's `provider_name` + raw upstream body, when
 *    surfaced directly on the thrown error.
 *
 * Returns `undefined` when no structured provider body is present, so callers
 * omit the field entirely rather than setting it to `null`:
 *
 *   const rawEvent = toRunErrorRawEvent(error)
 *   yield { type: EventType.RUN_ERROR, ..., ...(rawEvent !== undefined && { rawEvent }) }
 */
export declare function toRunErrorRawEvent(error: unknown): unknown;
/**
 * Read the provider's error type and request id from a thrown value, to put
 * on a `RUN_ERROR` as `errorType` and `requestId`. Only keys that are present
 * are set, so you can spread the result into the event:
 *
 *   yield { type: EventType.RUN_ERROR, ..., ...toRunErrorDetails(error) }
 *
 * - `errorType` is the SDK error's `type` (OpenAI and Anthropic set it from
 *   the body), else the body's `error.type` (an Anthropic stream error event),
 *   else the body's `type`. For example `overloaded_error`.
 * - `requestId` is the SDK error's `requestID` or `request_id`, else the
 *   `request-id` or `x-request-id` response header.
 *
 * Each value must be a string of at most 128 characters.
 */
export declare function toRunErrorDetails(error: unknown): {
    errorType?: string;
    requestId?: string;
};
/**
 * Read how long a provider asks you to wait before a retry, from the response
 * headers that an SDK error carries. It reads `retry-after-ms` first, then
 * `retry-after` in seconds or as an HTTP date. Gives `undefined` when no
 * usable header is present.
 *
 *   const retryAfterMs = toRetryAfterMs(error)
 *   yield { type: EventType.RUN_ERROR, ..., ...(retryAfterMs !== undefined && { retryAfterMs }) }
 */
export declare function toRetryAfterMs(error: unknown): number | undefined;