import { ChatRole } from './enums.js';
import type { ContextMessageProto } from '../proto/types.js';
import type { CoerceImageOptions, ImageFrame } from './images.js';
/** Options for {@link ChatContent}. */
export type ChatContentOptions = {
    /** Content kind. Defaults to `'text'`. */
    type?: string;
    /** The text body. Defaults to `''`. */
    text?: string;
};
/** A piece of textual message content. */
export type ChatContent = {
    type: string;
    text: string;
};
/** Create a {@link ChatContent} text block. */
export declare function ChatContent(opts?: ChatContentOptions): ChatContent;
/** Options for {@link ImageContent}. */
export type ImageContentOptions = {
    /** Content kind. Defaults to `'image'`. */
    type?: string;
    /** Image URL or `data:` URL. Defaults to `''`. */
    url?: string;
    /** Vision detail hint: `'auto'`, `'low'`, or `'high'`. Defaults to `'auto'`. */
    detail?: string;
};
/** An image attached to a message, referenced by URL or inline `data:` URL. */
export type ImageContent = {
    type: string;
    url: string;
    detail: string;
};
type VisionFrameLike = {
    data: Buffer | Uint8Array | ArrayBuffer;
    mimeType?: string;
    mime_type?: string;
};
declare function makeImageContent(opts?: ImageContentOptions): ImageContent;
/**
 * Create an {@link ImageContent}, or one of its helper constructors:
 * `fromUrl`, `fromDataUrl`, `fromBase64`, `fromBytes`, `fromFile`, `fromFrame`.
 * All accept a `detail` hint (`'auto'` | `'low'` | `'high'`, default `'auto'`).
 */
export declare const ImageContent: typeof makeImageContent & {
    /** Reference an image by http(s) URL. */
    fromUrl(url: string, detail?: string): ImageContent;
    /** Wrap an existing `data:` URL. Throws if `dataUrl` is not a data URL. */
    fromDataUrl(dataUrl: string, detail?: string): ImageContent;
    /** Build a `data:` URL from a base64 string and MIME type. */
    fromBase64(base64: string, mimeType: string, detail?: string): ImageContent;
    /** Build a `data:` URL from raw image bytes and a MIME type. */
    fromBytes(bytes: Buffer | Uint8Array | ArrayBuffer, mimeType: string, detail?: string): ImageContent;
    /** Read an image file and inline it as a `data:` URL. Throws on unrecognized image types. */
    fromFile(path: string, detail?: string): Promise<ImageContent>;
    /** Build image content from a captured vision frame, encoding to JPEG if needed. */
    fromFrame(frame: ImageFrame | VisionFrameLike, opts?: {
        detail?: string;
        encode?: CoerceImageOptions;
    }): Promise<ImageContent>;
};
/** Options for {@link FunctionCall}. */
export type FunctionCallOptions = {
    /** Name of the tool being called. Defaults to `''`. */
    name?: string;
    /** Call arguments as a JSON string. Defaults to `''`. */
    arguments?: string;
    /** Unique id correlating this call with its output. Defaults to `''`. */
    callId?: string;
};
/** A tool/function call requested by the model. */
export type FunctionCall = {
    name: string;
    arguments: string;
    callId: string;
};
/** Create a {@link FunctionCall}. */
export declare function FunctionCall(opts?: FunctionCallOptions): FunctionCall;
/** Options for {@link FunctionCallOutput}. */
export type FunctionCallOutputOptions = {
    /** Name of the tool that produced this output. Defaults to `''`. */
    name?: string;
    /** The tool's result, serialized as a string. Defaults to `''`. */
    output?: string;
    /** Id matching the originating {@link FunctionCall}. Defaults to `''`. */
    callId?: string;
    /** Whether the output represents an error. Defaults to `false`. */
    isError?: boolean;
};
/** The result of a tool/function call, returned to the model. */
export type FunctionCallOutput = {
    name: string;
    output: string;
    callId: string;
    isError: boolean;
};
/** Create a {@link FunctionCallOutput}. */
export declare function FunctionCallOutput(opts?: FunctionCallOutputOptions): FunctionCallOutput;
/** Options for {@link ChatMessage}. */
export type ChatMessageOptions = {
    /** Author role. Defaults to {@link ChatRole.USER}. */
    role?: ChatRole;
    /** Message text. Defaults to `''`. */
    content?: string;
    /** Stable message id. Defaults to `''`. */
    messageId?: string;
    /** Tool calls requested in this message. Defaults to `[]`. */
    toolCalls?: FunctionCall[];
    /** Id of the tool call this message responds to. Defaults to `''`. */
    toolCallId?: string;
    /** Attached images. Defaults to `[]`. */
    images?: ImageContent[];
    /** Id of the agent that authored the message (multi-agent attribution). Defaults to `''`. */
    agentId?: string;
    /** Creation timestamp (epoch seconds), or `null` when unset. Defaults to `null`. */
    createdAt?: number | null;
};
/** A single message in a conversation. */
export type ChatMessage = {
    role: ChatRole;
    content: string;
    messageId: string;
    toolCalls: FunctionCall[];
    toolCallId: string;
    images: ImageContent[];
    agentId: string;
    createdAt: number | null;
};
/** Create a {@link ChatMessage}. */
export declare function ChatMessage(opts?: ChatMessageOptions): ChatMessage;
/** A record of a control transfer from one agent to another during a session. */
export type AgentHandoff = {
    /** Auto-generated unique id for the handoff. */
    id: string;
    /** Id of the agent that handed off. */
    fromAgent: string;
    /** Id of the agent that received control. */
    toAgent: string;
    /** Human-readable reason for the handoff. */
    reason: string;
};
/** Create an {@link AgentHandoff} record (with a generated id). */
export declare function AgentHandoff(opts?: {
    fromAgent?: string;
    toAgent?: string;
    reason?: string;
}): AgentHandoff;
/**
 * An ordered collection of {@link ChatMessage}s plus handoff history, with helpers for
 * building, copying, truncating, and exporting conversation context. Create one with
 * {@link ChatContext}().
 */
export type ChatContext = {
    /** Live, mutable view of the underlying messages. Prefer {@link ChatContext.messages} for a copy. */
    readonly items: ChatMessage[];
    /** Return a shallow copy of the messages. */
    messages(): ChatMessage[];
    /** Number of user turns in the context. */
    turnCount(): number;
    /** Rough token estimate (~2 tokens per word). */
    estimatedTokens(): number;
    /**
     * Append a message and return it. Generates a `messageId` if none is given.
     * With `replace=true` and `role=SYSTEM`, replaces the existing system message in
     * place instead of appending a duplicate.
     */
    addMessage(role: ChatRole, content: string, messageId?: string, images?: ImageContent[], createdAt?: number | null, replace?: boolean): ChatMessage;
    /** Like {@link ChatContext.addMessage} but tags the message with an authoring `agentId`. */
    addAttributedMessage(role: ChatRole, content: string, agentId: string, messageId?: string, images?: ImageContent[]): ChatMessage;
    /** Record an assistant tool call as an ASSISTANT message carrying a {@link FunctionCall}. */
    addFunctionCall(name: string, args: string, callId?: string, messageId?: string, agentId?: string): ChatMessage;
    /** Record a tool result as a TOOL-role message linked to its `callId`. */
    addFunctionOutput(name: string, output: string, callId: string, isError?: boolean, messageId?: string, agentId?: string): ChatMessage;
    /** Record a handoff to another agent and return it. */
    addHandoff(toAgent: string, fromAgent?: string, reason?: string): AgentHandoff;
    /** Return a copy of the recorded handoffs. */
    handoffs(): AgentHandoff[];
    /** The most recent handoff, or `null` if none. */
    lastHandoff(): AgentHandoff | null;
    /**
     * Return a deep, independent copy of this context.
     * @param opts.excludeSystemMessages Drop SYSTEM messages from the copy.
     * @param opts.excludeEmptyMessages Drop messages with no content, tool calls, or images.
     */
    copy(opts?: {
        excludeSystemMessages?: boolean;
        excludeEmptyMessages?: boolean;
    }): ChatContext;
    /**
     * Return a new context trimmed to the most recent messages.
     * @param opts.maxItems Keep at most this many messages (most recent kept).
     * @param opts.maxTokens Drop oldest messages until the estimate fits within this budget.
     */
    truncate(opts?: {
        maxItems?: number;
        maxTokens?: number;
    }): ChatContext;
    /** Export to OpenAI chat messages (text, image parts, tool calls, tool results). */
    toOpenaiMessages(opts?: {
        reasoningModel?: boolean;
    }): Array<Record<string, any>>;
    /**
     * Render as Anthropic Messages. The system text is returned separately in `system`
     * (Anthropic takes it as a top-level field, not as a message).
     */
    toAnthropicMessages(): {
        messages: Array<Record<string, any>>;
        system: string | null;
    };
    /** Render as Google Gemini `contents`, with the system text returned in `systemInstruction`. */
    toGoogleContents(): {
        contents: Array<Record<string, any>>;
        systemInstruction: string | null;
    };
    /** Append another context's messages in place, de-duped by `messageId`; returns this context. */
    merge(other: ChatContext | ChatMessage[]): ChatContext;
    /** Serialize the whole context (messages + handoffs) to a plain object. */
    toDict(): {
        items: ContextMessageProto[];
        handoffs: Array<Record<string, string>>;
    };
    /** Serialize the conversation context for sending to Zero Runtime. */
    toContextMessages(): ContextMessageProto[];
};
/**
 * Create a {@link ChatContext}, optionally seeded with messages. Also exposes
 * `ChatContext.empty()`, `ChatContext.fromContextMessages(...)`, and `ChatContext.fromDict(...)`.
 */
export declare const ChatContext: {
    (initialMessages?: ChatMessage[]): ChatContext;
    /** Create an empty context. */
    empty(): ChatContext;
    /** Build a context from serialized context messages received from the live session. */
    fromContextMessages(messages: ContextMessageProto[]): ChatContext;
    /** Rebuild a context from {@link ChatContext.toDict} output. */
    fromDict(data: any): ChatContext;
};
export {};