import type { AuthoritySessionHandle, ToolExecutionOutcome, OpenSessionParams } from './types.js';
import type { RealtimeSessionConfig } from '../realtime/RealtimeAudioClient.js';
/**
 * PORT: Transport-agnostic orchestration authority for AriaFlow.
 *
 * This is the single point of truth for conversational semantics that must
 * be consistent across text (Runtime) and realtime (RealtimeRuntime) execution.
 *
 * The authority owns:
 * - Session lifecycle (open, close, fail)
 * - Transcript recording
 * - Tool execution orchestration (via ToolExecutor + CapabilityHost routing)
 * - Hook lifecycle (onStart, onEnd, onToolResult, onHandoff, etc.)
 * - Persistence policy (with retry and error hooks)
 * - Post-turn extraction
 * - Memory ingestion
 * - Prompt assembly for realtime sessions
 *
 * The authority does NOT own:
 * - WebSocket or HTTP transport mechanics
 * - Audio encoding/decoding
 * - Provider wire formats
 * - LLM inference (that's the model client's job)
 * - Stream event emission (that's the text Runtime facade's job)
 *
 * Facades (Runtime, RealtimeRuntime) compose this authority and add
 * execution-mode-specific control flow on top.
 *
 * @see RFC-REALTIME-RUNTIME-AUTHORITY.md §4.1 Layer B
 */
export interface OrchestrationAuthority {
    /**
     * Open a new or existing session and prepare it for interaction.
     *
     * Responsibilities:
     * 1. Load or create session via ConversationState
     * 2. Set active agent via AgentStateController
     * 3. Bump session turn counter
     * 4. Build RunContext
     * 5. Fire onStart and onAgentStart hooks
     *
     * @returns A handle that carries session state across subsequent calls.
     */
    openSession(params: OpenSessionParams): Promise<AuthoritySessionHandle>;
    /**
     * Record user input (text transcript) into the session.
     * Used by both text (from stream input) and realtime (from speech-to-text).
     */
    recordUserInput(handle: AuthoritySessionHandle, text: string): Promise<void>;
    /**
     * When flow pre-LLM logic (expression transitions or tool nodes) updates the graph
     * during a realtime session, the new prompt/tools are queued here for the transport.
     */
    consumePendingRealtimeReconfigure(handle: AuthoritySessionHandle): Promise<RealtimeSessionConfig | undefined>;
    /**
     * Record assistant output (text transcript) into the session.
     * Used primarily by realtime path (assistant speech-to-text).
     * Text path records via stream events instead.
     */
    recordAssistantOutput(handle: AuthoritySessionHandle, text: string): Promise<void>;
    /**
     * Prepare initial realtime session configuration.
     * Builds the system prompt (via LivePromptAssembler) and tool declarations
     * for the active agent's current state.
     *
     * Used by RealtimeRuntime before connecting to the model client.
     */
    prepareRealtimeConfig(handle: AuthoritySessionHandle): Promise<RealtimeSessionConfig>;
    /**
     * Execute a tool call through the authority pipeline.
     *
     * Responsibilities:
     * 1. Resolve the tool from active agent's CapabilityHost
     * 2. Execute via ToolExecutor (enforcement, timeouts, idempotency)
     * 3. Record tool call and result events
     * 4. Fire onToolResult hook
     * 5. Route result through CapabilityHost.processToolResult()
     * 6. Persist session (fire-and-forget in hot path)
     * 7. If reconfigure: rebuild prompt and tools via assembler
     * 8. If handoff: fire onHandoff hook
     * 9. If end: fire onAgentEnd hook
     *
     * @returns Outcome describing what the facade should do next.
     */
    executeToolCall(handle: AuthoritySessionHandle, call: {
        id: string;
        name: string;
        args: unknown;
    }): Promise<ToolExecutionOutcome>;
    /**
     * Complete a turn after the model finishes responding.
     *
     * Responsibilities:
     * 1. Run post-turn extraction (if configured)
     * 2. Persist session with retry
     * 3. Run memory ingestion (if configured)
     * 4. Fire lifecycle hooks
     */
    completeTurn(handle: AuthoritySessionHandle): Promise<void>;
    /**
     * Close a session normally.
     *
     * Responsibilities:
     * 1. Fire onAgentEnd hook
     * 2. Fire onEnd hook (success: true)
     * 3. Clean up event log transient state
     * 4. Final session persistence with retry
     */
    closeSession(handle: AuthoritySessionHandle, result?: {
        success: boolean;
        error?: Error;
    }): Promise<void>;
    /**
     * Handle an unrecoverable session error.
     *
     * Responsibilities:
     * 1. Fire onError hook
     * 2. Fire onEnd hook (success: false)
     * 3. Clean up event log transient state
     * 4. Emergency session persistence (best-effort)
     */
    failSession(handle: AuthoritySessionHandle, error: Error): Promise<void>;
}