bamboo-llm 2026.10.21

//! LLM provider trait and types
//!
//! This module defines the interface for LLM (Large Language Model) providers,
//! enabling support for multiple LLM backends through a common trait.

use crate::prompt_ir::PromptIR;
use crate::types::LLMChunk;
use async_trait::async_trait;
use bamboo_domain::ToolSchema;
use bamboo_domain::{CapabilityLoadingMode, ReasoningEffort};
use bamboo_domain::{Message, ModelContextResetReason};
use futures::Stream;
use serde::Serialize;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use thiserror::Error;

/// Observes the concrete provider selected for one scoped main dispatch.
/// Observation does not authorize the provider or prove a managed origin.
#[doc(hidden)]
pub type MainDispatchObserver = Arc<dyn Fn(Arc<dyn LLMProvider>) + Send + Sync>;

tokio::task_local! {
    static MAIN_DISPATCH_OBSERVER: MainDispatchObserver;
}

/// Scope one actual main dispatch attempt. The observer is not inherited by
/// spawned tasks; a Host caller must reject a missing receipt rather than
/// inferring an unmanaged route. Nested scopes restore their outer observer.
#[doc(hidden)]
pub async fn scope_main_dispatch<F: Future>(
    observer: MainDispatchObserver,
    future: F,
) -> F::Output {
    MAIN_DISPATCH_OBSERVER.scope(observer, future).await
}

/// Report the exact Arc selected by a forwarding boundary. Returns false if
/// no observer was scoped in the current task; ordinary SDK calls keep their
/// existing behavior and the Host owns the missing-receipt failure policy.
#[doc(hidden)]
pub fn observe_main_dispatch(selected: Arc<dyn LLMProvider>) -> bool {
    MAIN_DISPATCH_OBSERVER
        .try_with(|observer| observer(selected))
        .is_ok()
}

/// Allocation identity for pairing delayed requests. Dynamic credentials
/// inside an existing provider remain the provider owner’s responsibility.
#[doc(hidden)]
#[derive(Clone)]
pub enum QueuedRouteIdentity {
    Stable(Arc<dyn LLMProvider>),
    Unmanaged,
}

/// Errors that can occur when working with LLM providers
#[derive(Error, Debug)]
pub enum LLMError {
    /// HTTP request/response errors
    #[error("HTTP error: {0}")]
    Http(#[from] reqwest::Error),

    /// JSON serialization/deserialization errors
    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),

    /// Streaming response errors
    #[error("Stream error: {0}")]
    Stream(String),

    /// LLM API errors (rate limits, invalid requests, etc.)
    #[error("API error: {0}")]
    Api(String),

    /// Authentication/authorization errors
    #[error("Authentication error: {0}")]
    Auth(String),

    /// The provider already applied its bounded request policy. Callers must
    /// retain this terminal boundary instead of retrying the entire agent turn.
    #[error("{0}")]
    RequestFailed(String),

    /// Protocol conversion errors
    #[error("Protocol conversion error: {0}")]
    Protocol(#[from] crate::protocol::ProtocolError),
}

/// Convenient result type for LLM operations
pub type Result<T> = std::result::Result<T, LLMError>;

/// Type alias for boxed streaming LLM responses
pub type LLMStream = Pin<Box<dyn Stream<Item = Result<LLMChunk>> + Send>>;

/// Why one compact tool-schema segment is visible at its model position.
///
/// The footprint deliberately describes already-lowered JSON rather than
/// estimating tokens in the provider crate. Adjacent top-level definitions are
/// one segment; provider-inlined definitions later in history are separate
/// segments because prompt text lies between those positions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProviderVisibleToolSegmentKind {
    /// Complete definitions visible in the request's initial tools position.
    InitialFullDefinition,
    /// Name and description retained for one or more OpenAI hosted-search
    /// functions while their parameter schemas remain deferred.
    InitialDeferredDescriptor,
    /// A complete Anthropic definition expanded at a validated tool reference.
    AnthropicToolReferenceExpansion,
    /// Empty marker following an initial search-enabled definition array. Later
    /// definitions are bound by the provider or by transcript items rather than
    /// duplicated at the initial position.
    ProviderLateBound,
}

/// One compact serialized provider-visible schema position.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProviderVisibleToolSegment {
    pub kind: ProviderVisibleToolSegmentKind,
    pub serialized: String,
}

impl ProviderVisibleToolSegment {
    pub(crate) fn from_serializable<T: Serialize + ?Sized>(
        kind: ProviderVisibleToolSegmentKind,
        value: &T,
    ) -> Result<Self> {
        Ok(Self {
            kind,
            serialized: serde_json::to_string(value)?,
        })
    }

    pub(crate) fn empty_marker(kind: ProviderVisibleToolSegmentKind) -> Self {
        Self {
            kind,
            serialized: String::new(),
        }
    }
}

/// Ordered tool-schema material visible to a provider model for one request.
///
/// [`ProviderVisibleToolSegmentKind::ProviderLateBound`] explicitly marks
/// provider-selected schema material that cannot be known before dispatch. It
/// is not included in the known local token estimate; provider-reported usage
/// remains authoritative after the response.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProviderVisibleToolFootprint {
    pub segments: Vec<ProviderVisibleToolSegment>,
}

/// Metadata for a provider model returned by `list_model_info`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProviderModelInfo {
    /// Model identifier.
    pub id: String,
    /// Maximum total context window (input + output) in tokens when known.
    /// Provider adapters that receive an input-only limit must add the model's
    /// output capacity before populating this field.
    pub max_context_tokens: Option<u32>,
    /// Maximum output/completion tokens when known.
    pub max_output_tokens: Option<u32>,
}

impl ProviderModelInfo {
    /// Create metadata with only model id (no token limits).
    pub fn from_id(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            max_context_tokens: None,
            max_output_tokens: None,
        }
    }
}

/// Optional request-time controls for provider calls.
#[derive(Debug, Clone, Default)]
pub struct ResponsesRequestOptions {
    /// Optional top-level instructions for Responses API requests.
    pub instructions: Option<String>,
    /// Optional message list to serialize into the Responses API `input` array.
    ///
    /// When omitted, providers fall back to the generic `messages` slice passed
    /// to `chat_stream_with_options`. This lets the engine provide a
    /// Responses-specific input view (for example, without a duplicated stable
    /// system message) while preserving backward compatibility for non-Responses
    /// callers and providers.
    pub input_messages: Option<Vec<Message>>,
    /// Validated provider-native Responses items, grouped by the ordinary
    /// assistant message they replace. Internal only; the OpenAI adapter lowers
    /// these at their anchored `input` position.
    pub provider_transcript_groups: Vec<bamboo_domain::ProviderTranscriptGroup>,
    /// Optional reasoning summary control for Responses API requests
    /// (e.g. "auto", "concise", "detailed").
    pub reasoning_summary: Option<String>,
    /// Optional include list for Responses API requests.
    pub include: Option<Vec<String>>,
    /// Whether Responses API should store the response server-side.
    pub store: Option<bool>,
    /// Optional continuation handle for stateful Responses API turns.
    pub previous_response_id: Option<String>,
    /// Optional truncation mode for Responses API requests
    /// (e.g. "auto", "disabled").
    pub truncation: Option<String>,
    /// Optional text verbosity for Responses API requests
    /// (e.g. "low", "medium", "high").
    pub text_verbosity: Option<String>,
    /// Stable affinity key for OpenAI prompt caching. Callers should provide a
    /// privacy-preserving value. The agent loop supplies a domain-separated hash,
    /// never its raw session identity, through this generic request DTO.
    pub prompt_cache_key: Option<String>,
    /// OpenAI request-wide cache policy (currently `mode` and optional `ttl`).
    /// Kept as JSON so newly added official policy keys survive proxying.
    pub prompt_cache_options: Option<serde_json::Value>,
    /// Original Responses `input` retained by the compatibility endpoint when
    /// it contains caller-authored explicit cache breakpoints.
    ///
    /// The OpenAI Responses adapter may use this instead of the provider-neutral
    /// message rendering so supported `input_text`, `input_image`, and
    /// `input_file` markers survive byte-for-byte. Agent/runtime calls leave it
    /// unset.
    pub raw_input_with_cache_breakpoints: Option<serde_json::Value>,
    /// Internal model-context prefix epoch used only for safe wire-shape
    /// diagnostics. It is never serialized into the upstream request.
    pub prefix_epoch: Option<u64>,
    /// Internal, secret-free reset reason paired with `prefix_epoch`.
    pub prefix_reset_reason: Option<ModelContextResetReason>,
    /// Retain raw Responses protocol events alongside provider-neutral chunks.
    ///
    /// This is an internal compatibility-endpoint control, not an upstream
    /// request field. Agent/runtime calls leave it disabled to avoid cloning
    /// every SSE payload when only normalized chunks are needed.
    pub retain_protocol_events: bool,
}

/// Optional request-time controls for provider calls.
#[derive(Debug, Clone, Default)]
pub struct LLMRequestOptions {
    /// Session identifier used for request-scoped logging correlation.
    pub session_id: Option<String>,
    /// Override reasoning effort for this request.
    pub reasoning_effort: Option<ReasoningEffort>,
    /// Request provider-side parallel tool call planning when supported.
    ///
    /// - OpenAI/Copilot: maps to `parallel_tool_calls`
    /// - Anthropic: maps to `tool_choice.disable_parallel_tool_use` (inverse)
    pub parallel_tool_calls: Option<bool>,
    /// Require the model to issue this specific tool call when the provider
    /// supports request-level tool choice. Providers translate this to their
    /// native forced-function form; `None` preserves normal automatic choice.
    pub required_tool: Option<String>,
    /// Responses API specific overrides.
    pub responses: Option<ResponsesRequestOptions>,
    /// Purpose of this request for observability (e.g., "agent_loop", "task_evaluation").
    pub request_purpose: Option<String>,
    /// Provider-agnostic prompt-cache plan describing the stable, cacheable
    /// prefix of this request. Providers render it in their own dialect
    /// (Anthropic `cache_control`; GPT-5.6+ OpenAI Responses explicit content
    /// breakpoints; automatic caching for providers without explicit support).
    /// `None` means "no explicit cache hints".
    pub cache: Option<crate::cache::PromptCachePlan>,
}

/// Resolve a forced named-tool request and fail before network I/O when the
/// requested schema is not actually offered to the provider.
pub(crate) fn required_tool_from_options<'a>(
    options: Option<&'a LLMRequestOptions>,
    tools: &[ToolSchema],
) -> Result<Option<&'a str>> {
    let Some(name) = options
        .and_then(|options| options.required_tool.as_deref())
        .map(str::trim)
        .filter(|name| !name.is_empty())
    else {
        return Ok(None);
    };
    if tools.iter().any(|tool| tool.function.name == name) {
        Ok(Some(name))
    } else {
        Err(LLMError::Api(format!(
            "required tool schema '{name}' was not offered"
        )))
    }
}

/// Trait for LLM provider implementations
///
/// This trait defines the interface that all LLM providers must implement
/// to work with Bamboo's agent system. Providers handle communication with
/// specific LLM services (OpenAI, Anthropic, local models, etc.).
///
/// # Design Principle
///
/// The `model` parameter is **required** in `chat_stream`, not optional.
/// This ensures that the calling code explicitly specifies which model to use,
/// preventing accidental use of unintended models and making model selection
/// explicit and auditable.
///
/// # Example
///
/// ```ignore
/// use bamboo_agent::agent::llm::provider::LLMProvider;
///
/// async fn use_provider(provider: &dyn LLMProvider) {
///     let stream = provider.chat_stream(
///         &messages,
///         &tools,
///         Some(4096),
///         "claude-sonnet-4-6", // Model is required
///     ).await?;
/// }
/// ```
#[async_trait]
pub trait LLMProvider: Send + Sync {
    /// An immutable downstream handle through which this wrapper sends every
    /// chat request. This is separate from queue and allocation identity.
    ///
    /// Return `Some` only when every chat and IR method forwards the exact
    /// unchanged model to this same handle, or refuses locally before any
    /// dispatch, for the wrapper's entire lifetime. It must not replace the
    /// model, bypass the handle, or asynchronously change the destination.
    /// A mutable router or provider that can choose a different account must
    /// return `None`.
    /// Implementations are trusted in-process adapters: this is a behavior
    /// contract, not a security boundary against dishonest implementations.
    #[doc(hidden)]
    fn fixed_gold_policy_delegate(&self) -> Option<Arc<dyn LLMProvider>> {
        None
    }

    /// Return the fixed provider explicitly injected into a Host while it is
    /// still current. Mutable routers must never identify an inferred provider
    /// as an injection; the default preserves existing SDK implementations.
    #[doc(hidden)]
    fn legacy_injected_provider_snapshot(&self) -> Result<Option<Arc<dyn LLMProvider>>> {
        Ok(None)
    }

    /// An already-known local routing refusal, when no request may be sent.
    /// This query must be nonblocking and must not initiate a request.
    /// The default preserves existing providers and SDK implementations.
    /// Transparent provider wrappers should forward this to their inner handle.
    #[doc(hidden)]
    fn known_pre_dispatch_error(&self) -> Option<LLMError> {
        None
    }

    /// Whether this single-use target refused its request locally.
    /// This is for evaluation lifecycle classification, never accounting or
    /// authorization evidence. Implementations must not infer it from later state.
    #[doc(hidden)]
    fn local_dispatch_refused(&self) -> bool {
        false
    }

    /// Transparent Host decorators retain the original provider allocation's
    /// process-wide concurrency identity. This is never a model/client ID.
    fn resource_allocation_identity(&self) -> Option<usize> {
        None
    }

    /// True only for a Host route whose managed registry admitted the target.
    /// An opaque SDK provider defaults to retaining its original Arc. This
    /// cannot freeze credentials or other mutable state inside that provider;
    /// SDK owners must keep those stable or implement the snapshot hook.
    #[doc(hidden)]
    fn queue_requires_current_route(&self) -> bool {
        false
    }

    /// Underlying allocation used for pairing a delayed model and provider.
    /// Transparent decorators should forward this unchanged. This identity
    /// does not establish that dynamic credentials inside a provider are fixed.
    #[doc(hidden)]
    fn queued_route_identity(&self) -> QueuedRouteIdentity {
        QueuedRouteIdentity::Unmanaged
    }

    /// Freeze only transparent mutable handles for delayed dispatch. An SDK
    /// provider defaults to its existing Arc; it owns changes behind that Arc.
    #[doc(hidden)]
    fn queued_provider_snapshot(&self) -> Result<Option<Arc<dyn LLMProvider>>> {
        Ok(None)
    }

    /// Effective Vision support. Missing declarations default to enabled;
    /// only an explicit false disables it. Never infer from model names.
    async fn supports_vision(&self, model: &str) -> bool {
        self.vision_support_override(model).await.unwrap_or(true)
    }

    /// Explicit per-model policy, used to distinguish a user's override from
    /// their separately configured legacy image fallback. None is default-on.
    async fn vision_support_override(&self, _model: &str) -> Option<bool> {
        None
    }

    /// Select the provider's callable-catalog policy for one model request.
    ///
    /// Providers must opt in explicitly. The default preserves the complete
    /// legacy function catalog for compatibility endpoints and unknown models.
    async fn capability_loading_mode(
        &self,
        _model: &str,
        _required_tool: Option<&str>,
    ) -> CapabilityLoadingMode {
        CapabilityLoadingMode::LegacyFullCatalog
    }

    /// Lower the tool definitions visible to the model at this request.
    ///
    /// The default matches Bamboo's OpenAI-compatible Chat wire, which is also
    /// the legacy surface used by generic providers. Native adapters override
    /// this when their schema shape or deferred-loading protocol differs.
    async fn provider_visible_tool_footprint(
        &self,
        _ir: &PromptIR,
        tools: &[ToolSchema],
        _model: &str,
        _required_tool: Option<&str>,
    ) -> Result<ProviderVisibleToolFootprint> {
        if tools.is_empty() {
            return Ok(ProviderVisibleToolFootprint::default());
        }
        let projected = crate::providers::common::openai_compat::tools_to_openai_compat_json(tools);
        Ok(ProviderVisibleToolFootprint {
            segments: vec![ProviderVisibleToolSegment::from_serializable(
                ProviderVisibleToolSegmentKind::InitialFullDefinition,
                &projected,
            )?],
        })
    }

    /// Stream chat completion from the LLM
    ///
    /// This is the primary method for interacting with LLMs, returning
    /// a stream of response chunks that can be processed incrementally.
    ///
    /// # Arguments
    ///
    /// * `messages` - Conversation history and current prompt
    /// * `tools` - Available tools the LLM can call
    /// * `max_output_tokens` - Optional limit on response length
    /// * `model` - **Required** model identifier (e.g., "claude-sonnet-4-6")
    ///
    /// # Returns
    ///
    /// A stream of `LLMChunk` items containing partial responses
    ///
    /// # Errors
    ///
    /// Returns `LLMError` on network failures, API errors, or invalid requests
    async fn chat_stream(
        &self,
        messages: &[Message],
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
    ) -> Result<LLMStream>;

    /// Stream chat completion with optional request-level controls.
    ///
    /// Default implementation preserves backward compatibility by delegating to
    /// [`LLMProvider::chat_stream`].
    async fn chat_stream_with_options(
        &self,
        messages: &[Message],
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
        _options: Option<&LLMRequestOptions>,
    ) -> Result<LLMStream> {
        self.chat_stream(messages, tools, max_output_tokens, model)
            .await
    }

    /// Stream from the canonical [`PromptIR`] — the single, rich, provider-agnostic
    /// request the engine emits once per round.
    ///
    /// A provider renders the IR into its own wire format by calling the lowering
    /// methods ([`PromptIR::system_field`], [`PromptIR::body_chat`],
    /// [`PromptIR::responses_input`], [`PromptIR::continuation_delta`]). The IR
    /// carries the stateful Responses continuation, so an adapter derives the
    /// delta itself rather than the engine pre-baking it.
    ///
    /// The default implementation lowers the IR for BOTH wire families and
    /// delegates to [`chat_stream_with_options`](Self::chat_stream_with_options):
    /// - the flat message list (`continuation_delta` mid-tool-loop, else `flatten`)
    ///   for the Chat-Completions path;
    /// - the Responses-API view (`instructions` / `input_messages` /
    ///   `previous_response_id`) derived via [`PromptIR::responses_request_options`]
    ///   and merged onto the request POLICY, so a Responses provider works WITHOUT
    ///   overriding this method (Chat-Completions providers ignore those options).
    ///
    /// This is byte-identical to the pre-IR request. Block-native providers (e.g.
    /// Anthropic) still override this to consume `system_blocks` structurally.
    async fn chat_stream_ir(
        &self,
        ir: &PromptIR,
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
        options: Option<&LLMRequestOptions>,
    ) -> Result<LLMStream> {
        crate::image_budget::validate_tool_image_budget(ir.body_chat_iter())
            .map_err(LLMError::Api)?;
        let messages = if ir.continuation.is_some() {
            ir.continuation_delta()
        } else {
            ir.flatten()
        };
        let mut effective_options = options.cloned().unwrap_or_default();
        effective_options.responses =
            Some(ir.responses_request_options(effective_options.responses.as_ref()));
        self.chat_stream_with_options(
            &messages,
            tools,
            max_output_tokens,
            model,
            Some(&effective_options),
        )
        .await
    }

    /// Lists available models from this provider
    ///
    /// Returns a list of model identifiers that can be used with `chat_stream`.
    /// Default implementation returns an empty list.
    async fn list_models(&self) -> Result<Vec<String>> {
        // Default implementation returns empty list
        Ok(vec![])
    }

    /// Lists available models with optional token limit metadata.
    ///
    /// Default implementation preserves backward compatibility by adapting
    /// `list_models()` output into metadata entries without limits.
    async fn list_model_info(&self) -> Result<Vec<ProviderModelInfo>> {
        Ok(self
            .list_models()
            .await?
            .into_iter()
            .map(ProviderModelInfo::from_id)
            .collect())
    }
}

/// Produce a stable, process-local identity for a known wrapper's inner Arc.
#[doc(hidden)]
pub fn queued_identity_for(provider: &Arc<dyn LLMProvider>) -> QueuedRouteIdentity {
    match provider.queued_route_identity() {
        QueuedRouteIdentity::Unmanaged => QueuedRouteIdentity::Stable(provider.clone()),
        identity => identity,
    }
}

/// Resolve a transparent mutable wrapper once, retaining the original outer
/// Arc and its existing process-wide auxiliary-budget identity.
#[doc(hidden)]
pub fn queued_snapshot_for(provider: Arc<dyn LLMProvider>) -> Result<Arc<dyn LLMProvider>> {
    match provider.queued_provider_snapshot()? {
        Some(inner) => Ok(Arc::new(QueuedBudgetProvider {
            inner,
            require_current: provider.queue_requires_current_route(),
            original: provider,
            fixed_inner: false,
        })),
        None => Ok(provider),
    }
}

/// Mark only a route admitted from a Host-managed registry snapshot.
/// The original handle and its concurrency identity remain unchanged.
#[doc(hidden)]
pub fn mark_host_queued_route(provider: Arc<dyn LLMProvider>) -> Arc<dyn LLMProvider> {
    Arc::new(QueuedBudgetProvider {
        inner: provider.clone(),
        original: provider,
        require_current: true,
        fixed_inner: false,
    })
}

/// Retain the provider selected by a dispatch while using the original outer
/// provider's process-wide auxiliary semaphore identity. This function does
/// not prove origin or admission: callers must use an independent Host guard.
/// It freezes the selected Arc, not mutable state or credentials inside it.
#[doc(hidden)]
pub fn fixed_provider_with_identity(
    selected: Arc<dyn LLMProvider>,
    original: Arc<dyn LLMProvider>,
) -> Arc<dyn LLMProvider> {
    Arc::new(QueuedBudgetProvider {
        inner: selected,
        original,
        require_current: true,
        fixed_inner: true,
    })
}

/// Freeze the selected Arc for an explicitly injected provider while keeping
/// its own queue policy and the original outer semaphore identity. This is not
/// evidence of injection: the Host must have independently classified the
/// exact selected Arc as injected before using this helper.
#[doc(hidden)]
pub fn fixed_injected_provider_with_identity(
    selected: Arc<dyn LLMProvider>,
    original: Arc<dyn LLMProvider>,
) -> Arc<dyn LLMProvider> {
    Arc::new(QueuedBudgetProvider {
        inner: selected,
        original,
        require_current: false,
        fixed_inner: true,
    })
}

struct QueuedBudgetProvider {
    inner: Arc<dyn LLMProvider>,
    original: Arc<dyn LLMProvider>,
    require_current: bool,
    // A receipt-bound delegate must not later resnapshot a mutable wrapper.
    fixed_inner: bool,
}

#[async_trait]
impl LLMProvider for QueuedBudgetProvider {
    fn fixed_gold_policy_delegate(&self) -> Option<Arc<dyn LLMProvider>> {
        Some(self.inner.clone())
    }

    fn local_dispatch_refused(&self) -> bool {
        self.inner.local_dispatch_refused()
    }

    fn queue_requires_current_route(&self) -> bool {
        self.require_current || self.inner.queue_requires_current_route()
    }
    fn queued_provider_snapshot(&self) -> Result<Option<Arc<dyn LLMProvider>>> {
        if self.fixed_inner {
            return Ok(None);
        }
        let Some(inner) = self.inner.queued_provider_snapshot()? else {
            return Ok(None);
        };
        Ok(Some(Arc::new(Self {
            inner,
            original: self.original.clone(),
            require_current: self.require_current,
            fixed_inner: false,
        })))
    }
    fn queued_route_identity(&self) -> QueuedRouteIdentity {
        queued_identity_for(&self.inner)
    }
    fn known_pre_dispatch_error(&self) -> Option<LLMError> {
        self.inner.known_pre_dispatch_error()
    }
    fn resource_allocation_identity(&self) -> Option<usize> {
        Some(
            self.original
                .resource_allocation_identity()
                .unwrap_or(Arc::as_ptr(&self.original) as *const () as usize),
        )
    }
    async fn supports_vision(&self, model: &str) -> bool {
        self.inner.supports_vision(model).await
    }
    async fn vision_support_override(&self, model: &str) -> Option<bool> {
        self.inner.vision_support_override(model).await
    }
    async fn capability_loading_mode(
        &self,
        model: &str,
        required_tool: Option<&str>,
    ) -> CapabilityLoadingMode {
        self.inner
            .capability_loading_mode(model, required_tool)
            .await
    }
    async fn provider_visible_tool_footprint(
        &self,
        ir: &PromptIR,
        tools: &[ToolSchema],
        model: &str,
        required_tool: Option<&str>,
    ) -> Result<ProviderVisibleToolFootprint> {
        self.inner
            .provider_visible_tool_footprint(ir, tools, model, required_tool)
            .await
    }
    async fn chat_stream(
        &self,
        messages: &[Message],
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
    ) -> Result<LLMStream> {
        self.inner
            .chat_stream(messages, tools, max_output_tokens, model)
            .await
    }
    async fn chat_stream_with_options(
        &self,
        messages: &[Message],
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
        options: Option<&LLMRequestOptions>,
    ) -> Result<LLMStream> {
        self.inner
            .chat_stream_with_options(messages, tools, max_output_tokens, model, options)
            .await
    }
    async fn chat_stream_ir(
        &self,
        ir: &PromptIR,
        tools: &[ToolSchema],
        max_output_tokens: Option<u32>,
        model: &str,
        options: Option<&LLMRequestOptions>,
    ) -> Result<LLMStream> {
        self.inner
            .chat_stream_ir(ir, tools, max_output_tokens, model, options)
            .await
    }
    async fn list_models(&self) -> Result<Vec<String>> {
        self.inner.list_models().await
    }
    async fn list_model_info(&self) -> Result<Vec<ProviderModelInfo>> {
        self.inner.list_model_info().await
    }
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, Mutex};

    use async_trait::async_trait;
    use futures::{stream, StreamExt};

    use super::*;

    #[tokio::test]
    async fn chat_stream_ir_default_flattens_and_delegates() {
        use crate::prompt_ir::{PromptIR, Segment, SegmentRole};

        // A provider that captures the message list AND the options it is handed.
        #[derive(Default)]
        struct Capture {
            seen: Arc<Mutex<Vec<Message>>>,
            seen_responses: Arc<Mutex<Option<crate::provider::ResponsesRequestOptions>>>,
        }
        #[async_trait]
        impl LLMProvider for Capture {
            async fn chat_stream(
                &self,
                _m: &[Message],
                _t: &[ToolSchema],
                _mt: Option<u32>,
                _model: &str,
            ) -> Result<LLMStream> {
                unreachable!("default chat_stream_ir must route via chat_stream_with_options")
            }
            async fn chat_stream_with_options(
                &self,
                messages: &[Message],
                _t: &[ToolSchema],
                _mt: Option<u32>,
                _model: &str,
                o: Option<&LLMRequestOptions>,
            ) -> Result<LLMStream> {
                *self.seen.lock().expect("seen lock") = messages.to_vec();
                *self.seen_responses.lock().expect("resp lock") =
                    o.and_then(|value| value.responses.clone());
                Ok(Box::pin(stream::iter(Vec::<Result<LLMChunk>>::new())))
            }
        }

        let cap = Capture::default();
        assert_eq!(
            cap.capability_loading_mode("any-model", None).await,
            CapabilityLoadingMode::LegacyFullCatalog
        );
        let ir = PromptIR {
            system_text: "sys".into(),
            segments: vec![
                Segment::new(SegmentRole::StablePrefix, vec![Message::user("guide")]),
                Segment::new(SegmentRole::DynamicContext, vec![Message::user("dyn")]),
                Segment::new(SegmentRole::Conversation, vec![Message::user("ask")]),
            ],
            ..PromptIR::default()
        };
        let _ = cap
            .chat_stream_ir(&ir, &[], None, "m", None)
            .await
            .expect("ir stream");

        let seen = cap.seen.lock().expect("seen lock").clone();
        let expected = ir.flatten();
        assert_eq!(seen.len(), expected.len(), "delegates the flattened IR");
        for (got, want) in seen.iter().zip(expected.iter()) {
            assert_eq!(got.role, want.role);
            assert_eq!(got.content, want.content);
        }
        // system + guide + dyn + ask
        assert_eq!(seen.len(), 4);
        assert!(matches!(seen[0].role, bamboo_domain::Role::System));

        // SAFETY NET: the default also derives the Responses-API view from the IR, so
        // a Responses provider works without overriding `chat_stream_ir`. instructions
        // = the (trimmed) system field; input_messages = the full responses_input view
        // (system lifted out, so it does not lead with a system message).
        let responses = cap
            .seen_responses
            .lock()
            .expect("resp lock")
            .clone()
            .expect("default derives Responses options from the IR");
        assert_eq!(responses.instructions.as_deref(), Some("sys"));
        let input = responses.input_messages.expect("input_messages derived");
        assert_eq!(
            input.iter().map(|m| m.content.clone()).collect::<Vec<_>>(),
            vec!["guide".to_string(), "dyn".to_string(), "ask".to_string()],
            "input_messages is the responses_input view: NO leading system message"
        );
    }

    #[derive(Clone, Default)]
    struct RecordingProvider {
        requested_models: Arc<Mutex<Vec<String>>>,
        requested_max_tokens: Arc<Mutex<Vec<Option<u32>>>>,
    }

    #[tokio::test]
    async fn default_tool_footprint_is_one_compact_openai_compat_position() {
        let provider = RecordingProvider::default();
        let tools = vec![ToolSchema {
            schema_type: "function".to_string(),
            function: bamboo_domain::FunctionSchema {
                name: "lookup".to_string(),
                description: "Look up a value".to_string(),
                parameters: serde_json::json!({
                    "type": "object",
                    "properties": {"key": {"type": "string"}},
                    "oneOf": [{"required": ["key"]}]
                }),
            },
        }];

        let footprint = provider
            .provider_visible_tool_footprint(&PromptIR::default(), &tools, "model", None)
            .await
            .expect("footprint");

        assert_eq!(footprint.segments.len(), 1);
        assert_eq!(
            footprint.segments[0].kind,
            ProviderVisibleToolSegmentKind::InitialFullDefinition
        );
        let rendered: serde_json::Value =
            serde_json::from_str(&footprint.segments[0].serialized).unwrap();
        assert_eq!(
            footprint.segments[0].serialized,
            serde_json::to_string(&rendered).unwrap()
        );
        assert_eq!(rendered[0]["function"]["name"], "lookup");
        assert!(rendered[0]["function"]["parameters"].get("oneOf").is_none());

        assert_eq!(
            provider
                .provider_visible_tool_footprint(&PromptIR::default(), &[], "model", None)
                .await
                .unwrap(),
            ProviderVisibleToolFootprint::default()
        );
    }

    #[async_trait]
    impl LLMProvider for RecordingProvider {
        async fn chat_stream(
            &self,
            _messages: &[Message],
            _tools: &[ToolSchema],
            max_output_tokens: Option<u32>,
            model: &str,
        ) -> Result<LLMStream> {
            if let Ok(mut models) = self.requested_models.lock() {
                models.push(model.to_string());
            }
            if let Ok(mut max_tokens) = self.requested_max_tokens.lock() {
                max_tokens.push(max_output_tokens);
            }

            Ok(Box::pin(stream::empty()))
        }
    }

    #[tokio::test]
    async fn main_dispatch_scope_is_attempt_local_and_not_inherited_by_spawned_tasks() {
        let a: Arc<dyn LLMProvider> = Arc::new(RecordingProvider::default());
        let b: Arc<dyn LLMProvider> = Arc::new(RecordingProvider::default());
        let outer_seen = Arc::new(Mutex::new(Vec::<Arc<dyn LLMProvider>>::new()));
        let inner_seen = Arc::new(Mutex::new(Vec::<Arc<dyn LLMProvider>>::new()));
        let outer_copy = outer_seen.clone();
        let inner_copy = inner_seen.clone();
        let outer: MainDispatchObserver =
            Arc::new(move |provider| outer_copy.lock().unwrap().push(provider));
        let inner: MainDispatchObserver =
            Arc::new(move |provider| inner_copy.lock().unwrap().push(provider));

        assert!(!observe_main_dispatch(a.clone()));
        scope_main_dispatch(outer, async {
            assert!(observe_main_dispatch(a.clone()));
            let spawned_b = b.clone();
            assert!(
                !tokio::spawn(async move { observe_main_dispatch(spawned_b) })
                    .await
                    .unwrap(),
                "a new task must not silently inherit an attempt receipt"
            );
            scope_main_dispatch(inner, async {
                assert!(observe_main_dispatch(b.clone()));
            })
            .await;
            assert!(observe_main_dispatch(a.clone()), "outer scope is restored");
        })
        .await;
        assert!(
            !observe_main_dispatch(b.clone()),
            "scope must not leak after completion"
        );
        let outer = outer_seen.lock().unwrap();
        assert_eq!(outer.len(), 2);
        assert!(outer.iter().all(|provider| Arc::ptr_eq(provider, &a)));
        let inner = inner_seen.lock().unwrap();
        assert_eq!(inner.len(), 1);
        assert!(Arc::ptr_eq(&inner[0], &b));
    }

    #[tokio::test]
    async fn cancelling_scoped_main_attempt_does_not_install_a_later_observer() {
        let selected: Arc<dyn LLMProvider> = Arc::new(RecordingProvider::default());
        let observed = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let observed_copy = observed.clone();
        let observer: MainDispatchObserver = Arc::new(move |_| {
            observed_copy.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        });
        let (started, ready) = tokio::sync::oneshot::channel();
        let run = tokio::spawn(scope_main_dispatch(observer, async move {
            started.send(()).unwrap();
            std::future::pending::<()>().await;
        }));
        ready.await.unwrap();
        run.abort();
        assert!(run.await.unwrap_err().is_cancelled());
        assert!(!observe_main_dispatch(selected));
        assert_eq!(observed.load(std::sync::atomic::Ordering::SeqCst), 0);
    }

    struct ResnapshottingProvider {
        alternate: Arc<dyn LLMProvider>,
        calls: std::sync::atomic::AtomicUsize,
        require_current: bool,
    }

    #[async_trait]
    impl LLMProvider for ResnapshottingProvider {
        fn queue_requires_current_route(&self) -> bool {
            self.require_current
        }

        fn queued_provider_snapshot(&self) -> Result<Option<Arc<dyn LLMProvider>>> {
            Ok(Some(self.alternate.clone()))
        }

        async fn chat_stream(
            &self,
            _: &[Message],
            _: &[ToolSchema],
            _: Option<u32>,
            _: &str,
        ) -> Result<LLMStream> {
            self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            Ok(Box::pin(stream::empty()))
        }
    }

    #[tokio::test]
    async fn fixed_dispatch_delegate_keeps_selected_arc_and_outer_budget_identity() {
        let b = Arc::new(RecordingProvider::default());
        let a = Arc::new(ResnapshottingProvider {
            alternate: b.clone(),
            calls: std::sync::atomic::AtomicUsize::new(0),
            require_current: false,
        });
        let selected: Arc<dyn LLMProvider> = a.clone();
        let original: Arc<dyn LLMProvider> = Arc::new(RecordingProvider::default());
        let expected_identity = Arc::as_ptr(&original) as *const () as usize;
        let fixed = fixed_provider_with_identity(selected, original);
        assert_eq!(
            fixed.resource_allocation_identity(),
            Some(expected_identity)
        );
        assert!(fixed.queue_requires_current_route());
        let queued = queued_snapshot_for(fixed.clone()).unwrap();
        assert!(
            Arc::ptr_eq(&queued, &fixed),
            "receipt-bound Arc must not be resnapshotted"
        );
        let _ = queued.chat_stream(&[], &[], None, "gold").await.unwrap();
        assert_eq!(a.calls.load(std::sync::atomic::Ordering::SeqCst), 1);
        assert!(b.requested_models.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn injected_fixed_queue_keeps_a_when_current_selection_becomes_b() {
        let a = Arc::new(RecordingProvider::default());
        let b = Arc::new(RecordingProvider::default());
        let original: Arc<dyn LLMProvider> = Arc::new(RecordingProvider::default());
        let expected_identity = Arc::as_ptr(&original) as *const () as usize;
        let queued = fixed_injected_provider_with_identity(a.clone(), original.clone());
        let current = fixed_injected_provider_with_identity(b.clone(), original.clone());
        assert!(!queued.queue_requires_current_route());
        assert!(!current.queue_requires_current_route());
        assert_eq!(
            queued.resource_allocation_identity(),
            Some(expected_identity)
        );
        assert_eq!(
            current.resource_allocation_identity(),
            Some(expected_identity)
        );
        let captured = queued_snapshot_for(queued.clone()).unwrap();
        assert!(Arc::ptr_eq(&captured, &queued));
        let _ = captured.chat_stream(&[], &[], None, "gold").await.unwrap();
        assert_eq!(
            *a.requested_models.lock().unwrap(),
            vec!["gold".to_string()]
        );
        assert!(b.requested_models.lock().unwrap().is_empty());

        let guarded_inner: Arc<dyn LLMProvider> = Arc::new(ResnapshottingProvider {
            alternate: b,
            calls: std::sync::atomic::AtomicUsize::new(0),
            require_current: true,
        });
        let guarded = fixed_injected_provider_with_identity(guarded_inner, original);
        assert!(
            guarded.queue_requires_current_route(),
            "the selected provider's own policy remains authoritative"
        );
    }

    #[tokio::test]
    async fn chat_stream_with_options_delegates_to_chat_stream_with_same_model_and_tokens() {
        let provider = RecordingProvider::default();
        let options = LLMRequestOptions::default();

        let mut stream = provider
            .chat_stream_with_options(&[], &[], Some(512), "gpt-test", Some(&options))
            .await
            .expect("delegation should succeed");
        assert!(stream.next().await.is_none());

        assert_eq!(
            provider
                .requested_models
                .lock()
                .expect("lock poisoned")
                .as_slice(),
            ["gpt-test"]
        );
        assert_eq!(
            provider
                .requested_max_tokens
                .lock()
                .expect("lock poisoned")
                .as_slice(),
            [Some(512)]
        );
    }

    #[tokio::test]
    async fn list_models_returns_empty_by_default() {
        let provider = RecordingProvider::default();
        let models = provider
            .list_models()
            .await
            .expect("default list_models should succeed");
        assert!(models.is_empty());
    }

    #[test]
    fn request_options_default_has_no_purpose() {
        let opts = LLMRequestOptions::default();
        assert!(opts.request_purpose.is_none());
    }

    #[test]
    fn request_options_purpose_is_set_and_readable() {
        let opts = LLMRequestOptions {
            request_purpose: Some("title_generation".to_string()),
            ..Default::default()
        };
        assert_eq!(opts.request_purpose.as_deref(), Some("title_generation"));
    }
}