import { EventEmitter } from './eventEmitter.js';
import type { FunctionTool, ToolRunContext } from './tools.js';
import type { ContextWindow } from './config.js';
/** Configuration for a background audio clip played during a call. */
export type BackgroundAudioConfig = {
    /** URL or local file path of the audio to play. */
    file_url: string;
    /** Playback volume, 0.0-1.0. */
    volume: number;
    /** Whether the clip loops until stopped. */
    looping: boolean;
};
/** Configuration for preloading a background audio clip ahead of playback. */
export type PreloadAudioConfig = {
    /** URL or local file path of the audio to preload. */
    file_url: string;
    /** Playback volume to associate with the preloaded clip, 0.0-1.0. */
    volume: number;
};
/**
 * The live session interface available to an {@link Agent} via {@link Agent.session}.
 * Provides call controls (hangup, background audio) for the current call. The full
 * runtime session implements this and many more members.
 */
export type AgentSession = {
    /** End the current call. */
    hangup(): Promise<void> | void;
    /** Start playing a background audio clip. */
    playBackgroundAudio(config: BackgroundAudioConfig, options: {
        override_thinking: boolean;
    }): Promise<void> | void;
    /** Stop any background audio. */
    stopBackgroundAudio(): Promise<void> | void;
    /** Preload a background audio clip for low-latency playback. */
    preloadBackgroundAudio(config: PreloadAudioConfig): Promise<void> | void;
    /** The active pipeline, exposing recent captured vision frames when available. */
    pipeline?: {
        getLatestFrames?(numOfFrames: number): unknown[];
    } | null;
    [key: string]: any;
};
/** Events emitted by an {@link Agent}. */
export type AgentEvents = Record<string, unknown[]> & {
    /** Fired when the agent has started in a session. */
    agent_started: unknown[];
};
/** Options for constructing an {@link Agent}. */
export type AgentOptions = {
    /** System prompt / instructions for the agent. Pass it here, or as the first positional
     *  constructor argument. */
    instructions?: string;
    /** Tools the agent exposes to its model. Defaults to none. */
    tools?: FunctionTool[] | null;
    /** Display name. Defaults to the agent's {@link AgentOptions.agentId | id}. */
    name?: string | null;
    /** Stable agent id. Defaults to the class name. */
    agentId?: string | null;
    /** The {@link Pipeline} this agent runs on. Defaults to `null`. */
    pipeline?: unknown;
    /** Maximum call duration in seconds, or `null` for no limit. Defaults to `null`. */
    maxSessionDurationSeconds?: number | null;
    /** MCP servers to attach. Defaults to none. */
    mcpServers?: unknown[] | null;
    /** Whether the agent inherits conversation context on handoff. Defaults to `false`. */
    inheritContext?: boolean;
    /** Suffix appended to instructions to steer voice/style, or `null`. Defaults to `null`. */
    voiceSuffix?: string | null;
    /** Whether {@link AgentOptions.voiceSuffix} is appended. Defaults to `true`. */
    appendVoiceSuffix?: boolean;
    /** Sub-agents available for handoff via `agentSwitch`. Defaults to none. */
    agents?: Agent[] | null;
    /** Context-window policy for trimming conversation history. Defaults to `null`. */
    contextWindow?: ContextWindow | null;
};
/**
 * A voice agent: instructions plus tools, optional sub-agents, and call-control
 * behavior. Subclass it and decorate methods as tools, give it a {@link Pipeline},
 * then register it with `serve` and start calls against it with `invoke` - the
 * serving worker runs each call in an {@link AgentSession}. Within a live call,
 * `this.session` resolves to the current {@link AgentSession}.
 */
export declare class Agent extends EventEmitter<AgentEvents> {
    private _instructions;
    private readonly _tools;
    /** Display name of the agent. */
    name: string;
    /** Stable agent id (used for handoff routing). */
    id: string;
    /** The {@link Pipeline} this agent runs on, if set. */
    pipeline: unknown;
    /** Maximum call duration in seconds, or `null` for no limit. */
    maxSessionDurationSeconds: number | null;
    /** Per-call dispatch metadata, set by {@link serve} before `onEnter`. Defaults to `{}`. */
    metadata: Record<string, unknown>;
    /** Room id for the current call, set by {@link serve} before `onEnter`, or `null`. */
    roomId: string | null;
    private _sessionRef;
    /** The current live {@link AgentSession} for this call, or `null` outside a call. */
    get session(): AgentSession | null;
    set session(value: AgentSession | null);
    /** The agent's current chat context, if attached. */
    chatContext: unknown;
    /** Whether the agent inherits conversation context on handoff. */
    inheritContext: boolean;
    private readonly _mcpServers;
    private _thinkingBackgroundConfig;
    /** Suffix appended to instructions to steer voice/style, or `null`. */
    voiceSuffix: string | null;
    /** Whether {@link Agent.voiceSuffix} is appended to instructions. */
    appendVoiceSuffix: boolean;
    /** Context-window policy for trimming history, or `null`. */
    contextWindow: ContextWindow | null;
    /** Sub-agents available for handoff. */
    agents: Agent[];
    /** Agent-to-agent (A2A) handle, when configured. */
    a2a: unknown;
    /** MCP manager, when MCP servers are attached. */
    mcpManager: unknown;
    private _agentCard;
    /** Background audio clips to preload at session start. */
    preloadBgAudio: unknown[];
    /**
     * Accepts either an all-in-options object (`new Agent({ instructions, agentId, ... })`)
     * or instructions-first (`new Agent(instructions, { agentId, ... })`).
     *
     * @param instructions The system prompt / instructions for the agent.
     * @param options See {@link AgentOptions}.
     */
    constructor(instructions: string, options?: AgentOptions);
    constructor(options: AgentOptions);
    /** Alias for {@link Agent.id}. */
    get agentId(): string;
    /** The agent's instructions (system prompt). Settable at runtime. */
    get instructions(): string;
    set instructions(value: string);
    /** The tools currently exposed to the model. */
    get tools(): FunctionTool[];
    /**
     * Scan this instance (and its prototype chain) for methods marked as tools and add
     * them to {@link Agent.tools}. Called automatically by the constructor.
     */
    registerTools(): void;
    /** Replace the agent's tool set with `tools`. */
    updateTools(tools: FunctionTool[]): void;
    /** End the current call, if a session is active. */
    hangup(): Promise<void>;
    /**
     * Speak `message` through the pipeline's text-to-speech (no model call).
     * No-op when no session is active. Also reachable as `ctx.session.say(...)`.
     */
    say(message: string, opts?: Record<string, unknown>): Promise<unknown>;
    /**
     * Ask the model to produce a reply given `instructions`, then speak it.
     * No-op when no session is active. Also reachable as `ctx.session.reply(...)`.
     */
    reply(instructions: string, opts?: Record<string, unknown>): Promise<unknown>;
    /**
     * Interrupt the current utterance and cancel any in-flight generation.
     * No-op when no session is active. Also reachable as `ctx.session.interrupt(...)`.
     */
    interrupt(opts?: Record<string, unknown>): Promise<unknown>;
    /**
     * Set the audio looped while the agent is "thinking" (generating). Pass a falsy
     * `file` to clear it.
     * @param volume Playback volume 0.0-1.0. Defaults to `0.3`.
     */
    setThinkingAudio(file?: string | null, volume?: number): void;
    /**
     * Play a background audio clip during the call. No-op without an active session or file.
     * @param volume Playback volume 0.0-1.0. Defaults to `1.0`.
     * @param looping Whether to loop the clip. Defaults to `false`.
     * @param overrideThinking Whether this clip overrides any thinking audio. Defaults to `true`.
     */
    playBackgroundAudio(file?: string | null, volume?: number, looping?: boolean, overrideThinking?: boolean): Promise<void>;
    /** Stop any background audio, if a session is active. */
    stopBackgroundAudio(): Promise<void>;
    /**
     * Preload a background audio clip for low-latency playback.
     * @param volume Playback volume 0.0-1.0. Defaults to `1.0`.
     */
    preloadBackgroundAudio(file?: string | null, volume?: number): Promise<void>;
    /** Initialize attached MCP servers. Override to add custom MCP setup. */
    initializeMcp(): Promise<void>;
    /** Attach an MCP server at runtime. Override to add custom handling. */
    addServer(_mcpServer: unknown): Promise<void>;
    /** Register an agent-to-agent (A2A) card. Override to add custom handling. */
    registerA2a(_card: unknown): Promise<void>;
    /** Unregister the agent's A2A card. Override to add custom handling. */
    unregisterA2a(): Promise<void>;
    /** Release agent resources. Override for custom teardown. */
    cleanup(): Promise<void>;
    /**
     * Capture the most recent vision frame(s) from the active session's pipeline.
     * Returns an empty array if vision frames are unavailable.
     * @param numOfFrames Number of most-recent frames to return. Defaults to `1`.
     */
    captureFrames(numOfFrames?: number): unknown[];
    /** Lifecycle hook run when the agent becomes active in a call. Override it. */
    onEnter(): Promise<void>;
    /** Lifecycle hook run when the agent leaves the call. Override it. */
    onExit(): Promise<void>;
}
/** A single tool in a {@link CreateAgentSpec.tools} map. The map key is the tool name. */
export type ToolSpec<P = any> = {
    /** Natural-language description shown to the model. */
    description?: string;
    /** A Zod schema for the arguments. Converted to JSON Schema; takes precedence over `parameters`. */
    input?: unknown;
    /** Raw JSON Schema for the arguments. Used when `input` is not a Zod schema. */
    parameters?: object;
    /** Optional spoken filler phrase played while the tool runs. */
    filler?: string | null;
    /** Delay in milliseconds before the filler is spoken. */
    fillerGracePeriod?: number | null;
    /** Handler; the second argument is `{ ctx }` with the live session and agent. */
    execute: (args: P, ctx: {
        ctx: ToolRunContext;
    }) => any | Promise<any>;
};
/** Declarative spec for {@link createAgent} - the functional authoring surface. */
export type CreateAgentSpec = {
    /** Stable agent id (used for handoff routing). */
    agentId?: string;
    /** Display name. Defaults to the id. */
    name?: string;
    /** System prompt / instructions. */
    instructions?: string;
    /** The pipeline this agent runs on. */
    pipeline?: unknown;
    /** Tools, keyed by tool name. */
    tools?: Record<string, ToolSpec>;
    /** Lifecycle hook run when the agent becomes active in a call. */
    onEnter?: (this: Agent, ctx: ToolRunContext) => void | Promise<void>;
    /** Lifecycle hook run when the agent leaves the call. See {@link CreateAgentSpec.onEnter}. */
    onExit?: (this: Agent, ctx: ToolRunContext) => void | Promise<void>;
    /** MCP servers to attach. */
    mcpServers?: unknown[];
    /** Sub-agents available for handoff. */
    agents?: Agent[];
    /** Context-window policy for trimming history. */
    contextWindow?: unknown;
    /** Whether the agent inherits conversation context on handoff. */
    inheritContext?: boolean;
    /** Maximum call duration in seconds, or `null` for no limit. */
    maxSessionDurationSeconds?: number | null;
    /** Suffix appended to instructions to steer voice/style, or `null`. */
    voiceSuffix?: string | null;
    /** Whether the voice suffix is appended. Defaults to `true`. */
    appendVoiceSuffix?: boolean;
};
/**
 * Build an {@link Agent} from a declarative spec - the functional authoring surface.
 * Tools are a name-to-spec map; `onEnter`/`onExit` receive a live `{ session, agent }` context.
 */
export declare function createAgent(spec: CreateAgentSpec): Agent;