import type { JsonObject } from "#shared/json.js";
import type { SemanticErrorSummary } from "#harness/semantic-errors/rule.js";
import { type UpstreamRejectionSummary } from "#harness/model-call/errors.js";
import type { Step } from "#harness/step/context.js";
import type { StepResult } from "#harness/types.js";
/**
 * Projects a model-call failure into the `step.failed` / `turn.failed`
 * `details` payload. Three mutually exclusive branches:
 *
 * 1. Catalog match → the rule's curated `name`/`message`/`hint` plus its
 *    registered `semanticErrorId`, no SDK inspector dump.
 * 2. Upstream rejection → raw error `message` with the extracted upstream
 *    identity, no inspector dump. No `semanticErrorId`: the message is
 *    arbitrary provider prose, not a registered failure shape.
 * 3. Fallback → full {@link formatError} projection (cause chain via
 *    `util.inspect`) so unrecognized failures still carry the upstream
 *    stack to log aggregators.
 *
 * All branches merge {@link extractModelCallErrorDetails} on top so the
 * compact gateway diagnostics (`statusCode`, `upstreamMessage`,
 * `responseBodySnippet`, ...) always show up next to the message.
 */
export declare function buildModelCallFailureDetails(input: {
    readonly catalogSummary: SemanticErrorSummary | null;
    readonly error: unknown;
    readonly errorId: string;
    readonly modelCallDetails: JsonObject;
    readonly upstreamRejection: UpstreamRejectionSummary | null;
}): JsonObject;
/**
 * Builds the structured log fields for a model-call failure. When the
 * failure was recognized (catalog match or extracted upstream rejection),
 * attach the compact `details` payload and *omit* the raw `error` so the
 * logger's `util.inspect` of the cause chain (which would render
 * `[object Object]` for upstream `APICallError` shapes) is bypassed.
 * Otherwise fall back to the raw error so unrecognized failures keep
 * their full stack in logs.
 */
export declare function buildModelCallFailureLogFields(input: {
    readonly error: unknown;
    readonly errorId: string;
    readonly modelCallDetails: JsonObject;
    readonly recognized: boolean;
    readonly sessionId: string;
    readonly turnId: string;
}): Record<string, unknown>;
/**
 * The model call failed past its retries and recoveries. A failed write to the session's stream is
 * the workflow's failure, not the model's: the session parks for the user to retry. A terminal
 * failure ends the session; any other fails the turn recoverably.
 */
export declare function reportModelCallFailure(step: Step, error: unknown): Promise<StepResult>;