/**
 * Unified error types for opencli.
 *
 * All errors thrown by the framework should extend CliError so that
 * the top-level handler in commanderAdapter.ts can render consistent,
 * helpful output with emoji-coded severity and actionable hints.
 *
 * ## Exit codes
 *
 * opencli follows Unix conventions (sysexits.h) for process exit codes:
 *
 *   0   Success
 *   1   Generic / unexpected error
 *   2   Argument / usage error          (ArgumentError)
 *  66   No input / empty result         (EmptyResultError)
 *  69   Service unavailable             (BrowserConnectError, adapter load failures)
 *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
 *  77   Permission denied / auth needed (AuthRequiredError)
 *  78   Configuration error             (ConfigError)
 * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
 */
import type { ObservationTraceReceipt } from './observation/events.js';
export declare const EXIT_CODES: {
    readonly SUCCESS: 0;
    readonly GENERIC_ERROR: 1;
    readonly USAGE_ERROR: 2;
    readonly EMPTY_RESULT: 66;
    readonly SERVICE_UNAVAIL: 69;
    readonly TEMPFAIL: 75;
    readonly NOPERM: 77;
    readonly CONFIG_ERROR: 78;
    readonly INTERRUPTED: 130;
};
export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
export declare class CliError extends Error {
    /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
    readonly code: string;
    /** Human-readable hint on how to fix the problem */
    readonly hint?: string;
    /** Unix process exit code — defaults to 1 (generic error) */
    readonly exitCode: ExitCode;
    constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
}
export declare function attachTraceReceipt(err: unknown, receipt: ObservationTraceReceipt): void;
export declare function getTraceReceipt(err: unknown): ObservationTraceReceipt | undefined;
export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'profile-required' | 'profile-disconnected' | 'command-failed' | 'unknown';
export declare class BrowserConnectError extends CliError {
    readonly kind: BrowserConnectKind;
    constructor(message: string, hint?: string, kind?: BrowserConnectKind);
}
export declare class CommandExecutionError extends CliError {
    constructor(message: string, hint?: string);
}
export declare class ConfigError extends CliError {
    constructor(message: string, hint?: string);
}
export declare class AuthRequiredError extends CliError {
    readonly domain: string;
    constructor(domain: string, message?: string);
}
export declare class TimeoutError extends CliError {
    constructor(label: string, seconds: number, hint?: string);
}
export declare class ArgumentError extends CliError {
    constructor(message: string, hint?: string);
}
export declare class EmptyResultError extends CliError {
    constructor(command: string, hint?: string);
}
export declare function adapterLoadError(message: string, hint?: string): CliError;
export declare function selectorError(selector: string, hint?: string): CliError;
export declare class PluginError extends CliError {
    constructor(message: string, hint?: string);
}
/**
 * Thrown when a JSON endpoint returns HTML instead of JSON — typically a login
 * wall, rate-limit page, or WAF challenge. Surfaced as a structured error so
 * callers can show "re-login or wait out the rate limit" guidance instead of
 * the cryptic `SyntaxError: Unexpected token '<', "<!DOCTYPE "...` that a naive
 * JSON.parse on an HTML body produces.
 *
 * `bodyPreview` is the first 100 chars of the response body (after trimming
 * leading whitespace) — useful for logs / debugging without dumping the full
 * page.
 */
export declare class LoginWallError extends CliError {
    readonly status: number;
    readonly url: string;
    readonly bodyPreview: string;
    constructor(message: string, status: number, url: string, bodyPreview: string, hint?: string);
}
/** Structured error output — unified contract for all consumers (AI agents, scripts, humans). */
export interface ErrorEnvelope {
    ok: false;
    error: {
        code: string;
        message: string;
        help?: string;
        exitCode: number;
        stack?: string;
        cause?: string;
    };
    trace?: {
        traceId: string;
        dir: string;
        summaryPath: string;
        receiptPath: string;
        status: ObservationTraceReceipt['status'];
    };
}
/** Extract a human-readable message from an unknown caught value. */
export declare function getErrorMessage(error: unknown): string;
/** Build an ErrorEnvelope from any caught value. */
export declare function toEnvelope(err: unknown): ErrorEnvelope;