harn_vm/llm/capabilities/

model.rs

//! Capability DTOs and the wire-dialect model.
//!
//! Pure data types: the on-disk [`CapabilitiesFile`] schema, per-provider
//! [`ProviderDefaults`], the resolved [`Capabilities`] struct callers consume,
//! and the [`WireDialect`] enum that types a route's message wire format. The
//! `ProviderRule` matrix row and the resolution engine that turns these DTOs
//! into a `Capabilities` live in `super::rule`.

use std::collections::BTreeMap;

use serde::Deserialize;

use super::rule::ProviderRule;

/// Parsed on-disk capabilities schema. Public so harn-cli can
/// construct one directly when wiring harn.toml overrides.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct CapabilitiesFile {
    /// Per-provider ordered rule lists. The first matching rule wins; a
    /// matching rule with `extends = true` contributes only the fields it
    /// sets and lets resolution continue to later matching rules (see
    /// [`ProviderRule::extends`]).
    #[serde(default)]
    pub provider: BTreeMap<String, Vec<ProviderRule>>,
    /// Per-provider defaults applied to every matching row and to
    /// provider/model pairs that have no model-specific row. This keeps
    /// transport-shape facts in data without repeating them on every
    /// generation-specific capability row.
    #[serde(default)]
    pub provider_defaults: BTreeMap<String, ProviderDefaults>,
    /// Sibling → canonical family mapping. Providers with no rule of
    /// their own fall through to the named family (recursively).
    #[serde(default)]
    pub provider_family: BTreeMap<String, String>,
    /// Per-provider adaptive rate/concurrency governor limits, keyed by
    /// provider id. Consumed by `crate::llm::rate_governor` when the
    /// `llm.rate_governor` flag is enabled, so provider limits stay catalog
    /// data instead of call-site branches.
    #[serde(default)]
    pub provider_limits: BTreeMap<String, ProviderLimits>,
}

/// Adaptive-governor limits for one provider. Every field is optional so a
/// catalog fragment can pin just the axes it knows; unset axes fall back to the
/// governor's conservative built-in defaults.
#[derive(Debug, Clone, Deserialize, Default, PartialEq)]
pub struct ProviderLimits {
    /// Ceiling the AIMD concurrency limiter additively climbs toward on
    /// sustained success.
    #[serde(default)]
    pub max_concurrency: Option<u32>,
    /// Floor the AIMD limiter multiplicatively decreases toward on a throttle
    /// signal.
    #[serde(default)]
    pub min_concurrency: Option<u32>,
    /// Requests-per-minute token bucket. `None` disables the RPM bucket.
    #[serde(default)]
    pub rpm: Option<u32>,
    /// Tokens-per-minute token bucket, charged by estimated input + output
    /// tokens. `None` disables the TPM bucket.
    #[serde(default)]
    pub tpm: Option<u64>,
    /// Whether the AIMD adaptive concurrency loop is active. When `false`, the
    /// concurrency limit is pinned at `max_concurrency`.
    #[serde(default)]
    pub adaptive: Option<bool>,
    /// Circuit-breaker / backoff parameters. Absent means built-in defaults.
    #[serde(default)]
    pub backoff: Option<GovernorBackoff>,
}

/// Exponential-backoff-with-jitter parameters for the governor circuit breaker.
/// Provider `Retry-After` values always take precedence over the computed
/// window.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct GovernorBackoff {
    /// First OPEN window, in milliseconds.
    #[serde(default)]
    pub base_ms: Option<u64>,
    /// Ceiling for the OPEN window, in milliseconds.
    #[serde(default)]
    pub max_ms: Option<u64>,
    /// Growth factor applied per consecutive OPEN cycle.
    #[serde(default)]
    pub multiplier: Option<f64>,
    /// Full-jitter toggle.
    #[serde(default)]
    pub jitter: Option<bool>,
}

/// Provider-wide default fields merged into matching rules.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct ProviderDefaults {
    /// Message/request/response wire format used by shared helpers.
    /// Known values are `openai`, `anthropic`, `gemini`, and `ollama`.
    #[serde(default)]
    pub message_wire_format: Option<String>,
    /// Which synchronous endpoint family the dialect's routes dispatch to.
    /// See [`LiveEndpointFamily`].
    #[serde(default)]
    pub live_endpoint_family: Option<LiveEndpointFamily>,
    /// Native tool definition wire shape. Known values are `openai`
    /// and `anthropic`.
    #[serde(default)]
    pub native_tool_wire_format: Option<String>,
    /// Whether image content blocks may reference remote URLs.
    #[serde(default)]
    pub image_url_input_supported: Option<bool>,
    /// File-upload transport used by `std/files.upload`. Known values
    /// are `anthropic` and `gemini`.
    #[serde(default)]
    pub file_upload_wire_format: Option<String>,
    /// Provider-specific reasoning request shape for OpenAI-compatible
    /// transports. Known values are `openrouter` and `enabled`.
    #[serde(default)]
    pub reasoning_wire_format: Option<String>,
    #[serde(default)]
    pub files_api_supported: Option<bool>,
    #[serde(default)]
    pub batch_api: Option<bool>,
    #[serde(default)]
    pub batch_wire_format: Option<String>,
    #[serde(default)]
    pub batch_input_mode: Option<String>,
    #[serde(default)]
    pub batch_discount_percent: Option<u32>,
    #[serde(default)]
    pub batch_turnaround_hours: Option<u32>,
    #[serde(default)]
    pub batch_max_requests: Option<u64>,
    #[serde(default)]
    pub batch_max_input_bytes: Option<u64>,
    #[serde(default)]
    pub batch_result_retention_days: Option<u32>,
    #[serde(default)]
    pub batch_result_ordering: Option<String>,
    #[serde(default)]
    pub batch_partial_failure: Option<String>,
    #[serde(default)]
    pub batch_cancellation: Option<String>,
    #[serde(default)]
    pub batch_security_notes: Option<Vec<String>>,
    #[serde(default)]
    pub batch_operational_notes: Option<Vec<String>>,
    /// Regions where the provider/model batch route is explicitly supported.
    /// Empty means the capability is not region-scoped.
    #[serde(default)]
    pub batch_regions: Option<Vec<String>>,
    /// Explicit prompt-cache TTL values this provider can honor on request.
    /// Empty means the route may cache, but Harn has no explicit TTL knob for
    /// it. Known values today: `5m`, `1h`.
    #[serde(default)]
    pub prompt_cache_ttls: Option<Vec<String>>,
    /// Shortest prefix this provider will actually cache, in tokens. See
    /// [`crate::llm::capabilities::rule::ProviderRule::prompt_cache_min_prefix_tokens`].
    #[serde(default)]
    pub prompt_cache_min_prefix_tokens: Option<u32>,
    /// Request-side cache marker placement shared by every adapter for this
    /// provider. Unknown values fail capability loading.
    #[serde(default)]
    pub cache_breakpoint_style: Option<CacheBreakpointStyle>,
    /// How prior assistant reasoning may be projected back onto the provider
    /// wire. The privacy-preserving default is `strip`.
    #[serde(default)]
    pub reasoning_round_trip: Option<ReasoningRoundTripPolicy>,
    #[serde(default)]
    pub seed_supported: Option<bool>,
    #[serde(default)]
    pub top_k_supported: Option<bool>,
    #[serde(default)]
    pub temperature_supported: Option<bool>,
    #[serde(default)]
    pub top_p_supported: Option<bool>,
    #[serde(default)]
    pub frequency_penalty_supported: Option<bool>,
    #[serde(default)]
    pub presence_penalty_supported: Option<bool>,
    #[serde(default)]
    pub stop_supported: Option<bool>,
}

/// Copies `src` into `dst` when `src` is set (last-writer-wins overlay).
pub(super) fn overlay_opt<T: Clone>(dst: &mut Option<T>, src: &Option<T>) {
    if src.is_some() {
        dst.clone_from(src);
    }
}

/// Copies `src` into `dst` only when `dst` is still unset (fill-the-gaps).
pub(super) fn fill_opt<T: Clone>(dst: &mut Option<T>, src: &Option<T>) {
    if dst.is_none() {
        dst.clone_from(src);
    }
}

/// Visits every `ProviderDefaults` field once, applying `$op` (`overlay_opt`
/// or `fill_opt`) to each `(dst, src)` pair. The field roster lives here only;
/// `overlay`/`fill_missing_from` differ solely in the merge rule they pass.
macro_rules! merge_provider_defaults {
    ($dst:expr, $src:expr, $op:path) => {{
        $op(&mut $dst.message_wire_format, &$src.message_wire_format);
        $op(&mut $dst.live_endpoint_family, &$src.live_endpoint_family);
        $op(
            &mut $dst.native_tool_wire_format,
            &$src.native_tool_wire_format,
        );
        $op(
            &mut $dst.image_url_input_supported,
            &$src.image_url_input_supported,
        );
        $op(
            &mut $dst.file_upload_wire_format,
            &$src.file_upload_wire_format,
        );
        $op(&mut $dst.reasoning_wire_format, &$src.reasoning_wire_format);
        $op(&mut $dst.files_api_supported, &$src.files_api_supported);
        $op(&mut $dst.batch_api, &$src.batch_api);
        $op(&mut $dst.batch_wire_format, &$src.batch_wire_format);
        $op(&mut $dst.batch_input_mode, &$src.batch_input_mode);
        $op(
            &mut $dst.batch_discount_percent,
            &$src.batch_discount_percent,
        );
        $op(
            &mut $dst.batch_turnaround_hours,
            &$src.batch_turnaround_hours,
        );
        $op(&mut $dst.batch_max_requests, &$src.batch_max_requests);
        $op(&mut $dst.batch_max_input_bytes, &$src.batch_max_input_bytes);
        $op(
            &mut $dst.batch_result_retention_days,
            &$src.batch_result_retention_days,
        );
        $op(&mut $dst.batch_result_ordering, &$src.batch_result_ordering);
        $op(&mut $dst.batch_partial_failure, &$src.batch_partial_failure);
        $op(&mut $dst.batch_cancellation, &$src.batch_cancellation);
        $op(&mut $dst.batch_security_notes, &$src.batch_security_notes);
        $op(
            &mut $dst.batch_operational_notes,
            &$src.batch_operational_notes,
        );
        $op(&mut $dst.batch_regions, &$src.batch_regions);
        $op(&mut $dst.prompt_cache_ttls, &$src.prompt_cache_ttls);
        $op(
            &mut $dst.prompt_cache_min_prefix_tokens,
            &$src.prompt_cache_min_prefix_tokens,
        );
        $op(
            &mut $dst.cache_breakpoint_style,
            &$src.cache_breakpoint_style,
        );
        $op(&mut $dst.reasoning_round_trip, &$src.reasoning_round_trip);
        $op(&mut $dst.seed_supported, &$src.seed_supported);
        $op(&mut $dst.top_k_supported, &$src.top_k_supported);
        $op(&mut $dst.temperature_supported, &$src.temperature_supported);
        $op(&mut $dst.top_p_supported, &$src.top_p_supported);
        $op(
            &mut $dst.frequency_penalty_supported,
            &$src.frequency_penalty_supported,
        );
        $op(
            &mut $dst.presence_penalty_supported,
            &$src.presence_penalty_supported,
        );
        $op(&mut $dst.stop_supported, &$src.stop_supported);
    }};
}

impl ProviderDefaults {
    pub(super) fn overlay(&mut self, other: &ProviderDefaults) {
        merge_provider_defaults!(self, other, overlay_opt);
    }

    pub(super) fn fill_missing_from(&mut self, other: &ProviderDefaults) {
        merge_provider_defaults!(self, other, fill_opt);
    }

    pub(super) fn has_any_field(&self) -> bool {
        self.message_wire_format.is_some()
            || self.live_endpoint_family.is_some()
            || self.native_tool_wire_format.is_some()
            || self.image_url_input_supported.is_some()
            || self.file_upload_wire_format.is_some()
            || self.reasoning_wire_format.is_some()
            || self.files_api_supported.is_some()
            || self.batch_api.is_some()
            || self.batch_wire_format.is_some()
            || self.batch_input_mode.is_some()
            || self.batch_discount_percent.is_some()
            || self.batch_turnaround_hours.is_some()
            || self.batch_max_requests.is_some()
            || self.batch_max_input_bytes.is_some()
            || self.batch_result_retention_days.is_some()
            || self.batch_result_ordering.is_some()
            || self.batch_partial_failure.is_some()
            || self.batch_cancellation.is_some()
            || self.batch_security_notes.is_some()
            || self.batch_operational_notes.is_some()
            || self.batch_regions.is_some()
            || self.prompt_cache_ttls.is_some()
            || self.prompt_cache_min_prefix_tokens.is_some()
            || self.cache_breakpoint_style.is_some()
            || self.reasoning_round_trip.is_some()
            || self.seed_supported.is_some()
            || self.top_k_supported.is_some()
            || self.temperature_supported.is_some()
            || self.top_p_supported.is_some()
            || self.frequency_penalty_supported.is_some()
            || self.presence_penalty_supported.is_some()
            || self.stop_supported.is_some()
    }
}

/// The message/request/response wire dialect a route speaks.
///
/// This is the single typed representation of what used to be encoded two
/// different, drift-prone ways: the stringly `Capabilities.message_wire_format`
/// field (compared against `"anthropic"`/`"gemini"`/`"ollama"` literals at a
/// dozen call sites) and the `(is_anthropic_style, is_ollama)` boolean pair
/// threaded independently through the transport/response layers. A closed enum
/// makes an unhandled or mistyped dialect a compile error and removes the
/// boolean-blindness where two `bool`s could silently disagree.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WireDialect {
    /// Anthropic native Messages API (`/v1/messages`). The only dialect that
    /// surfaces Claude's extended-thinking stream. `message_wire_format =
    /// "anthropic"`.
    Anthropic,
    /// OpenAI-compatible Chat Completions (`/v1/chat/completions`). The default
    /// for hosted/openai-shape routes. `message_wire_format = "openai"`.
    OpenAiCompat,
    /// Ollama native `/api/chat`. `message_wire_format = "ollama"`.
    Ollama,
    /// Google Gemini `generateContent`. `message_wire_format = "gemini"`.
    Gemini,
}

impl WireDialect {
    /// Parse the catalog's `message_wire_format` string. Unrecognized values
    /// (including the explicit `"openai"`) resolve to [`WireDialect::OpenAiCompat`],
    /// exactly matching the pre-cutover behavior where every
    /// `== "anthropic"/"gemini"/"ollama"` check fell through to the
    /// OpenAI-compatible path.
    pub fn from_message_wire_format(value: &str) -> WireDialect {
        match value {
            "anthropic" => WireDialect::Anthropic,
            "ollama" => WireDialect::Ollama,
            "gemini" => WireDialect::Gemini,
            _ => WireDialect::OpenAiCompat,
        }
    }

    /// The canonical `message_wire_format` string for display and round-trip.
    pub fn as_str(self) -> &'static str {
        match self {
            WireDialect::Anthropic => "anthropic",
            WireDialect::OpenAiCompat => "openai",
            WireDialect::Ollama => "ollama",
            WireDialect::Gemini => "gemini",
        }
    }

    /// Whether this route speaks Anthropic's native Messages shape.
    pub fn is_anthropic(self) -> bool {
        matches!(self, WireDialect::Anthropic)
    }

    /// Whether this route speaks Ollama's native `/api/chat` shape.
    pub fn is_ollama(self) -> bool {
        matches!(self, WireDialect::Ollama)
    }

    /// Whether this route speaks Google Gemini's `generateContent` shape.
    pub fn is_gemini(self) -> bool {
        matches!(self, WireDialect::Gemini)
    }
}

/// Which synchronous ("live") endpoint family a route dispatches to.
///
/// [`WireDialect`] answers "what does the JSON look like"; most dialects have
/// exactly one live endpoint, so the two questions collapse. Gemini is the
/// exception: Google serves the same models over two incompatible synchronous
/// shapes, so a second axis is needed to say *which* one a route uses.
///
/// This axis is deliberately independent of `batch_wire_format`. Gemini Batch
/// only accepts `generateContent`-shaped bodies, so a route can select
/// [`LiveEndpointFamily::GeminiInteractions`] for its live traffic while its
/// batch submissions stay `batch_wire_format = "gemini"`.
///
/// It is also deliberately independent of the advisory `recommended_endpoint`
/// string: this is the value the runtime actually switches on, so it is typed
/// and an unknown value in a capability source fails the load instead of
/// silently falling back to the legacy transport.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LiveEndpointFamily {
    /// Google Gemini `POST /v1beta/models/{model}:generateContent`. The legacy
    /// path, still the only shape Gemini Batch accepts and the only one Vertex
    /// delegates to.
    GeminiGenerateContent,
    /// Google Gemini `POST /v1beta/interactions` (GA June 2026). Adds
    /// server-side conversation state (`previous_interaction_id`), observable
    /// execution steps, streaming, and background execution.
    GeminiInteractions,
}

impl LiveEndpointFamily {
    /// The canonical capability-source string for display and round-trip.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::GeminiGenerateContent => "gemini_generate_content",
            Self::GeminiInteractions => "gemini_interactions",
        }
    }

    /// Whether this endpoint family keeps conversation state on the provider,
    /// making the `previous_response_id` / `store` / `background` options
    /// meaningful on the route.
    pub const fn is_stateful(self) -> bool {
        matches!(self, Self::GeminiInteractions)
    }

    /// Whether this route dispatches over Gemini's Interactions transport.
    pub const fn is_gemini_interactions(self) -> bool {
        matches!(self, Self::GeminiInteractions)
    }
}

/// How the neutral `computer` tool projects onto a route's native computer-use
/// surface (the `computer_use_style` capability). A typed enum rather than a raw
/// string so an unknown value in a capability source is a load-time
/// deserialize error instead of a silently-disabled computer tool.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ComputerUseStyle {
    /// Anthropic `computer_20251124` native tool.
    NativeAnthropic,
    /// OpenAI Responses `computer` native tool.
    NativeOpenai,
    /// Accessibility / set-of-marks grounding over the universal function tool.
    Grounded,
    /// The plain function-schema `computer` tool (the universal default).
    Function,
}

/// Screenshot downscaling policy applied before an image reaches the model (the
/// `screenshot_scaling` capability). Typed for the same reason as
/// [`ComputerUseStyle`] — an unknown value fails the capability load loudly.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ScreenshotScaling {
    /// Fit within Anthropic's XGA (1024x768), preserving aspect ratio.
    Xga,
    /// Send the capture at its native resolution (OpenAI et al.).
    Original,
}

/// How a route carries a `system`/`developer`-role message that appears at a
/// non-leading position in the conversation — the operator-instruction channel
/// (OpenAI developer messages, Anthropic mid-conversation system messages).
/// Leading system content is always the system prompt; this governs only the
/// *interleaved* case. Typed so an unknown value in a capability
/// source fails the load loudly. `None` on [`Capabilities`] derives a safe
/// default from the wire dialect — see
/// [`resolve_system_message_placement`](super::resolve_system_message_placement).
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SystemMessagePlacement {
    /// The wire API accepts a `system`/`developer` message verbatim at any
    /// position (OpenAI Chat Completions & Responses, Ollama). Pass through.
    Inline,
    /// The API accepts an interleaved `system`-role directive but enforces
    /// placement rules (Anthropic Opus 4.8: one message must follow a `user`
    /// turn — or an assistant turn ending in `server_tool_use` — and be the
    /// last message or be followed by an `assistant` turn; never
    /// `messages[0]`). A valid consecutive section is merged and kept native;
    /// anything else folds. `developer` collapses to `system` (Anthropic has no
    /// developer role).
    NativeDirective,
    /// The API has no positional system channel (Anthropic pre-4.8, Gemini
    /// `systemInstruction`, Bedrock Converse `system[]`). A leading run folds
    /// into the top-level system prompt; an interleaved directive folds into
    /// the adjacent user turn as a `<system-reminder>` block so its position
    /// and operator intent survive. Never 400s, never silently repositioned to
    /// the global system prompt.
    Fold,
}

/// Provider field that must carry Harn's private reasoning from an assistant
/// turn into that provider's next request.
///
/// This is deliberately an enum, rather than an arbitrary catalog string:
/// replaying private reasoning changes the provider-visible transcript, so an
/// unknown field must fail capability loading rather than silently leak or
/// discard it. The durable Harn transcript keeps this as `reasoning`; the
/// OpenAI-compatible request boundary projects it only for the selected mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReasoningHistoryWireField {
    /// Moonshot's OpenAI-compatible API requires this on the prior assistant
    /// message before matching tool results.
    ReasoningContent,
}

/// Placement of a provider prompt-cache breakpoint.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CacheBreakpointStyle {
    /// The route has no explicit request marker.
    #[default]
    None,
    /// Put `cache_control` on the request object.
    TopLevel,
    /// Put `cache_control` on the final message content block.
    LastBlock,
}

impl CacheBreakpointStyle {
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::TopLevel => "top_level",
            Self::LastBlock => "last_block",
        }
    }
}

/// Provider-visible replay policy for private assistant reasoning.
///
/// Reasoning is stripped unless a capability row explicitly opts into the
/// provider's cryptographically bound or same-field continuation contract.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReasoningRoundTripPolicy {
    /// Never send private reasoning back to the provider.
    #[default]
    Strip,
    /// Replay only provider-signed opaque reasoning blocks.
    EchoSigned,
    /// Replay Harn's canonical reasoning text under the typed provider field.
    EchoSameKey,
}

impl ReasoningRoundTripPolicy {
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Strip => "strip",
            Self::EchoSigned => "echo_signed",
            Self::EchoSameKey => "echo_same_key",
        }
    }
}

impl ReasoningHistoryWireField {
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::ReasoningContent => "reasoning_content",
        }
    }
}

/// Where a route's `tool_mode_parity` verdict came from.
///
/// Both variants are declarations about a route, not measurements of one. A
/// forced-format sweep is a different kind of evidence and has its own slot,
/// `tool_support.empirical_parity`, carrying pass rates and a sample size.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolModeParitySource {
    /// A capability row states the verdict outright.
    Declared,
    /// No row stated one, so it was computed from `native_tools` and
    /// `text_tool_wire_format_supported`. A consumer that needs evidence
    /// should treat this as "not established" rather than as a finding.
    Derived,
}

impl ToolModeParitySource {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Declared => "declared",
            Self::Derived => "derived",
        }
    }
}

/// Resolved capabilities for a `(provider, model)` pair. Unset rule
/// fields resolve to `false` / empty / `None` so callers never have to
/// unwrap an `Option<bool>` for what are really boolean gates.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Capabilities {
    pub native_tools: bool,
    pub message_wire_format: WireDialect,
    pub native_tool_wire_format: String,
    pub defer_loading: bool,
    pub tool_search: Vec<String>,
    pub responses_api: bool,
    pub hosted_tools: Vec<String>,
    pub remote_mcp: bool,
    pub conversation_state: bool,
    pub compaction: bool,
    pub background_mode: bool,
    pub batch_api: bool,
    pub batch_wire_format: Option<String>,
    pub batch_input_mode: Option<String>,
    pub batch_discount_percent: Option<u32>,
    pub batch_turnaround_hours: Option<u32>,
    pub batch_max_requests: Option<u64>,
    pub batch_max_input_bytes: Option<u64>,
    pub batch_result_retention_days: Option<u32>,
    pub batch_result_ordering: Option<String>,
    pub batch_partial_failure: Option<String>,
    pub batch_cancellation: Option<String>,
    pub batch_security_notes: Vec<String>,
    pub batch_operational_notes: Vec<String>,
    pub batch_regions: Vec<String>,
    pub tool_approval_policy: Option<String>,
    pub max_tools: Option<u32>,
    pub prompt_caching: bool,
    pub prompt_cache_ttls: Vec<String>,
    /// Shortest prefix this route will actually cache, in tokens. `None` means
    /// the route has no model-specific floor and the wire-dialect default in
    /// [`crate::llm::cache_conformance::CacheControlProfile`] applies.
    pub prompt_cache_min_prefix_tokens: Option<u32>,
    pub cache_breakpoint_style: CacheBreakpointStyle,
    pub vision: bool,
    pub audio: bool,
    pub pdf: bool,
    pub video: bool,
    pub files_api_supported: bool,
    pub file_upload_wire_format: Option<String>,
    pub structured_output: Option<String>,
    /// Legacy mirror for CLI display and older callers.
    pub json_schema: Option<String>,
    pub prefers_xml_scaffolding: bool,
    /// See [`ProviderRule::reserved_tool_call_token`].
    pub reserved_tool_call_token: bool,
    pub prefers_markdown_scaffolding: bool,
    pub structured_output_mode: String,
    pub supports_assistant_prefill: bool,
    pub prefers_role_developer: bool,
    pub prefers_xml_tools: bool,
    pub thinking_block_style: String,
    /// Which synchronous ("live") endpoint family this route dispatches to,
    /// when its wire dialect serves more than one. `None` means the dialect has
    /// exactly one live endpoint, so there is nothing to select. See
    /// [`LiveEndpointFamily`].
    pub live_endpoint_family: Option<LiveEndpointFamily>,
    /// Whether this route emits its reasoning INLINE in the text channel as
    /// `<think>...</think>` blocks (local Ollama/llama.cpp reasoning models,
    /// Qwen3 via vLLM, Kimi) rather than in a separate provider reasoning
    /// field. When true, the `llm_call` envelope builder splits those blocks
    /// out of `text`/`prose`/`visible_text` and folds them into the reasoning
    /// channel, mirroring how hosted providers surface a dedicated thinking
    /// field. Derived from `thinking_block_style == "inline"` — the same
    /// population that represents reasoning as inline `<think>` in prompt
    /// context is the one that emits it that way in responses.
    pub emits_inline_reasoning: bool,
    pub thinking_modes: Vec<String>,
    pub interleaved_thinking_supported: bool,
    pub anthropic_beta_features: Vec<String>,
    pub vision_supported: bool,
    pub image_url_input_supported: bool,
    pub preserve_thinking: bool,
    /// Typed provider-visible reasoning replay policy. Defaults to strip.
    pub reasoning_round_trip: ReasoningRoundTripPolicy,
    /// Provider-specific wire field used to replay Harn's private reasoning
    /// on the preceding assistant turn. `None` preserves the privacy default:
    /// reasoning is never sent back to an OpenAI-compatible provider.
    pub reasoning_history_wire_field: Option<ReasoningHistoryWireField>,
    pub server_parser: String,
    pub honors_chat_template_kwargs: bool,
    pub chat_template_options_field: Option<String>,
    pub requires_completion_tokens: bool,
    /// True when the route is served ONLY by the provider Responses API and
    /// rejects `/v1/chat/completions` (OpenAI `*-codex` models). Harn routes
    /// such calls through the Responses provider automatically.
    pub chat_completions_unsupported: bool,
    /// See [`ProviderRule::reasoning_tools_require_responses`].
    pub reasoning_tools_require_responses: bool,
    pub requires_streaming: bool,
    pub reasoning_effort_supported: bool,
    pub reasoning_effort_levels: Vec<String>,
    pub reasoning_none_supported: bool,
    /// See [`ProviderRule::max_thinking_budget`]. `None` means the model uses
    /// the provider's own default ceiling.
    pub max_thinking_budget: Option<i64>,
    pub reasoning_disable_supported: bool,
    /// See [`ProviderRule::reasoning_required_for_tools`].
    pub reasoning_required_for_tools: bool,
    pub reasoning_text_promotable: bool,
    pub reasoning_wire_format: Option<String>,
    pub seed_supported: bool,
    pub top_k_supported: bool,
    pub temperature_supported: bool,
    pub top_p_supported: bool,
    pub frequency_penalty_supported: bool,
    pub presence_penalty_supported: bool,
    pub stop_supported: bool,
    pub allowed_tool_choice_modes: Vec<String>,
    pub requires_tool_result_adjacency: bool,
    pub supports_parallel_tool_calls: bool,
    pub tools_exclude_response_format: bool,
    pub recommended_endpoint: Option<String>,
    pub text_tool_wire_format_supported: bool,
    pub preferred_tool_format: Option<String>,
    pub tool_mode_parity: Option<String>,
    /// Where [`Self::tool_mode_parity`] came from.
    ///
    /// The verdict and its provenance used to share one slot, so a row a
    /// human wrote a verdict for was indistinguishable from a row that got
    /// the `unwrap_or_else` fallback (#5885). Both are *declarations* --
    /// neither is a forced-format sweep, which lives in the catalog's
    /// separate `tool_support.empirical_parity`.
    pub tool_mode_parity_source: Option<ToolModeParitySource>,
    pub tool_mode_parity_notes: Option<String>,
    pub thinking_disable_directive: Option<String>,
    /// Per-task auto-policy reasoning-level overrides for this route.
    /// See [`ProviderRule::auto_reasoning_overrides`].
    pub auto_reasoning_overrides: BTreeMap<String, String>,
    /// OpenRouter upstream provider names to exclude from routing for this
    /// row. See [`ProviderRule::provider_route_denylist`]. Empty means "no
    /// route restriction".
    pub provider_route_denylist: Vec<String>,
    /// OpenRouter upstream provider names this row is PINNED to (allowlist), in
    /// preference order. See [`ProviderRule::openrouter_provider_order`]. Empty
    /// means "no pin" (free OpenRouter routing).
    pub openrouter_provider_order: Vec<String>,
    /// Serving-quality / precision trust verdict for this route. See
    /// [`ProviderRule::serving_precision`]. `"unverified"` when unset.
    pub serving_precision: String,
    /// How the neutral `computer` tool projects onto this route's native
    /// computer-use surface. `None` means the route exposes no computer-use
    /// surface. See [`ComputerUseStyle`].
    pub computer_use_style: Option<ComputerUseStyle>,
    /// Screenshot downscaling policy applied before the image reaches the
    /// model. `None` means unset. See [`ScreenshotScaling`].
    pub screenshot_scaling: Option<ScreenshotScaling>,
    /// Whether this route requires echoing acknowledged safety checks on the
    /// computer-use follow-up turn (OpenAI Responses `pending_safety_checks`
    /// → `acknowledged_safety_checks`). See [`ProviderRule::safety_ack_flow`].
    pub safety_ack_flow: bool,
    /// How this route carries an interleaved `system`/`developer` message.
    /// `None` derives a safe default from `message_wire_format` (OpenAI/Ollama
    /// → `Inline`, everything else → `Fold`). See [`SystemMessagePlacement`]
    /// and [`resolve_system_message_placement`](super::resolve_system_message_placement).
    pub system_message_placement: Option<SystemMessagePlacement>,
}

impl Default for Capabilities {
    fn default() -> Self {
        Self {
            native_tools: false,
            message_wire_format: WireDialect::OpenAiCompat,
            native_tool_wire_format: "openai".to_string(),
            defer_loading: false,
            tool_search: Vec::new(),
            responses_api: false,
            hosted_tools: Vec::new(),
            remote_mcp: false,
            conversation_state: false,
            compaction: false,
            background_mode: false,
            batch_api: false,
            batch_wire_format: None,
            batch_input_mode: None,
            batch_discount_percent: None,
            batch_turnaround_hours: None,
            batch_max_requests: None,
            batch_max_input_bytes: None,
            batch_result_retention_days: None,
            batch_result_ordering: None,
            batch_partial_failure: None,
            batch_cancellation: None,
            batch_security_notes: Vec::new(),
            batch_operational_notes: Vec::new(),
            batch_regions: Vec::new(),
            tool_approval_policy: None,
            max_tools: None,
            prompt_caching: false,
            prompt_cache_ttls: Vec::new(),
            prompt_cache_min_prefix_tokens: None,
            cache_breakpoint_style: CacheBreakpointStyle::None,
            vision: false,
            audio: false,
            pdf: false,
            video: false,
            files_api_supported: false,
            file_upload_wire_format: None,
            structured_output: None,
            json_schema: None,
            prefers_xml_scaffolding: false,
            reserved_tool_call_token: false,
            prefers_markdown_scaffolding: false,
            structured_output_mode: "none".to_string(),
            supports_assistant_prefill: false,
            prefers_role_developer: false,
            prefers_xml_tools: false,
            thinking_block_style: "none".to_string(),
            live_endpoint_family: None,
            emits_inline_reasoning: false,
            thinking_modes: Vec::new(),
            interleaved_thinking_supported: false,
            anthropic_beta_features: Vec::new(),
            vision_supported: false,
            image_url_input_supported: true,
            preserve_thinking: false,
            reasoning_round_trip: ReasoningRoundTripPolicy::Strip,
            reasoning_history_wire_field: None,
            server_parser: "none".to_string(),
            honors_chat_template_kwargs: false,
            chat_template_options_field: None,
            requires_completion_tokens: false,
            chat_completions_unsupported: false,
            reasoning_tools_require_responses: false,
            requires_streaming: false,
            reasoning_effort_supported: false,
            reasoning_effort_levels: Vec::new(),
            reasoning_none_supported: false,
            max_thinking_budget: None,
            reasoning_disable_supported: true,
            reasoning_required_for_tools: false,
            reasoning_text_promotable: false,
            reasoning_wire_format: None,
            seed_supported: true,
            top_k_supported: true,
            temperature_supported: true,
            top_p_supported: true,
            frequency_penalty_supported: true,
            presence_penalty_supported: true,
            stop_supported: true,
            allowed_tool_choice_modes: Vec::new(),
            requires_tool_result_adjacency: false,
            supports_parallel_tool_calls: true,
            tools_exclude_response_format: false,
            recommended_endpoint: None,
            text_tool_wire_format_supported: true,
            preferred_tool_format: None,
            tool_mode_parity: None,
            tool_mode_parity_source: None,
            tool_mode_parity_notes: None,
            thinking_disable_directive: None,
            auto_reasoning_overrides: BTreeMap::new(),
            provider_route_denylist: Vec::new(),
            openrouter_provider_order: Vec::new(),
            serving_precision: "unverified".to_string(),
            computer_use_style: None,
            screenshot_scaling: None,
            safety_ack_flow: false,
            system_message_placement: None,
        }
    }
}