import type { Settings } from "../config/settings.js";
import type { SessionManager } from "../session/session-manager.js";
import { SpotlightClient } from "./client.js";
import { type ShapeState } from "./shape/index.js";
import { ArtifactShapeSink } from "./sink.js";
import { type SpotlightEntryType, type SpotlightSession, type SpotlightThinking } from "./types.js";
/**
 * Schema description of the tool-call intent field `i` in experiment sessions. Spotlight ranks output against the
 * intent, so it asks what the agent wants from the call's output; `PI_INTENT_DESC` still overrides it.
 */
export declare const SPOTLIGHT_INTENT_DESCRIPTION: string;
/**
 * System-prompt guidance for `i` in experiment sessions (see {@link SPOTLIGHT_INTENT_DESCRIPTION});
 * `PI_INTENT_PROMPT` still overrides it.
 */
export declare const SPOTLIGHT_INTENT_GUIDANCE: string;
/** The journal fields of a `spotlight:session` entry: what the session shapes with, and the coin shares in effect. */
export interface SpotlightSessionEntry extends SpotlightShares {
    /** The tools whose results the session shapes and journals (`spotlight.experiment.tools`; `*`: every tool). */
    tools: string[];
    model: string;
    thinking: SpotlightThinking;
    /** Host of the Spotlight endpoint. */
    urlHost: string;
    piVersion: string;
}
/** The coins the experiment draws per result, as shares in [0, 1]. */
export interface SpotlightShares {
    /** Would-be cuts held out (`spotlight.experiment.holdout`). */
    holdout: number;
    /** Results not held out that are shaped without Spotlight (`spotlight.experiment.scoreFree`). */
    scoreFree: number;
}
/** The coins drawn for one result; at most one lands. */
export interface SpotlightCoins {
    holdout: boolean;
    scoreFree: boolean;
}
/** How an experiment draws its coins and which tools it shapes. */
export interface SpotlightExperimentOptions extends Partial<SpotlightShares> {
    /** Tool names whose results are shaped (`*`: every tool); default every tool. */
    tools?: readonly string[];
}
/**
 * The experiment's state for one session: the Spotlight client, the coin shares, and the per-session shaping state
 * (lines already shown, cuts made) shaping reads and updates.
 */
export declare class SpotlightExperiment implements SpotlightSession {
    #private;
    readonly client: SpotlightClient;
    readonly thinking: SpotlightThinking;
    readonly sink: ArtifactShapeSink;
    shapeState: ShapeState;
    readonly shares: SpotlightShares;
    /** The configured tool list, as journaled. */
    readonly tools: readonly string[];
    constructor(client: SpotlightClient, thinking: SpotlightThinking, sessionManager: SessionManager, options?: SpotlightExperimentOptions, random?: () => number);
    /** Whether the session shapes and journals the results of `tool` (`spotlight.experiment.tools`). */
    shapesTool(tool: string): boolean;
    /**
     * Marks call `toolCallId` as shaped; false when it already was (a tool delegating to another under the same call
     * id, a tool that shaped its own result before its wrapper returned).
     */
    claimCall(toolCallId: string): boolean;
    /**
     * The coins of one result the arm is about to shape, drawn before shaping so the groups are alike: `holdout` with
     * probability {@link SpotlightShares.holdout}; else `scoreFree` with probability {@link SpotlightShares.scoreFree}.
     * At most one lands, and none is drawn after it.
     */
    drawCoins(): SpotlightCoins;
    log(type: SpotlightEntryType, data: Record<string, unknown>): void;
    /** The `spotlight:session` entry this session writes. */
    sessionEntry(): SpotlightSessionEntry;
    /** Text of a session artifact (a tool's full output), or null when it is gone or unreadable. */
    readArtifact(id: string): Promise<string | null>;
    /**
     * The agent session moved to another session file (new, resume, fork): its journal gets the live
     * `spotlight:session` entry unless its last one already matches, and shaping starts over.
     */
    onSessionChange(): void;
}
/**
 * Starts the experiment for a session when `spotlight.experiment.enabled`: journals the `spotlight:session` entry
 * and wakes Spotlight, which ranks both shaping and `find`.
 */
export declare function startSpotlightExperiment(settings: Settings, sessionManager: SessionManager): SpotlightExperiment | undefined;
/**
 * How `omp find` ranks filenames outside a session: Spotlight's handle when `spotlight.experiment.enabled`, else
 * undefined (the judge ranks). Nothing is journaled, since no session exists.
 */
export declare function standaloneFindSpotlight(settings: Settings): Pick<SpotlightSession, "client" | "thinking"> | undefined;