/**
 * Structured error envelope for cross-pillar primitives.
 *
 * Without this, the primitives throw string errors when the customer
 * backend fails. An agent caller gets the string and has to NLP-parse it
 * to decide whether to retry, back off, or give up. A structured error
 * envelope lets the agent branch on a typed category instead.
 *
 * This module defines:
 *   - `PrimitiveErrorType` — the taxonomy of error categories an agent
 *     can branch on.
 *   - `PrimitiveError` — the envelope shape returned in tool output
 *     when the call fails before useful results.
 *   - `wrapBackendError()` — translates a thrown Error from the
 *     backend layer (GenericPromBackend / Log10xBackend / etc.) into
 *     a typed `PrimitiveError`.
 *
 * Error envelopes are returned in the tool's `data.error` field with
 * `status: "error"` on the top level. The agent reads `error_type` to
 * decide:
 *
 *   - `backend_timeout` / `backend_unavailable` → retryable, back off
 *   - `anchor_not_found` → re-anchor with a different pattern
 *   - `candidate_too_many` → caller-side input error, won't retry-fix
 *   - `schema_invalid` → caller-side input error
 *   - `partial_failure` → some candidates succeeded; check
 *     evaluation_failed[] for details
 *   - `unknown` → log and surface to user; not auto-retryable
 */
export declare const PRIMITIVE_ERROR_TYPES: readonly ["backend_timeout", "backend_unavailable", "anchor_not_found", "candidate_too_many", "schema_invalid", "partial_failure", "input_invalid", "local_processing_failed", "missing_identifier", "no_environment", "missing_destination", "unsupported_destination", "ambiguous_destination", "missing_input", "noop_action", "config_missing", "no_signal", "backend_error", "write_not_allowed", "unknown_arg", "demo_read_only", "unknown"];
export type PrimitiveErrorType = (typeof PRIMITIVE_ERROR_TYPES)[number];
export interface PrimitiveError {
    error_type: PrimitiveErrorType;
    /** Whether the agent should retry the call after `suggested_backoff_ms`. */
    retryable: boolean;
    /** Hint for the agent's backoff. Null when retryable=false. */
    suggested_backoff_ms: number | null;
    /** Plain-English context for the agent OR a human reading the log. */
    hint: string;
}
/**
 * Translate an arbitrary thrown error (string or Error) from the
 * customer-metrics backend layer into a typed `PrimitiveError`.
 *
 * The current `GenericPromBackend.fetchJson` throws strings of the form
 * `"generic_prom HTTP 503: ..."`. We pattern-match on the status code
 * to classify retryability and backoff.
 */
export declare function wrapBackendError(err: unknown): PrimitiveError;