/**
 * Shared vision-caption relay: ask a vision-capable model to describe an image
 * as plain text, so a text-only main model can still work from it.
 */
import type { Api, ImageContent, Model, ProviderHeaders } from "@earendil-works/pi-ai";
export declare const VISION_CAPTION_SYSTEM_PROMPT: string;
export interface VisionCaptionRequestOptions {
    apiKey?: string;
    headers?: ProviderHeaders;
    signal?: AbortSignal;
    /** Called with the underlying error message when the caption request fails. */
    onError?: (message: string) => void;
    /**
     * The user's current instruction (e.g. "make this UI element bigger").
     * Included so the caption is targeted at the task, not generic.
     */
    userPrompt?: string;
    /**
     * A small, already-bounded slice of recent conversation text (or other relevant
     * context) to help the caption model understand intent. Must be small enough to
     * stay safely under the caption model's context window. Omit for none.
     */
    contextText?: string;
}
/**
 * Ask a vision model to describe an image. Returns the caption text, or null if
 * the request fails or is aborted. The request context is minimal (prompt +
 * image only), so it is independent of any main-agent context usage.
 */
export declare function captionImageWithModel(captionModel: Model<Api>, image: ImageContent, options?: VisionCaptionRequestOptions): Promise<string | null>;