import type { TLlmRequest } from "../../lib/llm/types.js";
import { type TOpenAiFetch } from "./types.js";
/**
 * The status values the OpenAI Responses API reports for a stored
 * response. `completed` / `failed` / `incomplete` / `cancelled` are
 * terminal; `queued` / `in_progress` are transient.
 */
export type TResponseStatus = "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
/**
 * The structured result of a `retrieveResponse` call. All fields
 * except `status` and `rawResponseId` are absent for non-terminal
 * or failed responses.
 */
export type TRetrievedResponse = {
    /** Current status of the stored response. */
    status: TResponseStatus;
    /**
     * Parsed text output, present when `status === "completed"` and
     * the response carried a `message` output item.
     */
    output?: string;
    /** Token usage reported by OpenAI, when available. */
    tokenUsage?: import("../../lib/llm/types.js").TLlmTokenUsage;
    /** The OpenAI response id that was retrieved. */
    rawResponseId: string;
    /**
     * The envelope's `incomplete_details.reason`, present when
     * `status === "incomplete"` (e.g. `max_output_tokens`,
     * `content_filter`). Lets a completion-side consumer classify an
     * incomplete response without re-deriving it. Additive (since
     * v1.11.0).
     */
    incompleteReason?: string;
    /**
     * The envelope's `error.message`, present when `status === "failed"`.
     * Additive (since v1.11.0).
     */
    errorMessage?: string;
};
/**
 * Retrieve a stored OpenAI response by id. Surfaces the current
 * status, output text (when completed), and token usage.
 *
 * Throws {@link ResponseNotFoundError} when the response is not found
 * (HTTP 404), which typically means the ~10-minute retention window
 * has elapsed. Callers should clear the stored id, settle the
 * associated stage as failed, and surface a retry prompt.
 *
 * @param id - The OpenAI response id to retrieve.
 * @param options - Provider configuration (apiKey, optional baseUrl and fetch).
 */
export declare function retrieveResponse(id: string, options: {
    apiKey: string;
    baseUrl?: string;
    fetch?: TOpenAiFetch;
    signal?: AbortSignal;
}): Promise<TRetrievedResponse>;
/**
 * Reconnect to a stored, still-generating background response and
 * **stream it to completion**. This is what actually drives a dropped
 * background response forward: a passive `retrieveResponse` GET only
 * reads the current state and leaves a `queued` / `in_progress`
 * response sitting where it is, whereas reconnecting with `stream=true`
 * resumes consumption so the response reaches a terminal status.
 *
 * Issues `GET /responses/{id}?stream=true&starting_after=<cursor>` and
 * consumes the SSE stream to its terminal event, returning the same
 * {@link TRetrievedResponse} shape as {@link retrieveResponse}.
 *
 * Throws {@link ResponseNotFoundError} when the response is not found
 * (HTTP 404 — typically the ~10-minute retention window elapsed).
 * Honors `signal`: an abort propagates as an `AbortError` from the
 * underlying stream read.
 *
 * @param id - The OpenAI response id to reconnect to.
 * @param options - `apiKey`, optional `startingAfter` SSE cursor
 *   (defaults to 0 — replay from the start of the stored stream),
 *   optional `baseUrl`, `fetch`, and `signal`.
 */
export declare function reconnectStream(id: string, options: {
    apiKey: string;
    startingAfter?: number;
    baseUrl?: string;
    fetch?: TOpenAiFetch;
    signal?: AbortSignal;
}): Promise<TRetrievedResponse>;
/**
 * Cancel a stored, in-flight OpenAI response. Issues
 * `POST /responses/{id}/cancel` and returns the resulting
 * {@link TRetrievedResponse} (typically `status: "cancelled"`).
 *
 * Cancel is **idempotent** per the Responses API: cancelling twice, or
 * cancelling an already-terminal response, simply returns the final
 * `Response` object rather than erroring — so callers do not need to
 * guard against double-cancel.
 *
 * Throws {@link ResponseNotFoundError} when the response is not found
 * (HTTP 404 — typically the ~10-minute retention window elapsed).
 * Honors `signal` (an abort propagates as an `AbortError`).
 *
 * Use this to stop an in-flight background response when a stage is
 * abandoned (resync timeout) or an import is cancelled, so generation
 * does not keep running (and billing) server-side after the consumer
 * has given up on it.
 *
 * @param id - The OpenAI response id to cancel.
 * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
 */
export declare function cancelResponse(id: string, options: {
    apiKey: string;
    baseUrl?: string;
    fetch?: TOpenAiFetch;
    signal?: AbortSignal;
}): Promise<TRetrievedResponse>;
/**
 * Submit a background OpenAI response and return its `responseId` +
 * submit-time `status` **without polling or streaming to completion**.
 *
 * This is the submit-only half of the existing `backgroundMode`
 * (`runBackground`): it POSTs `{ background: true, store: true }`, parses
 * the submit envelope, and returns immediately — the caller drives the
 * response to completion later via {@link retrieveResponse} (typically
 * after a durable suspend keyed on the returned `responseId`). It is the
 * provider capability the pipeline's `launchStage` needs.
 *
 * **Terminal-on-submit fast-path:** a small/cached request can come back
 * already terminal (`completed`/`failed`/`incomplete`/`cancelled`) on the
 * submit POST. This function still returns `{ responseId, status }` for
 * that case (no throw, no poll); the caller proceeds to
 * `retrieveResponse(responseId)`, which sees the terminal state
 * immediately.
 *
 * **No-tools precondition:** background mode does not support function
 * tools in V1 — a tool-bearing request throws {@link NonRetryableLlmError},
 * matching `respond`'s background guard.
 *
 * @param req - The structured-output request (system/user prompts +
 *   `outputSchema` + model knobs). Tools are rejected.
 * @param options - `apiKey`, optional `baseUrl`, `fetch`, and `signal`.
 */
export declare function submitBackgroundResponse<T>(req: TLlmRequest<T>, options: {
    apiKey: string;
    baseUrl?: string;
    fetch?: TOpenAiFetch;
    signal?: AbortSignal;
}): Promise<{
    responseId: string;
    status: TResponseStatus;
}>;
//# sourceMappingURL=openai-retrieval.d.ts.map