import { StencilCredential } from "../stencil/credential.js";
import { type SpotlightThinking } from "./types.js";
/** Spotlight's `state`: the conversation context sent with the output. */
export interface SpotlightState {
    /** The user turn. */
    task?: string;
    /** Earlier bash calls, shown with their output omitted. */
    commands?: string[];
    /** What the current assistant turn says before its call. */
    said?: string;
    /** The current turn's reasoning; also fills `{intent}` in probes. */
    intent?: string;
}
/** One ranking request: every question reads the same items after the same state. */
export interface SpotlightRequest {
    state: SpotlightState;
    /** The command whose output the items are. */
    source: string;
    /** Output items, one or more lines each; at most 32,768 prompt tokens per question. */
    items: readonly string[];
    /** Question id → probe Spotlight scores each item's relevance under (1–32 questions). */
    questions: Readonly<Record<string, string>>;
    thinking?: SpotlightThinking;
}
/** Per-question item scores in [0, 1] (comparable within one request only), and what the request cost. */
export interface SpotlightReply {
    scores: Record<string, number[]>;
    inputTokens: number;
    /** `Stencil-Cost-Usd`: the charged list price (exempt accounts see the would-be price). */
    costUsd: number;
    ms: number;
    requestId: string | null;
}
/** A failed ranking: no credential, transport failure, timeout, or a non-200 answer. */
export declare class SpotlightError extends Error {
    /** HTTP status, or 0 when the request never got an answer. */
    readonly status: number;
    /** The error code the service sent, if any. */
    readonly code: string | null;
    constructor(message: string, 
    /** HTTP status, or 0 when the request never got an answer. */
    status: number, 
    /** The error code the service sent, if any. */
    code: string | null);
}
export interface SpotlightClientOptions {
    url?: string;
    model?: string;
    /** Budget of one {@link SpotlightClient.rank} call. */
    timeoutMs: number;
    credential?: StencilCredential;
    fetch?: typeof fetch;
}
/**
 * `POST /v1/spotlight` with the session's Stencil credential (`STENCIL_API_KEY`, else the stencil.so login, the
 * token `omp token stencil` prints). No retries: callers are inside a tool call and fall back to a rule instead.
 */
export declare class SpotlightClient {
    #private;
    readonly url: string;
    readonly model: string;
    constructor(options: SpotlightClientOptions);
    /**
     * Ranks `request.items` for every question.
     *
     * @throws {SpotlightError} without a Stencil credential (status 0, code `no_credential`), on a transport failure
     * or timeout (status 0), for any non-200 answer (its status and Cloud's error code), and for a reply that does not
     * score every item of every question (status 200, code `bad_reply`).
     */
    rank(request: SpotlightRequest, signal?: AbortSignal, timeoutMs?: number): Promise<SpotlightReply>;
    /**
     * Releases the auth store the client's own credential opened: its broker snapshot stream otherwise keeps a
     * one-shot process such as `omp find` alive until the store idles out (20 s). The client must not be used after.
     */
    close(): void;
    /**
     * Wakes the endpoint in the background so the session's first real ranking doesn't pay the cold start; at most
     * one warm-up in flight per client (a later call, e.g. after a timed-out ranking, wakes it again), failures
     * logged only.
     */
    warm(): void;
}