/**
 * Error classification for the Claude Agent SDK driver.
 *
 * Wraps the Anthropic API error patterns surfaced through the bundled
 * `claude-cli.js`. The CLI flattens upstream HTTP errors into terse strings
 * like:
 *
 *   `Claude Code returned an error result: Failed to authenticate. API Error:
 *    401 {"type":"error","error":{"type":"authentication_error","message":
 *    "Invalid authentication credentials"}}`
 *
 * Word-for-word that reads as an auth failure, but in practice it also
 * fires when a Claude Max OAuth subscription has exhausted its current
 * quota window — Anthropic returns a non-200 that the CLI relabels as
 * "Failed to authenticate" without preserving the original error type.
 *
 * The classifier here:
 *   1. Parses an embedded JSON body when the upstream included one
 *      (e.g. `{"type":"error","error":{"type":"rate_limit_error",...}}`)
 *      so we believe the structured `error.type` over the surrounding
 *      free-text wrapper.
 *   2. Honours the SDK's `terminal_reason` when it explicitly indicates
 *      a blocking-limit / rapid-refill / model-error condition — those
 *      are authoritative even if the textual error reads as auth.
 *   3. Falls back to keyword heuristics on the message text.
 *   4. For OAuth-style credentials (Claude Code subscriptions), adds a
 *      hint that bounces user attention to quota rather than credentials,
 *      because that's overwhelmingly the cause when a CredentialsFile
 *      provider that worked yesterday now returns "Invalid authentication
 *      credentials" without anyone touching the file.
 */
import type { AgentError } from "./types.js";
/**
 * Error thrown by drivers when the upstream provider rejects the credential
 * with an authentication-shaped failure (HTTP 401 / `authentication_error`
 * structured body). Carries the structured {@link AgentError} produced by
 * {@link classifyClaudeSdkError} so the runner can mediate without
 * re-classifying string text.
 *
 * The runner's 401-mediation handler `instanceof`-discriminates on this
 * subclass so the auth-vs-rate_limit fork stays in one place.
 *
 * Spec: `_devlog/specs/2026-05-07-unified-credential-mediation.md`
 * § "Runner-side handling on 401".
 *
 * @category Errors
 * @since 3.3.0
 */
export declare class AuthError extends Error {
    readonly detail: AgentError;
    constructor(detail: AgentError);
}
/**
 * Error thrown when an auth-shaped failure persists *after* a successful
 * credential self-heal — the refresh worked, yet the immediate retry still
 * returned 401. That combination rules out the credential and points at the
 * account itself: a hidden-tier rate limit, a billing block, or anti-abuse
 * throttling on OAuth tokens used at scale (Anthropic mislabels all three as
 * `authentication_error`). It deliberately does **not** extend {@link AuthError}
 * so the driver's auth self-heal does not fire again on it.
 *
 * @category Errors
 */
export declare class AccountUnavailableError extends Error {
    readonly detail: AgentError;
    constructor(detail: AgentError);
}
/**
 * Re-label an auth-shaped {@link AgentError} as an `account` failure. Called
 * when a 401 recurs after a successful credential refresh: the credential is
 * fine, so the user needs an account-state hint, not "check your API key".
 * Pure function.
 */
export declare function reclassifyAuthAsAccountUnavailable(detail: AgentError): AgentError;
/**
 * Input shape for {@link classifyClaudeSdkError} when decoding an `SDKResultError`.
 *
 * All fields are optional; `classifyClaudeSdkError` also accepts a plain `string`
 * (a thrown exception message) for the common non-SDK code paths.
 *
 * @docLink packages/bridge/api-reference#error-classifier
 */
export interface ClaudeSdkResultErrorInput {
    /** `errors` array from `SDKResultError`. Empty when not provided. */
    errors?: string[];
    /**
     * `terminal_reason` from `SDKResultError`. Authoritative when set to a
     * blocking/rapid-refill value, regardless of message text.
     */
    terminalReason?: string;
    /** `subtype` from `SDKResultError` — `error_max_turns` etc. */
    subtype?: string;
    /**
     * `true` when the configured Anthropic credential is a Claude Code
     * subscription (`CredentialsFile` provider) rather than a raw API key.
     * Changes the hint copy because `Invalid authentication credentials`
     * on an OAuth subscription almost always means quota.
     */
    oauthCredential?: boolean;
}
/**
 * Classify a Claude SDK result-error or thrown error into a structured
 * {@link AgentError}. Pure function — safe to call from any layer.
 *
 * @param input - Either a free-text error message (from a thrown exception)
 *   or a partially-decoded `SDKResultError` shape with `errors[]`,
 *   `terminal_reason`, and `subtype`.
 * @returns A category, retryable flag, and human-readable hint.
 * @docLink packages/bridge/api-reference#error-classifier
 */
export declare function classifyClaudeSdkError(input: string | ClaudeSdkResultErrorInput): AgentError;
/**
 * The shared keyword buckets matched by {@link classifyGenericErrorMessage}.
 * Drivers layer a provider-specific `hint` on top of the returned category.
 */
export type GenericErrorCategory = "auth" | "rate_limit" | "model" | "network";
/**
 * Classify a free-text driver error against the keyword buckets common to the
 * subprocess/SDK drivers (omp, codex). Returns the matched `category` +
 * `retryable` flag, or `null` when no shared bucket matches so the caller can
 * fall through to its own provider-specific buckets (e.g. codex sandbox) and
 * `unknown` default. The driver supplies the user-facing `hint` — only the
 * bucketing logic is shared, not the copy.
 */
export declare function classifyGenericErrorMessage(msg: string): {
    category: GenericErrorCategory;
    retryable: boolean;
} | null;
//# sourceMappingURL=error-classifier.d.ts.map