Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-harness/src/protocol.rs

Raw
//! Provider protocol bridge (`SMH-SPEC-PLUG0001`): guest codecs,
//! host-owned connection policy, secret resolution, and HTTP effects.

use crate::plugins::PluginManifest;
use crate::wasm::bindings::exports::smith::plugin::provider::{
    CatalogSnapshot, CatalogSource, MessageBlock, MessageRole, ProviderMessage,
    ProviderRequest as PluginProviderRequest, ProviderSettings, ProviderTool, SettingsProvenance,
    ToolResult, ToolUse,
};
use crate::wasm::{PluginEngine, PluginGeneration};
use futures::StreamExt;
use smith::error::{ProviderFault, Result, SmithError};
use smith::http::{
    HttpBodyEnd, HttpBodyItem, HttpExchange, HttpExecutorRef, HttpHeader, HttpMethod,
};
use smith::message::{ContentBlock, Role};
use smith::provider::{
    ProviderCatalogSource, ProviderDispatchProvenance, ProviderEffectOutcome, ProviderEffectRecord,
    ProviderRequest, ProviderSettingsProvenance, ProviderSettingsRecord, RecordSink, StreamFn,
};
use smith::stream::{StopReason, StreamEvent};
use smith::tool::CancelHandle;
use smith_ai::auth::{AuthStore, CredentialReference};
use smith_core::agent::{SecretProxy, StreamRedactor};
use std::path::PathBuf;
use std::sync::Arc;

/// Distinct host-authorized routes sharing a wire protocol.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProtocolConnection {
    /// Default API route.
    Api,
    /// Subscription route.
    CodingPlan,
}

impl ProtocolConnection {
    /// Path below this connection's authorized authority.
    #[must_use]
    pub const fn request_path(self) -> &'static str {
        match self {
            Self::Api => "/api/paas/v4/chat/completions",
            Self::CodingPlan => "/api/coding/paas/v4/chat/completions",
        }
    }
}

const OPENAI_COMPATIBLE_MANIFEST: &str = "id \"smith:protocol-openai-compatible\"\nversion \"0.1.0\"\nworld \"0.1.0\"\nartifact \"smith_plugin_protocol_openai_compatible.wasm\"\ncapability \"net-scope\"\ncapability \"secret-proxy\"";
const ANTHROPIC_MANIFEST: &str = "id \"smith:protocol-anthropic\"\nversion \"0.1.0\"\nworld \"0.1.0\"\nartifact \"smith_plugin_protocol_anthropic.wasm\"\ncapability \"net-scope\"\ncapability \"secret-proxy\"";
const GOOGLE_MANIFEST: &str = "id \"smith:protocol-google\"\nversion \"0.1.0\"\nworld \"0.1.0\"\nartifact \"smith_plugin_protocol_google.wasm\"\ncapability \"net-scope\"\ncapability \"secret-proxy\"";
const OPENAI_COMPATIBLE_COMPONENT: &[u8] = include_bytes!(concat!(
    env!("OUT_DIR"),
    "/smith_plugin_protocol_openai_compatible.wasm"
));
const ANTHROPIC_COMPONENT: &[u8] = include_bytes!(concat!(
    env!("OUT_DIR"),
    "/smith_plugin_protocol_anthropic.wasm"
));
const GOOGLE_COMPONENT: &[u8] = include_bytes!(concat!(
    env!("OUT_DIR"),
    "/smith_plugin_protocol_google.wasm"
));
#[cfg(test)]
const OPENAI_COMPATIBLE_TEMPLATE_URL: &str = "https://protocol.invalid/chat/completions";

/// Embedded pure protocol codecs selectable by host-owned connections.
#[derive(Clone, Copy)]
pub enum ProtocolComponent {
    /// Exact registered component using the generic build/decode exports.
    Registered,
    /// `OpenAI` chat-completions wire protocol.
    OpenAiCompatible,
    /// Anthropic Messages wire protocol.
    Anthropic,
    /// Google Gemini wire protocol.
    Google,
    /// `OpenAI` Responses protocol with subscription credentials only.
    OpenAiResponses,
}

impl ProtocolComponent {
    const fn binding(
        self,
    ) -> Option<crate::wasm::bindings::exports::smith::plugin::registration::ProtocolBinding> {
        use crate::wasm::bindings::exports::smith::plugin::registration::ProtocolBinding;
        match self {
            Self::OpenAiCompatible => Some(ProtocolBinding::OpenaiCompatible),
            Self::Anthropic => Some(ProtocolBinding::AnthropicMessages),
            Self::Google => Some(ProtocolBinding::GoogleGemini),
            Self::OpenAiResponses | Self::Registered => None,
        }
    }

    const fn embedded(self) -> &'static [u8] {
        match self {
            Self::Registered => &[],
            Self::OpenAiCompatible => OPENAI_COMPATIBLE_COMPONENT,
            Self::Anthropic => ANTHROPIC_COMPONENT,
            Self::Google => GOOGLE_COMPONENT,
            Self::OpenAiResponses => include_bytes!(concat!(
                env!("OUT_DIR"),
                "/smith_plugin_protocol_openai_responses.wasm"
            )),
        }
    }

    fn manifest(self) -> Result<PluginManifest> {
        PluginManifest::parse(match self {
            Self::Registered => {
                return Err(plugin_fault("registered codec requires registry selection"));
            }
            Self::OpenAiCompatible => OPENAI_COMPATIBLE_MANIFEST,
            Self::Anthropic => ANTHROPIC_MANIFEST,
            Self::Google => GOOGLE_MANIFEST,
            Self::OpenAiResponses => {
                "id \"smith:protocol-openai-responses\"\nversion \"0.1.0\"\nworld \"0.1.0\"\nartifact \"smith_plugin_protocol_openai_responses.wasm\"\ncapability \"net-scope\"\ncapability \"secret-proxy\""
            }
        })
    }
}
mod round;
pub(crate) use round::{ProviderRoundOwner, provider_round_channel};

const STREAM_CHANNEL_ITEMS: usize = 64;
/// Largest request or response payload crossing the provider codec boundary.
const CODEC_BODY_BYTES_MAX: usize = 1024 * 1024;

/// Credential authority selected before protocol dispatch, with no billing fallback.
#[derive(Clone)]
pub enum ProtocolCredential {
    /// Existing API-key source and precedence.
    ApiKey(CredentialReference),
    /// Selected renewable OAuth module/profile.
    Subscription(crate::oauth::source::SubscriptionCredential),
}

pub(crate) enum ResolvedCredential {
    ApiKey(String),
    Subscription([String; 3]),
}

impl ResolvedCredential {
    pub(crate) fn secrets(&self) -> &[String] {
        match self {
            Self::ApiKey(secret) => std::slice::from_ref(secret),
            Self::Subscription(secrets) => {
                if secrets[2].is_empty() {
                    &secrets[..2]
                } else {
                    secrets
                }
            }
        }
    }
}

impl ProtocolCredential {
    #[cfg(test)]
    pub(crate) fn resolve(
        &self,
        store: &AuthStore,
        endpoint: &str,
        cancel: &CancelHandle,
    ) -> Result<ResolvedCredential> {
        self.resolve_pinned(store, endpoint, cancel, None)
    }

    fn resolve_pinned(
        &self,
        store: &AuthStore,
        endpoint: &str,
        cancel: &CancelHandle,
        subscription: Option<crate::oauth::source::SubscriptionCall>,
    ) -> Result<ResolvedCredential> {
        match (self, subscription) {
            (Self::ApiKey(reference), None) => {
                reference.resolve(store).map(ResolvedCredential::ApiKey)
            }
            (Self::Subscription(reference), Some(call)) if endpoint == reference.endpoint() => call
                .renew(
                    reference.profile_id(),
                    reference.fixture_issuer(),
                    cancel.clone(),
                )
                .map(ResolvedCredential::Subscription),
            (Self::Subscription(_), Some(_)) => Err(plugin_fault(
                "subscription credential cannot cross its authorized inference origin",
            )),
            _ => Err(plugin_fault(
                "credential call does not match protocol authority",
            )),
        }
    }
}

pub(super) struct DispatchAdmission {
    pub(super) effect: std::sync::mpsc::Receiver<Result<()>>,
    pub(super) inference: Option<std::sync::mpsc::Receiver<Result<()>>>,
}

impl From<CredentialReference> for ProtocolCredential {
    fn from(reference: CredentialReference) -> Self {
        Self::ApiKey(reference)
    }
}

/// Host configuration for one protocol connection.
#[derive(Clone)]
pub struct ProtocolConnectionConfig {
    /// Host-authorized connection identity recorded before dispatch.
    pub connection_id: &'static str,
    /// Protocol implementation selected by this host-owned connection.
    pub protocol: ProtocolComponent,
    /// Explicit development component override; absent uses the release-embedded component.
    pub artifact: Option<PathBuf>,
    /// Fixed host-authorized endpoint. Tests may supply a loopback endpoint.
    pub endpoint: String,
    /// Exact pure template URL permitted for this protocol implementation.
    pub template_url: &'static str,
    /// Host-owned header receiving the resolved credential.
    pub credential_header: &'static str,
    /// Host-owned credential prefix, for example `Bearer `.
    pub credential_prefix: &'static str,
    /// Host-owned fixed headers required by this connection.
    pub static_headers: &'static [(&'static str, &'static str)],
    /// Explicit billing connection; protocol failure never changes it.
    pub connection: ProtocolConnection,
    /// Host-authorized path below the selected connection endpoint.
    pub request_path: String,
    /// Host-owned credential authority; plaintext resolves only while the
    /// authorized exchange is assembled, after guest template validation.
    pub credential: ProtocolCredential,
    /// Auth store used only by the credential authority at the HTTP boundary.
    pub auth_store: AuthStore,
    /// Shared bounded HTTP executor.
    pub executor: HttpExecutorRef,
    /// Redacted effect record spool.
    pub records: RecordSink,
    /// Maximum wait for durable intent admission.
    pub intent_admission_timeout: std::time::Duration,
    /// Immutable protocol-owned effective settings, resolved by the host.
    pub settings: ProviderSettings,
    /// Read-only host catalog projection pinned for this invocation.
    pub catalog: CatalogSnapshot,
}

/// Resolve registered provider/model contributions into a usable stream.
///
/// `provider` and `model` accept qualified identities or unambiguous short names.
/// `credential_source` must be the exact qualified source authorized by the host.
/// The connection must select [`ProtocolComponent::Registered`], API-key authority,
/// and a matching host catalog; its artifact override must be absent.
/// Generic build/decode exports execute the selected frozen component, independent
/// of vendor labels in registration. No development-link or credential fallback runs.
///
/// # Errors
/// Rejects missing, ambiguous, wrong-owner, or unauthorized selections before effects.
pub fn registered_protocol_transport(
    registry: &crate::wasm::PluginRegistry,
    provider: &str,
    model: &str,
    credential_source: &str,
    connection: ProtocolConnectionConfig,
) -> Result<StreamFn> {
    if !matches!(connection.protocol, ProtocolComponent::Registered)
        || connection.artifact.is_some()
        || !matches!(connection.credential, ProtocolCredential::ApiKey(_))
        || connection.settings.subscription
    {
        return Err(plugin_fault(
            "registered codec requires exact registry selection and host API-key authority",
        ));
    }
    let (generation, selection) =
        registry.resolve_registered_provider(provider, model, credential_source)?;
    let model = selection
        .model_id
        .strip_prefix(&format!("{}/", generation.manifest_id()))
        .ok_or_else(|| plugin_fault("registered model owner mismatch"))?;
    if connection.catalog.models.len() != 1
        || connection.catalog.models[0].id != model
        || connection.catalog.models[0].capabilities.output_tokens_max == 0
    {
        return Err(plugin_fault(
            "registered model requires one matching bounded host catalog entry",
        ));
    }
    let load = generation.protocol_loader();
    let mut scratch = load()?;
    validate_effective_settings(&mut scratch, connection.settings)?;
    Ok(protocol_transport_with_loader(
        connection,
        load,
        Some(Box::new(selection)),
        None,
    ))
}

/// Build a stream whose vendor codec runs only in the component.
///
/// # Errors
///
/// Returns a plugin fault when the component, its request template, or durable
/// intent admission fails.
pub fn protocol_transport(provider: ProtocolConnectionConfig) -> Result<StreamFn> {
    let engine = PluginEngine::new()?;
    let registry = crate::plugins::registry::PackageRegistry::at_default();
    let mut candidates = crate::wasm::PluginRegistry::new();
    let subscription = matches!(provider.credential, ProtocolCredential::Subscription(_));
    let mut generations = if provider.artifact.is_none() || subscription {
        registry.load_credential_modules(&engine)?
    } else {
        Vec::new()
    };
    if subscription {
        generations.push(crate::oauth::source::embedded_generation(&engine)?);
    }
    candidates.publish_all(generations)?;
    round::prepare_transport(provider, None, &mut candidates, &engine)
}

fn protocol_transport_with_loader(
    provider: ProtocolConnectionConfig,
    load: impl Fn() -> Result<PluginGeneration> + Send + Sync + 'static,
    selection: Option<Box<smith::provider::ProviderRegistrationBinding>>,
    credential_load: Option<crate::wasm::GenerationLoader>,
) -> StreamFn {
    Arc::new(move |request, cancel| {
        let subscription = match match &provider.credential {
            ProtocolCredential::ApiKey(_) => Ok(None),
            ProtocolCredential::Subscription(reference) => reference
                .begin_call_with_loader(credential_load.clone())
                .map(Some),
        } {
            Ok(subscription) => subscription,
            Err(error) => return futures::stream::iter(std::iter::once(Err(error))).boxed(),
        };
        let prepared = validate_effective_request(&request, &provider.catalog)
            .and_then(|()| build_messages(&request))
            .and_then(|mut messages| {
                if let ProtocolCredential::Subscription(credential) = &provider.credential
                    && let Some(project) = credential.google_project() {
                        let identity = request.messages.iter().rev().find(|message| message.role == Role::User)
                        .ok_or_else(|| plugin_fault("Google subscription requires a recorded user prompt identity"))?.id.to_string();
                        messages.code_assist = Some(crate::wasm::bindings::exports::smith::plugin::provider::CodeAssistContext {
                            project: project.into(),
                            user_prompt_id: identity,
                        });
                }
                let mut generation = load()?;
                let settings = validate_effective_settings(&mut generation, provider.settings)?;
                let template = generation.build_provider_request(
                    &request.model,
                    &messages,
                    settings,
                    &provider.catalog,
                )?;
                let exchange = authorize_template(
                    &template.url,
                    &template.authorization,
                    template.body,
                    &provider,
                )?;
                let provenance = ProviderDispatchProvenance {
                    registration_binding: selection.clone(),
                    connection_id: provider.connection_id.to_string(),
                    protocol_manifest_id: generation.manifest_id().into(),
                    protocol_component_sha256: generation.component_sha256().to_string(),
                    catalog_generation: provider.catalog.generation,
                    catalog_source: catalog_source(provider.catalog.source),
                    settings: settings_record(settings),
                    credential_binding: match &provider.credential {
                        ProtocolCredential::ApiKey(_) => None,
                        ProtocolCredential::Subscription(_) => subscription
                            .as_ref()
                            .map(|call| Box::new(call.binding().clone())),
                    },
                };
                let admission = admit_dispatch(&provider, &exchange, provenance)?;
                Ok((generation, exchange, admission, subscription))
            });
        let (mut generation, exchange, admission, subscription) = match prepared {
            Ok(prepared) => prepared,
            Err(error) => return futures::stream::iter(std::iter::once(Err(error))).boxed(),
        };
        let provider = provider.clone();
        let (sender, receiver) = std::sync::mpsc::sync_channel(STREAM_CHANNEL_ITEMS);
        std::thread::spawn(move || {
            let result = dispatch_pinned(
                &provider,
                &request.model,
                exchange,
                &admission,
                &cancel,
                subscription,
                &mut generation,
                &sender,
            );
            if let Err(error) = result {
                match send_item(&sender, Err(error), &cancel) {
                    Ok(()) | Err(_) => {}
                }
            }
        });
        futures::stream::unfold(receiver, |receiver| async move {
            receiver.recv().ok().map(|item| (item, receiver))
        })
        .boxed()
    })
}

fn admit_dispatch(
    provider: &ProtocolConnectionConfig,
    exchange: &HttpExchange,
    provenance: ProviderDispatchProvenance,
) -> Result<DispatchAdmission> {
    admit_dispatch_with_mode(
        provider,
        exchange,
        provenance,
        matches!(provider.credential, ProtocolCredential::Subscription(_))
            && matches!(provider.protocol, ProtocolComponent::OpenAiResponses),
    )
}

fn admit_dispatch_with_mode(
    provider: &ProtocolConnectionConfig,
    exchange: &HttpExchange,
    provenance: ProviderDispatchProvenance,
    account_catalog: bool,
) -> Result<DispatchAdmission> {
    let primary_headers = if account_catalog {
        exchange.headers.get(..1).ok_or_else(|| {
            plugin_fault("subscription exchange missing authorized credential header")
        })?
    } else {
        &exchange.headers
    };
    let acknowledgement = provider.records.request_intent(
        ProviderEffectRecord::Intent {
            method: if account_catalog {
                HttpMethod::Get
            } else {
                exchange.method
            },
            url: if account_catalog {
                format!("{}/v1/models", provider.endpoint)
            } else {
                exchange.url.clone()
            },
            headers: smith::http::redact_headers(primary_headers).into(),
            request_bytes: if account_catalog {
                0
            } else {
                exchange.body.len()
            },
        },
        provenance.clone(),
    )?;
    let inference_admission = if account_catalog {
        Some(provider.records.request_intent(
            ProviderEffectRecord::Intent {
                method: exchange.method,
                url: exchange.url.clone(),
                headers: smith::http::redact_headers(&exchange.headers).into(),
                request_bytes: exchange.body.len(),
            },
            provenance,
        )?)
    } else {
        None
    };
    Ok(DispatchAdmission {
        effect: acknowledgement,
        inference: inference_admission,
    })
}

/// SHA-256 identity of the embedded release component.
#[must_use]
pub const fn embedded_openai_compatible_component_sha256() -> &'static str {
    env!("SMITH_OPENAI_COMPATIBLE_COMPONENT_SHA256")
}

/// SHA-256 identity of the embedded Anthropic release component.
#[must_use]
pub const fn embedded_anthropic_component_sha256() -> &'static str {
    env!("SMITH_ANTHROPIC_COMPONENT_SHA256")
}

/// SHA-256 identity of the embedded Google release component.
#[must_use]
pub const fn embedded_google_component_sha256() -> &'static str {
    env!("SMITH_GOOGLE_COMPONENT_SHA256")
}

fn validate_effective_settings(
    generation: &mut PluginGeneration,
    effective: ProviderSettings,
) -> Result<ProviderSettings> {
    validate_protocol_settings(generation)?;
    let settings = generation.validate_provider_settings(effective)?;
    if settings.include_usage != effective.include_usage
        || settings.subscription != effective.subscription
        || std::mem::discriminant(&settings.provenance)
            != std::mem::discriminant(&effective.provenance)
    {
        return Err(plugin_fault("protocol altered host effective settings"));
    }
    Ok(settings)
}

fn validate_protocol_settings(generation: &mut PluginGeneration) -> Result<()> {
    let declarations = generation.provider_settings()?;
    if protocol_settings_supported(declarations) {
        Ok(())
    } else {
        Err(plugin_fault(
            "protocol settings declaration does not match the supported binding",
        ))
    }
}

const fn protocol_settings_supported(settings: ProviderSettings) -> bool {
    settings.include_usage
}

const fn settings_record(settings: ProviderSettings) -> ProviderSettingsRecord {
    ProviderSettingsRecord {
        include_usage: settings.include_usage,
        provenance: match settings.provenance {
            SettingsProvenance::BuiltIn => ProviderSettingsProvenance::BuiltIn,
            SettingsProvenance::User => ProviderSettingsProvenance::User,
            SettingsProvenance::TrustedProject => ProviderSettingsProvenance::TrustedProject,
            SettingsProvenance::Explicit => ProviderSettingsProvenance::Explicit,
        },
    }
}

const fn catalog_source(source: CatalogSource) -> ProviderCatalogSource {
    match source {
        CatalogSource::Bundled => ProviderCatalogSource::Bundled,
        CatalogSource::Cache => ProviderCatalogSource::Cache,
        CatalogSource::ModelsDev => ProviderCatalogSource::ModelsDev,
    }
}

fn validate_effective_request(request: &ProviderRequest, catalog: &CatalogSnapshot) -> Result<()> {
    let model = catalog
        .models
        .iter()
        .find(|entry| entry.id == request.model)
        .ok_or_else(|| plugin_fault("pinned catalog does not admit model"))?;
    if !request.tools.is_empty() && !model.capabilities.tool_use {
        return Err(plugin_fault(
            "pinned catalog does not admit tool definitions",
        ));
    }
    if let Some(limit) = request.params.output_tokens_max
        && limit > model.capabilities.output_tokens_max
    {
        return Err(plugin_fault(
            "requested output tokens exceed pinned catalog limit",
        ));
    }
    if request.params.thinking && !model.capabilities.thinking {
        return Err(plugin_fault("pinned catalog does not admit thinking"));
    }
    Ok(())
}

fn build_messages(request: &ProviderRequest) -> Result<PluginProviderRequest> {
    let messages = request
        .messages
        .iter()
        .map(|message| {
            validate_message(message)?;
            let role = match message.role {
                Role::System => MessageRole::System,
                Role::User => MessageRole::User,
                Role::Assistant => MessageRole::Assistant,
                Role::Tool => MessageRole::Tool,
            };
            let blocks =
                message
                    .blocks
                    .iter()
                    .map(|block| match block {
                        ContentBlock::Text(text) => Ok(MessageBlock::Text(text.clone())),
                        ContentBlock::Thinking(text) => Ok(MessageBlock::Thinking(text.clone())),
                        ContentBlock::ToolUse {
                            name,
                            input,
                            call_id,
                        } => Ok(MessageBlock::ToolUse(ToolUse {
                            name: name.clone(),
                            input_json: serde_json::to_string(input).map_err(|error| {
                                plugin_fault(format!("cannot encode tool arguments: {error}"))
                            })?,
                            call_id: request
                                .provider_call_ids
                                .get(call_id)
                                .cloned()
                                .ok_or_else(|| plugin_fault("tool use has no provider call ID"))?,
                        })),
                        ContentBlock::ToolResult {
                            call_id, output, ..
                        } => Ok(MessageBlock::ToolResult(ToolResult {
                            call_id: request.provider_call_ids.get(call_id).cloned().ok_or_else(
                                || plugin_fault("tool result has no provider call ID"),
                            )?,
                            name: tool_result_name(&request.messages, *call_id)?.to_string(),
                            output: output.clone(),
                        })),
                    })
                    .collect::<Result<Vec<_>>>();
            blocks.map(|blocks| ProviderMessage { role, blocks })
        })
        .collect::<Result<Vec<_>>>()?;
    let tools = request
        .tools
        .iter()
        .map(|tool| {
            Ok(ProviderTool {
                name: tool.name.clone(),
                description: tool.description.clone(),
                input_schema_json: serde_json::to_string(&tool.input_schema)
                    .map_err(|error| plugin_fault(format!("cannot encode tool schema: {error}")))?,
            })
        })
        .collect::<Result<Vec<_>>>()?;
    Ok(PluginProviderRequest {
        code_assist: None,
        messages,
        tools,
        output_tokens_max: request.params.output_tokens_max,
    })
}

fn tool_result_name(
    messages: &[smith::message::Message],
    call_id: smith::id::ToolCallId,
) -> Result<&str> {
    messages
        .iter()
        .rev()
        .flat_map(|message| &message.blocks)
        .find_map(|block| match block {
            ContentBlock::ToolUse {
                name,
                call_id: tool_call_id,
                ..
            } if *tool_call_id == call_id => Some(name.as_str()),
            _ => None,
        })
        .ok_or_else(|| plugin_fault("tool result has no matching tool use"))
}

fn validate_message(message: &smith::message::Message) -> Result<()> {
    let supported = match message.role {
        Role::System | Role::User => message
            .blocks
            .iter()
            .all(|block| matches!(block, ContentBlock::Text(_))),
        Role::Assistant => message
            .blocks
            .iter()
            .all(|block| matches!(block, ContentBlock::Text(_) | ContentBlock::ToolUse { .. })),
        Role::Tool => message
            .blocks
            .iter()
            .all(|block| matches!(block, ContentBlock::ToolResult { .. })),
    };
    if supported {
        Ok(())
    } else {
        Err(plugin_fault(
            "provider request contains blocks this protocol cannot represent",
        ))
    }
}

pub(super) fn authorize_template(
    url: &str,
    authorization: &str,
    body: String,
    provider: &ProtocolConnectionConfig,
) -> Result<HttpExchange> {
    if body.len() > CODEC_BODY_BYTES_MAX {
        return Err(plugin_fault(format!(
            "provider request exceeds {CODEC_BODY_BYTES_MAX} bytes"
        )));
    }
    if url != provider.template_url {
        return Err(plugin_fault(
            "protocol plugin requested an endpoint outside its fixed scope",
        ));
    }
    let authorized = match (&provider.credential, provider.protocol) {
        (ProtocolCredential::Subscription(credential), ProtocolComponent::OpenAiResponses) => {
            credential.provider() == crate::oauth::login::SubscriptionProvider::OpenAi
                && provider.connection_id == "openai-chatgpt-plan"
                && authorization == "Bearer {{secret:connection-oauth}}"
        }
        (ProtocolCredential::Subscription(credential), ProtocolComponent::Anthropic) => {
            credential.provider() == crate::oauth::login::SubscriptionProvider::Anthropic
                && provider.connection_id == "anthropic-claude-plan"
                && authorization == "{{secret:anthropic-connection}}"
        }
        (ProtocolCredential::Subscription(credential), ProtocolComponent::Google) => {
            credential.provider() == crate::oauth::login::SubscriptionProvider::Google
                && provider.connection_id == "google-gemini-cli-plan"
                && authorization == "Bearer {{secret:connection-oauth}}"
        }
        (ProtocolCredential::ApiKey(_), ProtocolComponent::Anthropic) => {
            provider.connection_id == "anthropic-api"
                && authorization == "{{secret:anthropic-connection}}"
        }
        (ProtocolCredential::ApiKey(_), ProtocolComponent::OpenAiResponses)
        | (ProtocolCredential::Subscription(_), _) => false,
        (ProtocolCredential::ApiKey(_), _) => {
            authorization == "{{secret:connection-api-key}}"
                || authorization == "Bearer {{secret:connection-api-key}}"
        }
    };
    if !authorized {
        return Err(plugin_fault(
            "protocol plugin requested an unauthorized credential substitution",
        ));
    }
    let endpoint = provider
        .endpoint
        .strip_suffix('/')
        .unwrap_or(&provider.endpoint);
    let loopback_endpoint = endpoint
        .strip_prefix("http://127.0.0.1:")
        .is_some_and(|port| {
            !port.is_empty()
                && port.bytes().all(|byte| byte.is_ascii_digit())
                && port.parse::<u16>().is_ok()
        });
    if !endpoint.starts_with("https://") && !loopback_endpoint {
        return Err(plugin_fault(
            "OpenAI-compatible endpoint is outside the host-authorized network scope",
        ));
    }
    if !provider.request_path.starts_with('/') || provider.request_path.contains('#') {
        return Err(plugin_fault(
            "OpenAI-compatible connection has an invalid authorized request path",
        ));
    }
    Ok(HttpExchange {
        method: HttpMethod::Post,
        url: format!("{endpoint}{}", provider.request_path),
        headers: std::iter::once(HttpHeader {
            name: provider.credential_header.into(),
            value: format!(
                "{}{{{{secret:connection-api-key}}}}",
                provider.credential_prefix
            ),
        })
        .chain(std::iter::once(HttpHeader {
            name: "Content-Type".into(),
            value: "application/json".into(),
        }))
        .chain(
            provider
                .static_headers
                .iter()
                .map(|(name, value)| HttpHeader {
                    name: (*name).into(),
                    value: (*value).into(),
                }),
        )
        .collect(),
        body: body.into_bytes(),
    })
}

fn account_entitlement(
    provider: &ProtocolConnectionConfig,
    model: &str,
    credential: &str,
    cancel: &CancelHandle,
) -> Result<()> {
    const ACCOUNT_CATALOG_BYTES_MAX: usize = 128 * 1024;
    let exchange = HttpExchange {
        method: HttpMethod::Get,
        url: format!("{}/v1/models", provider.endpoint),
        headers: vec![HttpHeader {
            name: "Authorization".into(),
            value: format!("Bearer {credential}"),
        }],
        body: Vec::new(),
    };
    let mut status = 0;
    let mut bytes = Vec::new();
    let result = (|| {
        let response = provider
            .executor
            .execute(exchange, cancel.clone())
            .map_err(|_| plugin_fault("account catalog transport failed"))?;
        status = response.head.status;
        if status != 200 {
            return Err(plugin_fault(
                "selected account model catalog rejected; no inference dispatched",
            ));
        }
        let mut complete = false;
        for item in response.body {
            match item {
                HttpBodyItem::Chunk(chunk) => {
                    if bytes.len().saturating_add(chunk.bytes.len()) > ACCOUNT_CATALOG_BYTES_MAX {
                        return Err(plugin_fault("account model catalog exceeds byte bound"));
                    }
                    bytes.extend_from_slice(&chunk.bytes);
                }
                HttpBodyItem::End(HttpBodyEnd::Complete) => {
                    complete = true;
                    break;
                }
                HttpBodyItem::End(_) => {
                    return Err(plugin_fault(
                        "account model catalog incomplete; no inference dispatched",
                    ));
                }
            }
        }
        if !complete || cancel.is_cancelled() {
            return Err(plugin_fault(
                "account model catalog incomplete; no inference dispatched",
            ));
        }
        admitted_account_model(&bytes, model)
    })();
    record_outcome(
        provider,
        status,
        bytes.len() as u64,
        if result.is_ok() {
            ProviderEffectOutcome::Completed
        } else {
            ProviderEffectOutcome::Failed
        },
    );
    result
}

fn admitted_account_model(bytes: &[u8], model: &str) -> Result<()> {
    let catalog: serde_json::Value =
        serde_json::from_slice(bytes).map_err(|_| plugin_fault("invalid account model catalog"))?;
    let models = catalog["models"]
        .as_array()
        .filter(|models| models.len() <= 1024)
        .ok_or_else(|| plugin_fault("invalid account model catalog shape or count"))?;
    if models.iter().any(|entry| {
        entry["visibility"].as_str() == Some("list") && entry["slug"].as_str() == Some(model)
    }) {
        Ok(())
    } else {
        Err(plugin_fault(
            "selected model not available to selected ChatGPT account; no inference dispatched",
        ))
    }
}

#[cfg(test)]
pub(super) fn dispatch(
    provider: &ProtocolConnectionConfig,
    model: &str,
    exchange: HttpExchange,
    admission: &DispatchAdmission,
    cancel: &CancelHandle,
    generation: &mut PluginGeneration,
    sender: &std::sync::mpsc::SyncSender<smith::provider::StreamItem>,
) -> Result<()> {
    dispatch_pinned(
        provider, model, exchange, admission, cancel, None, generation, sender,
    )
}

#[expect(
    clippy::too_many_arguments,
    reason = "the subscription generation pin joins the existing dispatch boundary"
)]
#[expect(
    clippy::too_many_lines,
    reason = "each post-dispatch exit records exactly one terminal outcome beside its cause"
)]
fn dispatch_pinned(
    provider: &ProtocolConnectionConfig,
    model: &str,
    mut exchange: HttpExchange,
    admission: &DispatchAdmission,
    cancel: &CancelHandle,
    subscription: Option<crate::oauth::source::SubscriptionCall>,
    generation: &mut PluginGeneration,
    sender: &std::sync::mpsc::SyncSender<smith::provider::StreamItem>,
) -> Result<()> {
    if let Err(error) =
        await_admission(&admission.effect, cancel, provider.intent_admission_timeout)
    {
        record_outcome(provider, 0, 0, outcome_for(&error));
        return Err(error);
    }
    let resolved = provider.credential.resolve_pinned(
        &provider.auth_store,
        &provider.endpoint,
        cancel,
        subscription,
    );
    let credential = match resolved {
        Ok(credential) => credential,
        Err(error) => {
            record_outcome(provider, 0, 0, ProviderEffectOutcome::Failed);
            return Err(error);
        }
    };
    let credentials = credential.secrets();
    let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
        credentials,
        b"{{secret:connection-api-key}}",
    )
    .map_err(|message| {
        record_outcome(provider, 0, 0, ProviderEffectOutcome::Failed);
        plugin_fault(message)
    })?;
    if matches!(provider.credential, ProtocolCredential::Subscription(_))
        && matches!(provider.protocol, ProtocolComponent::OpenAiResponses)
    {
        account_entitlement(provider, model, &credentials[0], cancel)?;
        let acknowledgement = admission
            .inference
            .as_ref()
            .ok_or_else(|| plugin_fault("subscription inference has no durable admission"))?;
        await_admission(acknowledgement, cancel, provider.intent_admission_timeout)?;
    }
    exchange.headers[0].value = format!("{}{}", provider.credential_prefix, credentials[0]);
    let mut secrets = SecretProxy::new();
    for (name, credential) in [
        "connection-api-key",
        "connection-oauth-refresh",
        "connection-oauth-identity",
    ]
    .into_iter()
    .zip(credentials)
    {
        // Sanitizer borrows the resolved set; the core error redactor owns its registrations.
        secrets.register(name, credential.clone());
    }
    let mut redactor = StreamRedactor::default();
    let response = match provider.executor.execute(exchange, cancel.clone()) {
        Ok(response) => response,
        Err(error) => {
            record_outcome(provider, 0, 0, outcome_for(&error));
            return Err(secrets.mask_error(error));
        }
    };
    let status = response.head.status;
    if !(200..300).contains(&status) {
        let (response_bytes, outcome, error) =
            non_success_response(status, response.body, cancel, &mut sanitizer);
        record_outcome(provider, status, response_bytes, outcome);
        return Err(error);
    }
    let mut state = Vec::new();
    let mut response_bytes = 0_u64;
    let message_id = smith::id::MessageId::new();
    let mut terminal = None;
    for item in response.body {
        match item {
            HttpBodyItem::Chunk(chunk) => {
                let Some(bytes) = response_bytes
                    .checked_add(u64::try_from(chunk.bytes.len()).unwrap_or(u64::MAX))
                else {
                    record_outcome(
                        provider,
                        status,
                        response_bytes,
                        ProviderEffectOutcome::Failed,
                    );
                    return Err(plugin_fault("provider response byte count overflowed"));
                };
                response_bytes = bytes;
                if response_bytes > CODEC_BODY_BYTES_MAX as u64 {
                    record_outcome(
                        provider,
                        status,
                        response_bytes,
                        ProviderEffectOutcome::Failed,
                    );
                    return Err(plugin_fault(format!(
                        "provider response exceeds {CODEC_BODY_BYTES_MAX} bytes"
                    )));
                }
                let filtered = sanitizer.push(&chunk.bytes).map_err(|message| {
                    record_outcome(
                        provider,
                        status,
                        response_bytes,
                        ProviderEffectOutcome::Failed,
                    );
                    plugin_fault(message)
                })?;
                let step = match generation.decode_provider_chunk(&state, &filtered, false) {
                    Ok(step) => step,
                    Err(error) => {
                        record_outcome(
                            provider,
                            status,
                            response_bytes,
                            ProviderEffectOutcome::Failed,
                        );
                        return Err(secrets.mask_error(error));
                    }
                };
                state = step.state;
                if let Err(error) = send_events(
                    step.events,
                    message_id,
                    sender,
                    cancel,
                    &mut terminal,
                    &mut redactor,
                    &secrets,
                ) {
                    record_outcome(provider, status, response_bytes, outcome_for(&error));
                    return Err(error);
                }
            }
            HttpBodyItem::End(HttpBodyEnd::Complete) => {
                if cancel.is_cancelled() {
                    record_outcome(
                        provider,
                        status,
                        response_bytes,
                        ProviderEffectOutcome::Cancelled,
                    );
                    return Err(SmithError::Cancelled);
                }
                let filtered = sanitizer.finish();
                let step = match generation.decode_provider_chunk(&state, &filtered, true) {
                    Ok(step) => step,
                    Err(error) => {
                        record_outcome(
                            provider,
                            status,
                            response_bytes,
                            ProviderEffectOutcome::Failed,
                        );
                        return Err(secrets.mask_error(error));
                    }
                };
                if let Err(error) = send_events(
                    step.events,
                    message_id,
                    sender,
                    cancel,
                    &mut terminal,
                    &mut redactor,
                    &secrets,
                ) {
                    record_outcome(provider, status, response_bytes, outcome_for(&error));
                    return Err(error);
                }
                record_outcome(
                    provider,
                    status,
                    response_bytes,
                    ProviderEffectOutcome::Completed,
                );
                return send_terminal(terminal, sender, cancel);
            }
            HttpBodyItem::End(HttpBodyEnd::Cancelled) => {
                record_outcome(
                    provider,
                    status,
                    response_bytes,
                    ProviderEffectOutcome::Cancelled,
                );
                return Err(SmithError::Cancelled);
            }
            HttpBodyItem::End(HttpBodyEnd::Truncated { limit }) => {
                record_outcome(
                    provider,
                    status,
                    response_bytes,
                    ProviderEffectOutcome::Failed,
                );
                return Err(plugin_fault(format!(
                    "provider response exceeds {limit} bytes"
                )));
            }
            HttpBodyItem::End(HttpBodyEnd::Failed { message }) => {
                record_outcome(
                    provider,
                    status,
                    response_bytes,
                    ProviderEffectOutcome::Failed,
                );
                return Err(secrets.mask_error(plugin_fault(message)));
            }
        }
    }
    if cancel.is_cancelled() {
        record_outcome(
            provider,
            status,
            response_bytes,
            ProviderEffectOutcome::Cancelled,
        );
        return Err(SmithError::Cancelled);
    }
    record_outcome(
        provider,
        status,
        response_bytes,
        ProviderEffectOutcome::Failed,
    );
    Err(plugin_fault(
        "provider response ended without a terminal outcome",
    ))
}

/// Sanitized JSON retained only to extract a provider error code and message.
const PROVIDER_ERROR_JSON_CAPTURE_BYTES_MAX: usize = 16 * 1024;
/// Normalized code or message bytes exposed in a provider error.
const PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX: usize = 512;

fn non_success_response(
    status: u16,
    body: std::sync::mpsc::Receiver<HttpBodyItem>,
    cancel: &CancelHandle,
    sanitizer: &mut crate::response_sanitizer::ResponseSanitizer<'_>,
) -> (u64, ProviderEffectOutcome, SmithError) {
    let mut response_bytes = 0_u64;
    let mut diagnostic_bytes = Vec::new();
    for item in body {
        match item {
            HttpBodyItem::Chunk(chunk) => {
                let Ok(chunk_bytes) = u64::try_from(chunk.bytes.len()) else {
                    return non_success_failure(status, response_bytes);
                };
                let Some(bytes) = response_bytes.checked_add(chunk_bytes) else {
                    return non_success_failure(status, response_bytes);
                };
                response_bytes = bytes;
                if response_bytes > CODEC_BODY_BYTES_MAX as u64 {
                    return non_success_failure(status, response_bytes);
                }
                let Ok(filtered) = sanitizer.push(&chunk.bytes) else {
                    return non_success_failure(status, response_bytes);
                };
                if !append_error_diagnostic_bytes(&mut diagnostic_bytes, &filtered) {
                    return non_success_failure(status, response_bytes);
                }
            }
            HttpBodyItem::End(HttpBodyEnd::Complete) => {
                if cancel.is_cancelled()
                    || !append_error_diagnostic_bytes(&mut diagnostic_bytes, &sanitizer.finish())
                {
                    return non_success_failure(status, response_bytes);
                }
                return (
                    response_bytes,
                    ProviderEffectOutcome::Failed,
                    provider_status_error(status, &diagnostic_bytes),
                );
            }
            HttpBodyItem::End(
                HttpBodyEnd::Cancelled | HttpBodyEnd::Truncated { .. } | HttpBodyEnd::Failed { .. },
            ) => return non_success_failure(status, response_bytes),
        }
    }
    non_success_failure(status, response_bytes)
}

fn append_error_diagnostic_bytes(bytes: &mut Vec<u8>, additional: &[u8]) -> bool {
    let Some(length) = bytes.len().checked_add(additional.len()) else {
        return false;
    };
    if length > PROVIDER_ERROR_JSON_CAPTURE_BYTES_MAX {
        return false;
    }
    bytes.extend_from_slice(additional);
    true
}

fn non_success_failure(
    status: u16,
    response_bytes: u64,
) -> (u64, ProviderEffectOutcome, SmithError) {
    (
        response_bytes,
        ProviderEffectOutcome::Failed,
        provider_status_error(status, &[]),
    )
}

fn provider_status_error(status: u16, body: &[u8]) -> SmithError {
    let diagnostic = serde_json::from_slice::<serde_json::Value>(body)
        .ok()
        .and_then(|value| provider_error_fields(&value))
        .and_then(|(code, message)| {
            match (
                code.as_deref().and_then(normalize_provider_diagnostic),
                message.as_deref().and_then(normalize_provider_diagnostic),
            ) {
                (Some(code), Some(message)) => Some(format!(": {code}: {message}")),
                (Some(code), None) => Some(format!(": {code}")),
                (None, Some(message)) => Some(format!(": {message}")),
                (None, None) => None,
            }
        })
        .unwrap_or_default();
    plugin_fault(format!("provider returned HTTP {status}{diagnostic}"))
}

fn provider_error_fields(value: &serde_json::Value) -> Option<(Option<String>, Option<String>)> {
    let error = value.get("error").unwrap_or(value);
    let code = error
        .get("code")
        .and_then(serde_json::Value::as_str)
        .map(str::to_owned);
    let message = error
        .get("message")
        .and_then(serde_json::Value::as_str)
        .map(str::to_owned);
    (code.is_some() || message.is_some()).then_some((code, message))
}

fn normalize_provider_diagnostic(value: &str) -> Option<String> {
    let mut normalized =
        String::with_capacity(value.len().min(PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX));
    for character in value.chars() {
        let character = if character.is_control() {
            ' '
        } else {
            character
        };
        if normalized.len() + character.len_utf8() > PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX {
            break;
        }
        normalized.push(character);
    }
    (!normalized.trim().is_empty()).then_some(normalized.trim().to_owned())
}

const fn outcome_for(error: &SmithError) -> ProviderEffectOutcome {
    if matches!(error, SmithError::Cancelled) {
        ProviderEffectOutcome::Cancelled
    } else {
        ProviderEffectOutcome::Failed
    }
}

fn record_outcome(
    provider: &ProtocolConnectionConfig,
    status: u16,
    response_bytes: u64,
    outcome: ProviderEffectOutcome,
) {
    provider.records.record(ProviderEffectRecord::Outcome {
        status,
        response_bytes,
        outcome,
    });
}

fn send_events(
    events: Vec<crate::wasm::bindings::exports::smith::plugin::provider::StreamEvent>,
    message_id: smith::id::MessageId,
    sender: &std::sync::mpsc::SyncSender<smith::provider::StreamItem>,
    cancel: &CancelHandle,
    terminal: &mut Option<StreamEvent>,
    redactor: &mut StreamRedactor,
    secrets: &SecretProxy,
) -> Result<()> {
    use crate::wasm::bindings::exports::smith::plugin::provider::{
        StopReason as GuestStopReason, StreamEvent as GuestStreamEvent,
    };
    for event in events {
        let event = match event {
            GuestStreamEvent::Text(text) => StreamEvent::text_delta(message_id, text),
            GuestStreamEvent::Thinking(text) => StreamEvent::thinking_delta(message_id, text),
            GuestStreamEvent::ToolUse(tool) => {
                if tool.call_id.is_empty() {
                    return Err(plugin_fault(
                        "plugin tool call has an empty provider call ID",
                    ));
                }
                StreamEvent::tool_use_with_provider_call_id(
                    message_id,
                    tool.name,
                    serde_json::from_str(&tool.input_json).map_err(|error| {
                        plugin_fault(format!("plugin tool input is not JSON: {error}"))
                    })?,
                    smith::id::ToolCallId::new(),
                    tool.call_id,
                )
            }
            GuestStreamEvent::Stop((reason, usage)) => StreamEvent::stop(
                match reason {
                    GuestStopReason::EndTurn => StopReason::EndTurn,
                    GuestStopReason::ToolUse => StopReason::ToolUse,
                    GuestStopReason::Limit => StopReason::Limit,
                    GuestStopReason::Abort => StopReason::Abort,
                    GuestStopReason::StopSequence => StopReason::StopSequence,
                    GuestStopReason::Refusal => StopReason::Refusal,
                    GuestStopReason::ContentFilter => StopReason::ContentFilter,
                },
                usage.map(|usage| smith::stream::Usage {
                    input_tokens: usage.input_tokens,
                    output_tokens: usage.output_tokens,
                    input_cache_hit_tokens: usage.input_cache_hit_tokens,
                    input_cache_write_tokens: usage.input_cache_write_tokens,
                }),
            ),
        };
        if matches!(event, StreamEvent::Stop { .. }) {
            for event in redactor.drain(secrets, true)? {
                send_item(sender, Ok(event), cancel)?;
            }
            *terminal = Some(event);
        } else {
            for event in redactor.push(event, secrets)? {
                send_item(sender, Ok(event), cancel)?;
            }
        }
    }
    Ok(())
}

fn send_terminal(
    terminal: Option<StreamEvent>,
    sender: &std::sync::mpsc::SyncSender<smith::provider::StreamItem>,
    cancel: &CancelHandle,
) -> Result<()> {
    let event =
        terminal.ok_or_else(|| plugin_fault("provider stream completed without terminal event"))?;
    send_item(sender, Ok(event), cancel)
}

fn send_item(
    sender: &std::sync::mpsc::SyncSender<smith::provider::StreamItem>,
    mut item: smith::provider::StreamItem,
    cancel: &CancelHandle,
) -> Result<()> {
    loop {
        if cancel.is_cancelled() && item.is_ok() {
            return Err(SmithError::Cancelled);
        }
        match sender.try_send(item) {
            Ok(()) => return Ok(()),
            Err(std::sync::mpsc::TrySendError::Disconnected(_)) => {
                return Err(SmithError::Cancelled);
            }
            Err(std::sync::mpsc::TrySendError::Full(returned)) => {
                item = returned;
                std::thread::yield_now();
            }
        }
    }
}

#[cfg(test)]
fn append_response_bytes(bytes: &mut Vec<u8>, chunk: &[u8]) -> Result<()> {
    let Some(length) = bytes.len().checked_add(chunk.len()) else {
        return Err(plugin_fault("provider response byte count overflowed"));
    };
    if length > CODEC_BODY_BYTES_MAX {
        return Err(plugin_fault(format!(
            "provider response exceeds {CODEC_BODY_BYTES_MAX} bytes"
        )));
    }
    bytes.extend_from_slice(chunk);
    Ok(())
}

fn await_admission(
    acknowledgement: &std::sync::mpsc::Receiver<Result<()>>,
    cancel: &CancelHandle,
    timeout: std::time::Duration,
) -> Result<()> {
    let started = std::time::Instant::now();
    loop {
        if cancel.is_cancelled() {
            return Err(SmithError::Cancelled);
        }
        let Some(remaining) = timeout.checked_sub(started.elapsed()) else {
            return Err(plugin_fault("provider intent admission timed out"));
        };
        match acknowledgement.recv_timeout(remaining.min(std::time::Duration::from_millis(10))) {
            Ok(result) => return result,
            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
                return Err(plugin_fault("provider intent acknowledgement closed"));
            }
            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {}
        }
    }
}

fn plugin_fault(message: impl Into<String>) -> SmithError {
    SmithError::Provider {
        fault: ProviderFault::Plugin {
            message: message.into(),
        },
    }
}

#[cfg(test)]
mod tests {
    //! Provider bridge bounds (`SMH-SPEC-PLUG0001`).

    use super::*;
    use crate::wasm::bindings::exports::smith::plugin::provider::{
        CatalogModel, CatalogSource, ModelCapabilities, SettingsProvenance,
    };

    #[test]
    fn cancellation_does_not_discard_genuine_provider_failure() {
        let (sender, receiver) = std::sync::mpsc::sync_channel(1);
        let cancel = CancelHandle::new();
        cancel.cancel();
        let error = plugin_fault("genuine provider failure");
        send_item(&sender, Err(error.clone()), &cancel).unwrap();
        assert_eq!(
            receiver
                .recv_timeout(std::time::Duration::from_secs(1))
                .unwrap(),
            Err(error)
        );
    }

    #[test]
    fn non_success_response_reports_sanitized_normalized_vendor_error() {
        let credential = "raw-secret".to_string();
        let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
            std::slice::from_ref(&credential),
            b"{{secret:connection-api-key}}",
        )
        .unwrap();
        let (sender, body) = std::sync::mpsc::sync_channel(2);
        sender
            .send(HttpBodyItem::Chunk(smith::http::HttpChunk {
                bytes: br#"{"error":{"code":"rate_limited","message":"wait\nraw-secret"}}"#
                    .to_vec(),
            }))
            .unwrap();
        sender
            .send(HttpBodyItem::End(HttpBodyEnd::Complete))
            .unwrap();
        drop(sender);

        let (response_bytes, outcome, error) =
            non_success_response(429, body, &CancelHandle::new(), &mut sanitizer);

        assert_eq!(response_bytes, 62);
        assert_eq!(outcome, ProviderEffectOutcome::Failed);
        assert_eq!(
            error.to_string(),
            "provider: plugin: provider returned HTTP 429: rate_limited: wait {{secret:connection-api-key}}"
        );
        assert!(!error.to_string().contains("raw-secret"));
        assert!(!error.to_string().contains('\n'));
    }

    #[test]
    fn non_success_response_preserves_known_status_over_cancellation() {
        for end in [HttpBodyEnd::Complete, HttpBodyEnd::Cancelled] {
            let credential = "raw-secret".to_string();
            let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
                std::slice::from_ref(&credential),
                b"{{secret:connection-api-key}}",
            )
            .unwrap();
            let (sender, body) = std::sync::mpsc::sync_channel(2);
            sender
                .send(HttpBodyItem::Chunk(smith::http::HttpChunk {
                    bytes: br#"{\"error\":{\"message\":\"raw-secret\"}}"#.to_vec(),
                }))
                .unwrap();
            sender.send(HttpBodyItem::End(end)).unwrap();
            drop(sender);
            let cancel = CancelHandle::new();
            cancel.cancel();

            let (response_bytes, outcome, error) =
                non_success_response(429, body, &cancel, &mut sanitizer);

            assert_eq!(response_bytes, 40);
            assert_eq!(outcome, ProviderEffectOutcome::Failed);
            assert_eq!(
                error.to_string(),
                "provider: plugin: provider returned HTTP 429"
            );
        }
    }

    #[test]
    fn non_success_response_sanitizes_split_raw_and_json_escaped_credentials() {
        let credential = "raw-secret".to_string();
        let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
            std::slice::from_ref(&credential),
            b"{{secret:connection-api-key}}",
        )
        .unwrap();
        let response = br#"{"error":{"message":"raw-secret|\u0072aw-\u0073ecret|\u00e9|\uD83D\uDE00|\u0001done"}}"#;
        let (sender, body) = std::sync::mpsc::channel();
        for bytes in response.chunks(1) {
            sender
                .send(HttpBodyItem::Chunk(smith::http::HttpChunk {
                    bytes: bytes.to_vec(),
                }))
                .unwrap();
        }
        sender
            .send(HttpBodyItem::End(HttpBodyEnd::Complete))
            .unwrap();
        drop(sender);

        let (_, outcome, error) =
            non_success_response(429, body, &CancelHandle::new(), &mut sanitizer);

        assert_eq!(outcome, ProviderEffectOutcome::Failed);
        assert_eq!(
            error.to_string(),
            "provider: plugin: provider returned HTTP 429: {{secret:connection-api-key}}|{{secret:connection-api-key}}|é|😀| done"
        );
        assert!(!error.to_string().contains("raw-secret"));
        assert!(!error.to_string().contains(r"\u0072aw-\u0073ecret"));
    }

    #[test]
    fn non_success_response_normalizes_diagnostics_at_and_over_the_output_cap() {
        for message_length in [
            PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX,
            PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX + 1,
        ] {
            let credential = "raw-secret".to_string();
            let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
                std::slice::from_ref(&credential),
                b"{{secret:connection-api-key}}",
            )
            .unwrap();
            let body_bytes = format!(
                r#"{{"error":{{"message":"{}"}}}}"#,
                "a".repeat(message_length)
            );
            let (sender, body) = std::sync::mpsc::sync_channel(2);
            sender
                .send(HttpBodyItem::Chunk(smith::http::HttpChunk {
                    bytes: body_bytes.into_bytes(),
                }))
                .unwrap();
            sender
                .send(HttpBodyItem::End(HttpBodyEnd::Complete))
                .unwrap();
            drop(sender);

            let (_, outcome, error) =
                non_success_response(429, body, &CancelHandle::new(), &mut sanitizer);

            assert_eq!(outcome, ProviderEffectOutcome::Failed);
            assert_eq!(
                error.to_string(),
                format!(
                    "provider: plugin: provider returned HTTP 429: {}",
                    "a".repeat(PROVIDER_ERROR_DIAGNOSTIC_BYTES_MAX)
                )
            );
        }
    }

    #[test]
    fn non_success_response_falls_back_to_status_for_unusable_bodies() {
        for body in [b"".as_slice(), b"<html>busy</html>", b"\xff"] {
            assert_eq!(
                provider_status_error(429, body).to_string(),
                "provider: plugin: provider returned HTTP 429"
            );
        }
    }

    #[test]
    fn non_success_response_bounds_json_capture_before_parsing() {
        let credential = "raw-secret".to_string();
        let mut sanitizer = crate::response_sanitizer::ResponseSanitizer::new(
            std::slice::from_ref(&credential),
            b"{{secret:connection-api-key}}",
        )
        .unwrap();
        let body_bytes =
            format!(r#"{{"error":{{"message":"{}"}}}}"#, "a".repeat(16 * 1024)).into_bytes();
        let (sender, body) = std::sync::mpsc::sync_channel(2);
        sender
            .send(HttpBodyItem::Chunk(smith::http::HttpChunk {
                bytes: body_bytes,
            }))
            .unwrap();
        sender
            .send(HttpBodyItem::End(HttpBodyEnd::Complete))
            .unwrap();
        drop(sender);

        let (_, outcome, error) =
            non_success_response(429, body, &CancelHandle::new(), &mut sanitizer);

        assert_eq!(outcome, ProviderEffectOutcome::Failed);
        assert_eq!(
            error.to_string(),
            "provider: plugin: provider returned HTTP 429"
        );
    }

    #[test]
    fn provider_effect_outcome_follows_returned_error_not_cancel_flag() {
        assert_eq!(
            outcome_for(&plugin_fault("malformed provider tool input")),
            ProviderEffectOutcome::Failed
        );
        assert_eq!(
            outcome_for(&SmithError::Cancelled),
            ProviderEffectOutcome::Cancelled
        );
    }

    fn test_settings(include_usage: bool) -> ProviderSettings {
        ProviderSettings {
            include_usage,
            subscription: false,
            provenance: SettingsProvenance::BuiltIn,
        }
    }

    fn test_catalog() -> CatalogSnapshot {
        CatalogSnapshot {
            generation: 7,
            source: CatalogSource::Cache,
            models: vec![CatalogModel {
                id: "glm-4".to_string(),
                capabilities: ModelCapabilities {
                    output_tokens_max: 8192,
                    tool_use: true,
                    thinking: false,
                },
            }],
        }
    }

    #[test]
    fn subscription_catalog_intent_records_only_headers_actually_sent() {
        let (records, drain) = smith::provider::record_channel();
        let provider = ProtocolConnectionConfig {
            connection_id: "openai-chatgpt-plan",
            protocol: ProtocolComponent::OpenAiCompatible,
            artifact: None,
            endpoint: "https://api.openai.com".into(),
            template_url: "https://protocol.invalid/responses",
            credential_header: "Authorization",
            credential_prefix: "Bearer ",
            static_headers: &[],
            connection: ProtocolConnection::Api,
            request_path: "/v1/responses".into(),
            credential: CredentialReference::explicit("test-credential").into(),
            auth_store: AuthStore::at(std::env::temp_dir()),
            executor: crate::http::default_executor(),
            records,
            intent_admission_timeout: std::time::Duration::from_secs(1),
            settings: ProviderSettings {
                include_usage: true,
                subscription: false,
                provenance: SettingsProvenance::BuiltIn,
            },
            catalog: CatalogSnapshot {
                generation: 0,
                source: CatalogSource::Bundled,
                models: Vec::new(),
            },
        };
        let exchange = authorize_template(
            provider.template_url,
            "Bearer {{secret:connection-api-key}}",
            "{}".into(),
            &provider,
        )
        .unwrap();
        let _admission = admit_dispatch_with_mode(
            &provider,
            &exchange,
            ProviderDispatchProvenance {
                registration_binding: None,
                connection_id: provider.connection_id.into(),
                protocol_manifest_id: "smith:protocol-openai-responses".into(),
                protocol_component_sha256: "b".repeat(64),
                catalog_generation: 0,
                catalog_source: ProviderCatalogSource::Bundled,
                settings: settings_record(provider.settings),
                credential_binding: None,
            },
            true,
        )
        .unwrap();
        let recorded: Vec<_> = drain.try_iter().collect();
        assert_eq!(recorded.len(), 2);
        let ProviderEffectRecord::Intent {
            method,
            url,
            headers,
            request_bytes,
        } = recorded[0].record()
        else {
            panic!("missing catalog intent")
        };
        assert_eq!(*method, HttpMethod::Get);
        assert_eq!(url, "https://api.openai.com/v1/models");
        assert_eq!(*request_bytes, 0);
        assert_eq!(headers.len(), 1);
        assert_eq!(headers[0].name, "Authorization");
        let ProviderEffectRecord::Intent {
            method, headers, ..
        } = recorded[1].record()
        else {
            panic!("missing inference intent")
        };
        assert_eq!(*method, HttpMethod::Post);
        assert_eq!(headers.len(), 2);
    }

    #[test]
    fn request_template_body_over_codec_bound_is_rejected_before_authorization() {
        let (records, _drain) = smith::provider::record_channel();
        let provider = ProtocolConnectionConfig {
            connection_id: "test-api",
            protocol: ProtocolComponent::OpenAiCompatible,
            artifact: None,
            endpoint: "https://api.z.ai".to_string(),
            template_url: OPENAI_COMPATIBLE_TEMPLATE_URL,
            credential_header: "Authorization",
            credential_prefix: "Bearer ",
            static_headers: &[],
            connection: ProtocolConnection::Api,
            request_path: ProtocolConnection::Api.request_path().to_string(),
            credential: CredentialReference::explicit("must-not-cross-template-boundary").into(),
            auth_store: AuthStore::at(std::env::temp_dir()),
            executor: crate::http::default_executor(),
            records,
            intent_admission_timeout: std::time::Duration::from_secs(1),
            settings: test_settings(true),
            catalog: test_catalog(),
        };
        let body = "x".repeat(CODEC_BODY_BYTES_MAX + 1);

        let error = authorize_template(
            OPENAI_COMPATIBLE_TEMPLATE_URL,
            "Bearer {{secret:connection-api-key}}",
            body,
            &provider,
        )
        .unwrap_err();

        assert!(error.to_string().contains("request exceeds"));
    }

    #[test]
    fn loopback_override_rejects_non_literal_authorities_and_suffixes() {
        let (records, _drain) = smith::provider::record_channel();
        let mut provider = ProtocolConnectionConfig {
            connection_id: "test-api",
            protocol: ProtocolComponent::OpenAiCompatible,
            artifact: None,
            endpoint: String::new(),
            template_url: OPENAI_COMPATIBLE_TEMPLATE_URL,
            credential_header: "Authorization",
            credential_prefix: "Bearer ",
            static_headers: &[],
            connection: ProtocolConnection::Api,
            request_path: ProtocolConnection::Api.request_path().to_string(),
            credential: CredentialReference::explicit("must-not-cross-host-boundary").into(),
            auth_store: AuthStore::at(std::env::temp_dir()),
            executor: crate::http::default_executor(),
            records,
            intent_admission_timeout: std::time::Duration::from_secs(1),
            settings: test_settings(true),
            catalog: test_catalog(),
        };

        for endpoint in [
            "http://127.0.0.1:80@evil.example",
            "http://127.0.0.1:8080/path",
            "http://127.0.0.1:8080?query",
            "http://127.0.0.1:8080#fragment",
            "http://127.0.0.1:not-a-port",
            "http://127.0.0.1:65536",
            "http://127.0.0.1:",
        ] {
            provider.endpoint = endpoint.to_string();
            let error = authorize_template(
                OPENAI_COMPATIBLE_TEMPLATE_URL,
                "Bearer {{secret:connection-api-key}}",
                String::new(),
                &provider,
            )
            .unwrap_err();

            assert!(
                error.to_string().contains("network scope"),
                "endpoint {endpoint:?} must be rejected"
            );
        }
    }

    #[test]
    fn loopback_override_accepts_literal_ipv4_and_trailing_slash() {
        let (records, _drain) = smith::provider::record_channel();
        let mut provider = ProtocolConnectionConfig {
            connection_id: "test-api",
            protocol: ProtocolComponent::OpenAiCompatible,
            artifact: None,
            endpoint: "http://127.0.0.1:8080/".to_string(),
            template_url: OPENAI_COMPATIBLE_TEMPLATE_URL,
            credential_header: "Authorization",
            credential_prefix: "Bearer ",
            static_headers: &[],
            connection: ProtocolConnection::Api,
            request_path: ProtocolConnection::Api.request_path().to_string(),
            credential: CredentialReference::explicit("test-credential").into(),
            auth_store: AuthStore::at(std::env::temp_dir()),
            executor: crate::http::default_executor(),
            records,
            intent_admission_timeout: std::time::Duration::from_secs(1),
            settings: test_settings(true),
            catalog: test_catalog(),
        };

        let exchange = authorize_template(
            OPENAI_COMPATIBLE_TEMPLATE_URL,
            "Bearer {{secret:connection-api-key}}",
            String::new(),
            &provider,
        )
        .unwrap();
        assert_eq!(
            exchange.url,
            "http://127.0.0.1:8080/api/paas/v4/chat/completions"
        );

        provider.endpoint = "http://127.0.0.1:8080".to_string();
        assert!(
            authorize_template(
                OPENAI_COMPATIBLE_TEMPLATE_URL,
                "Bearer {{secret:connection-api-key}}",
                String::new(),
                &provider,
            )
            .is_ok()
        );
    }

    #[test]
    fn billing_connections_keep_distinct_authorized_paths() {
        assert_eq!(
            ProtocolConnection::Api.request_path(),
            "/api/paas/v4/chat/completions"
        );
        assert_eq!(
            ProtocolConnection::CodingPlan.request_path(),
            "/api/coding/paas/v4/chat/completions"
        );
    }

    #[test]
    fn unsupported_blocks_are_rejected_before_guest_dispatch() {
        let mut thinking_message = smith::message::Message::new(Role::Assistant);
        thinking_message.add_block(ContentBlock::thinking("private"));
        let thinking = ProviderRequest::new("model", vec![thinking_message]);
        assert!(build_messages(&thinking).is_err());

        let call_id = smith::id::ToolCallId::new();
        let mut assistant = smith::message::Message::new(Role::Assistant);
        assistant.add_block(ContentBlock::tool_use(
            "write",
            smith::structured::ToolArguments::empty_object(),
            call_id,
        ));
        let mut tool_message = smith::message::Message::new(Role::Tool);
        tool_message.add_block(ContentBlock::tool_result(call_id, true, "done"));
        let mut tool_result = ProviderRequest::new("model", vec![assistant, tool_message]);
        tool_result
            .provider_call_ids
            .insert(call_id, "call-1".to_string());
        assert!(build_messages(&tool_result).is_ok());
    }

    #[test]
    fn effective_catalog_rejects_requests_before_guest_or_network() {
        let mut request = ProviderRequest::new("glm-4", Vec::new())
            .with_tools(vec![smith::tool::ToolMetadata::new("read", "Read a file")]);
        let mut catalog = test_catalog();
        catalog.models[0].capabilities.tool_use = false;
        let error = validate_effective_request(&request, &catalog).unwrap_err();
        assert!(error.to_string().contains("tool definitions"));

        request.tools = std::sync::Arc::new([]);
        request.params.output_tokens_max = Some(8193);
        let error = validate_effective_request(&request, &test_catalog()).unwrap_err();
        assert!(error.to_string().contains("output tokens"));

        request.params.output_tokens_max = Some(8192);
        assert!(validate_effective_request(&request, &test_catalog()).is_ok());
    }

    #[test]
    fn protocol_components_use_matching_manifest_identities() {
        assert_eq!(
            ProtocolComponent::OpenAiCompatible.manifest().unwrap().id(),
            "smith:protocol-openai-compatible"
        );
        assert_eq!(
            ProtocolComponent::Anthropic.manifest().unwrap().id(),
            "smith:protocol-anthropic"
        );
        assert_eq!(
            ProtocolComponent::Google.manifest().unwrap().id(),
            "smith:protocol-google"
        );
    }

    #[test]
    fn supported_binding_rejects_disabled_typed_protocol_settings() {
        assert!(protocol_settings_supported(test_settings(true)));
        assert!(!protocol_settings_supported(test_settings(false)));
    }

    #[test]
    fn response_body_over_codec_bound_is_rejected_before_guest_decode() {
        let mut bytes = Vec::new();
        bytes.resize(CODEC_BODY_BYTES_MAX, b'x');

        let error = append_response_bytes(&mut bytes, b"x").unwrap_err();

        assert!(error.to_string().contains("response exceeds"));
    }
}