Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
47.7 KB
Raw Blame
//! GitHub Copilot provider.
//!
//! Copilot is not an OpenAI-compatible API-key provider. The stable auth chain
//! is GitHub user token -> `/copilot_internal/v2/token` -> short-lived Copilot
//! bearer token -> Copilot chat completions, with the same integration headers
//! used by Copilot Chat clients.

use std::path::Path;
use std::time::Duration;

use async_trait::async_trait;
use secrecy::{ExposeSecret as _, SecretString};
use serde::{Deserialize, Serialize};
use tokio::sync::Mutex;
use tracing::{debug, info, warn};

use crate::auth::CopilotAuth;
use crate::auth_file::{load_entry, now_ms, save_entry};
use crate::embedding::{
    Embedder, OPENAI_EMBED_MAX_TOKENS, normalise, parse_openai_embedding_values, retry_delay,
};
use crate::error::{LlmError, LlmResult};
use crate::openai::{STRUCTURED_OUTPUT_SCHEMA_NAME, enforce_strict_object_schemas};
use crate::openai_oauth::model_uses_default_temperature;
use crate::provider::LlmProvider;
use crate::response::{provider_error, response_json_limited, response_text_limited};
use crate::text::truncate_for_embedding;
use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, Usage};

/// GitHub Copilot's public OAuth client id used by Copilot clients.
pub const GITHUB_COPILOT_CLIENT_ID: &str = "Iv1.b507a08c87ecfe98";

/// GitHub device-code endpoint.
pub const GITHUB_DEVICE_CODE_URL: &str = "https://github.com/login/device/code";

/// GitHub OAuth token endpoint.
pub const GITHUB_ACCESS_TOKEN_URL: &str = "https://github.com/login/oauth/access_token";

/// GitHub endpoint that exchanges a GitHub user token for a Copilot API token.
pub const GITHUB_COPILOT_TOKEN_URL: &str = "https://api.github.com/copilot_internal/v2/token";

/// Default Copilot chat API base when a token does not advertise `proxy-ep`.
pub const DEFAULT_COPILOT_API_BASE_URL: &str = "https://api.githubcopilot.com";

/// Copilot integration id for chat requests and token exchange.
pub const COPILOT_INTEGRATION_ID: &str = "vscode-chat";

/// VS Code-like editor version header expected by Copilot endpoints.
pub const COPILOT_EDITOR_VERSION: &str = "vscode/1.107.0";

/// VS Code-like plugin version header expected by Copilot endpoints.
pub const COPILOT_EDITOR_PLUGIN_VERSION: &str = "copilot-chat/0.35.0";

/// VS Code Copilot Chat user agent.
pub const COPILOT_USER_AGENT: &str = "GitHubCopilotChat/0.35.0";

/// GitHub API version used for the token exchange endpoint.
pub const COPILOT_GITHUB_API_VERSION: &str = "2025-04-01";

const COPILOT_REFRESH_MARGIN_MS: u64 = 120_000;

/// Stored GitHub Copilot auth state.
#[derive(Clone, Default)]
pub struct CopilotToken {
    /// Long-lived GitHub user token used for Copilot token exchange.
    pub github_access: Option<SecretString>,
    /// Optional GitHub token expiry in milliseconds since Unix epoch.
    pub github_expires_at_ms: Option<u64>,
    /// Cached short-lived Copilot API token.
    pub copilot_access: Option<SecretString>,
    /// Copilot API token expiry in milliseconds since Unix epoch.
    pub copilot_expires_at_ms: Option<u64>,
    /// Cached/derived Copilot API base URL.
    pub api_base_url: Option<String>,
}

impl std::fmt::Debug for CopilotToken {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CopilotToken")
            .field(
                "github_access",
                &self.github_access.as_ref().map(|_| "<redacted>"),
            )
            .field("github_expires_at_ms", &self.github_expires_at_ms)
            .field(
                "copilot_access",
                &self.copilot_access.as_ref().map(|_| "<redacted>"),
            )
            .field("copilot_expires_at_ms", &self.copilot_expires_at_ms)
            .field("api_base_url", &self.api_base_url)
            .finish()
    }
}

impl CopilotToken {
    /// Build stored auth from a GitHub user token.
    #[must_use]
    pub fn from_github_token(token: impl Into<String>, expires_at_ms: Option<u64>) -> Self {
        Self {
            github_access: Some(SecretString::from(token.into())),
            github_expires_at_ms: expires_at_ms,
            ..Self::default()
        }
    }

    fn cached_copilot_token(&self) -> Option<CopilotApiToken> {
        let access = self.copilot_access.as_ref()?;
        let expires_at_ms = self.copilot_expires_at_ms?;
        if now_ms().saturating_add(COPILOT_REFRESH_MARGIN_MS) >= expires_at_ms {
            return None;
        }
        Some(CopilotApiToken {
            access: access.clone(),
            expires_at_ms,
            base_url: self
                .api_base_url
                .clone()
                .unwrap_or_else(|| DEFAULT_COPILOT_API_BASE_URL.into()),
        })
    }

    /// True when a GitHub token is available and not known to be expired.
    #[must_use]
    pub fn has_refreshable_github_token(&self) -> bool {
        let Some(_token) = self.github_access.as_ref() else {
            return false;
        };
        self.github_expires_at_ms
            .is_none_or(|expires| now_ms().saturating_add(COPILOT_REFRESH_MARGIN_MS) < expires)
    }

    /// True when the cached Copilot API token is still usable without refresh.
    #[must_use]
    pub fn has_valid_cached_copilot_token(&self) -> bool {
        self.cached_copilot_token().is_some()
    }

    /// Load the Copilot token from a shared auth file.
    ///
    /// # Errors
    /// Returns [`LlmError::Auth`] when the file exists but cannot be read or
    /// parsed.
    pub fn load(path: &Path) -> LlmResult<Option<Self>> {
        let Some(entry) = load_entry::<CopilotEntry>(path, "copilot")? else {
            return Ok(None);
        };
        Ok(Some(Self {
            github_access: entry.github_access.map(SecretString::from),
            github_expires_at_ms: entry.github_expires,
            copilot_access: entry.copilot_access.map(SecretString::from),
            copilot_expires_at_ms: entry.copilot_expires,
            api_base_url: entry.api_base_url,
        }))
    }

    /// Save the token into the shared auth file, preserving unknown keys.
    ///
    /// # Errors
    /// Returns [`LlmError::Auth`] when the file cannot be written.
    pub fn save(&self, path: &Path) -> LlmResult<()> {
        let entry = CopilotEntry {
            kind: "oauth".into(),
            github_access: self
                .github_access
                .as_ref()
                .map(|s| s.expose_secret().to_string()),
            github_expires: self.github_expires_at_ms,
            copilot_access: self
                .copilot_access
                .as_ref()
                .map(|s| s.expose_secret().to_string()),
            copilot_expires: self.copilot_expires_at_ms,
            api_base_url: self.api_base_url.clone(),
        };
        save_entry(path, "copilot", Some(entry))
    }

    /// Remove the Copilot entry from the shared auth file.
    ///
    /// # Errors
    /// Returns [`LlmError::Auth`] when the file cannot be updated.
    pub fn remove(path: &Path) -> LlmResult<()> {
        save_entry::<CopilotEntry>(path, "copilot", None)
    }
}

/// Shared Copilot token-resolution state: the GitHub->Copilot token exchange,
/// cache, and persistence used by every Copilot-backed client (chat
/// completions, embeddings). Factored out so both clients call the exact
/// same `exchange_copilot_token` / `resolve_copilot_api_base_url` path
/// instead of duplicating the auth chain.
struct CopilotAuthState {
    client: reqwest::Client,
    auth: CopilotAuth,
    stored: Mutex<CopilotToken>,
    timeout: Duration,
}

impl CopilotAuthState {
    fn new(auth: CopilotAuth) -> LlmResult<Self> {
        let stored = CopilotToken::load(&auth.token_file)?.unwrap_or_default();
        if auth.direct_api_token.is_none()
            && auth.github_token.is_none()
            && stored.github_access.is_none()
            && stored.cached_copilot_token().is_none()
        {
            return Err(LlmError::NotConfigured(format!(
                "no copilot auth found at {}; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN",
                auth.token_file.display()
            )));
        }
        let client = reqwest::Client::builder()
            .redirect(crate::redirect::same_origin_redirects())
            .user_agent(COPILOT_USER_AGENT)
            .build()
            .map_err(LlmError::from)?;
        Ok(Self {
            client,
            auth,
            stored: Mutex::new(stored),
            timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
        })
    }

    async fn current_token(&self) -> LlmResult<CopilotApiToken> {
        if let Some(token) = self.auth.direct_api_token.as_ref() {
            return Ok(CopilotApiToken {
                access: token.clone(),
                expires_at_ms: u64::MAX,
                base_url: resolve_copilot_api_base_url(
                    self.auth.api_base_url.as_deref(),
                    token.expose_secret(),
                ),
            });
        }

        let mut guard = self.stored.lock().await;
        if let Some(mut cached) = guard.cached_copilot_token() {
            if let Some(url) = self.auth.api_base_url.clone() {
                cached.base_url = url;
            }
            return Ok(cached);
        }

        let github = self
            .auth
            .github_token
            .clone()
            .or_else(|| guard.github_access.clone())
            .ok_or_else(|| {
                LlmError::NotConfigured(
                    "copilot GitHub token missing; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN"
                        .into(),
                )
            })?;

        info!("copilot API token expired or missing, exchanging GitHub token");
        let exchanged = exchange_copilot_token(
            &self.client,
            self.timeout,
            &github,
            GITHUB_COPILOT_TOKEN_URL,
        )
        .await?;
        guard.copilot_access = Some(exchanged.access.clone());
        guard.copilot_expires_at_ms = Some(exchanged.expires_at_ms);
        guard.api_base_url = Some(resolve_copilot_api_base_url(
            self.auth.api_base_url.as_deref(),
            exchanged.access.expose_secret(),
        ));
        guard.save(&self.auth.token_file)?;

        Ok(CopilotApiToken {
            access: exchanged.access,
            expires_at_ms: exchanged.expires_at_ms,
            base_url: guard
                .api_base_url
                .clone()
                .unwrap_or_else(|| DEFAULT_COPILOT_API_BASE_URL.into()),
        })
    }
}

/// Copilot provider backed by Copilot chat completions.
pub struct CopilotProvider {
    model: String,
    state: CopilotAuthState,
    extra_headers: ExtraHeaders,
    endpoint: Mutex<Option<CopilotEndpoint>>,
}

impl CopilotProvider {
    /// Build a provider from resolved Copilot auth inputs.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] when no GitHub/direct token is
    /// available.
    pub fn new(auth: CopilotAuth, model: impl Into<String>) -> LlmResult<Self> {
        Ok(Self {
            model: model.into(),
            state: CopilotAuthState::new(auth)?,
            extra_headers: ExtraHeaders::default(),
            endpoint: Mutex::new(None),
        })
    }

    /// Override the per-request timeout (default
    /// [`crate::DEFAULT_REQUEST_TIMEOUT_SECS`]). Also bounds the
    /// GitHub token-exchange request.
    #[must_use]
    pub fn with_timeout_secs(mut self, secs: u64) -> Self {
        self.state.timeout = Duration::from_secs(secs);
        self
    }

    /// Attach operator-configured headers to every chat request. The factory
    /// calls this with `ProviderConfig::extra_headers`. Replaces the client's
    /// default `user-agent` when the operator configures one.
    #[must_use]
    pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {
        self.extra_headers = headers;
        self
    }

    async fn endpoint(&self, token: &CopilotApiToken) -> LlmResult<CopilotEndpoint> {
        let mut cached = self.endpoint.lock().await;
        if let Some(endpoint) = *cached {
            return Ok(endpoint);
        }
        let url = format!("{}/models", token.base_url.trim_end_matches('/'));
        debug!(url = %url, model = %self.model, "GET copilot model capabilities");
        let request = self.extra_headers.apply(
            self.state
                .client
                .get(&url)
                .timeout(self.state.timeout)
                .bearer_auth(token.access.expose_secret())
                .headers(copilot_runtime_headers()),
        );
        let response = request.send().await.map_err(LlmError::from)?;
        let status = response.status();
        // Do not make a transient or unavailable metadata endpoint break the
        // long-standing Chat Completions path. A successful metadata response,
        // however, is authoritative about this model's available endpoints.
        if !status.is_success() {
            debug!(%status, model = %self.model, "copilot model metadata unavailable; using chat completions");
            return Ok(CopilotEndpoint::ChatCompletions);
        }
        let metadata = response_json_limited::<CopilotModelsResponse>(response).await?;
        let Some(model) = metadata
            .data
            .into_iter()
            .find(|entry| entry.id == self.model)
        else {
            // A configured model that the catalogue does not enumerate
            // (enterprise/custom deployments, aliases, casing, a model newer
            // than this list) reached Chat Completions directly before this
            // metadata check existed. Keep that backward-compatible path rather
            // than hard-erroring; only models the catalogue lists as
            // Responses-only route through `/responses`.
            warn!(
                model = %self.model,
                "copilot model not found in /models catalogue; using chat completions"
            );
            *cached = Some(CopilotEndpoint::ChatCompletions);
            return Ok(CopilotEndpoint::ChatCompletions);
        };
        let endpoint = CopilotEndpoint::from_supported(&model.supported_endpoints).ok_or_else(|| {
            LlmError::UnexpectedShape(format!(
                "copilot model {:?} has no supported completion endpoint; advertised endpoints: {:?}",
                self.model, model.supported_endpoints
            ))
        })?;
        *cached = Some(endpoint);
        Ok(endpoint)
    }

    async fn post_chat(
        &self,
        token: &CopilotApiToken,
        body: &CopilotChatRequest<'_>,
    ) -> LlmResult<CopilotChatResponse> {
        let url = format!("{}/chat/completions", token.base_url.trim_end_matches('/'));
        debug!(url = %url, "POST copilot chat completions");
        let request = self.extra_headers.apply(
            self.state
                .client
                .post(&url)
                .timeout(self.state.timeout)
                .bearer_auth(token.access.expose_secret())
                .headers(copilot_runtime_headers()),
        );
        let resp = request.json(body).send().await.map_err(LlmError::from)?;
        if !resp.status().is_success() {
            return Err(provider_error(resp).await);
        }
        response_json_limited::<CopilotChatResponse>(resp).await
    }

    async fn post_responses(
        &self,
        token: &CopilotApiToken,
        body: &CopilotResponsesRequest<'_>,
    ) -> LlmResult<CopilotResponsesResponse> {
        let url = format!("{}/responses", token.base_url.trim_end_matches('/'));
        debug!(url = %url, "POST copilot responses");
        let request = self.extra_headers.apply(
            self.state
                .client
                .post(&url)
                .timeout(self.state.timeout)
                .bearer_auth(token.access.expose_secret())
                .headers(copilot_runtime_headers()),
        );
        let resp = request.json(body).send().await.map_err(LlmError::from)?;
        if !resp.status().is_success() {
            return Err(provider_error(resp).await);
        }
        response_json_limited::<CopilotResponsesResponse>(resp).await
    }
}

#[async_trait]
impl LlmProvider for CopilotProvider {
    fn name(&self) -> &'static str {
        "copilot"
    }

    fn model(&self) -> &str {
        &self.model
    }

    async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
        let token = self.state.current_token().await?;
        match self.endpoint(&token).await? {
            CopilotEndpoint::ChatCompletions => to_chat_response(
                self.post_chat(&token, &build_chat_request(&self.model, &request, None))
                    .await?,
            ),
            CopilotEndpoint::Responses => Ok(to_responses_chat_response(
                self.post_responses(
                    &token,
                    &build_responses_request(&self.model, &request, None),
                )
                .await?,
                &self.model,
            )?),
        }
    }

    async fn complete_structured_raw(
        &self,
        request: ChatRequest,
        mut schema: serde_json::Value,
    ) -> LlmResult<serde_json::Value> {
        enforce_strict_object_schemas(&mut schema);
        let token = self.state.current_token().await?;
        let text = match self.endpoint(&token).await? {
            CopilotEndpoint::ChatCompletions => self
                .post_chat(
                    &token,
                    &build_chat_request(
                        &self.model,
                        &request,
                        Some(CopilotResponseFormat::JsonSchema {
                            json_schema: CopilotJsonSchema {
                                name: STRUCTURED_OUTPUT_SCHEMA_NAME.into(),
                                schema,
                                strict: true,
                            },
                        }),
                    ),
                )
                .await?
                .choices
                .first()
                .and_then(|c| c.message.content.as_deref())
                .filter(|text| !text.is_empty())
                .ok_or_else(|| {
                    LlmError::UnexpectedShape(
                        "copilot /chat/completions returned no structured content".into(),
                    )
                })?
                .to_owned(),
            CopilotEndpoint::Responses => response_text(
                &self
                    .post_responses(
                        &token,
                        &build_responses_request(&self.model, &request, Some(schema)),
                    )
                    .await?,
                &self.model,
            )?,
        };
        serde_json::from_str::<serde_json::Value>(&text).map_err(LlmError::from)
    }
}

#[derive(Debug, Clone)]
struct CopilotApiToken {
    access: SecretString,
    expires_at_ms: u64,
    base_url: String,
}

/// Default embedding model requested from Copilot's `/embeddings` endpoint.
pub const COPILOT_DEFAULT_EMBED_MODEL: &str = "text-embedding-3-small";

/// Default vector dimensionality for [`COPILOT_DEFAULT_EMBED_MODEL`].
pub const COPILOT_DEFAULT_EMBED_DIM: u32 = 1536;

#[derive(Debug, Serialize)]
struct CopilotEmbeddingRequest<'a> {
    input: &'a str,
    model: &'a str,
}

/// GitHub Copilot embedder.
///
/// **Caveat:** the Copilot `/embeddings` endpoint path and wire shape are
/// taken from the OpenAI-compatible contract Copilot documents for chat and
/// from prior art in other Copilot clients (openclaw#61717), not from a live
/// test against Copilot here — GitHub does not publish a dedicated
/// embeddings spec. Default model [`COPILOT_DEFAULT_EMBED_MODEL`]
/// (`text-embedding-3-small`) and dim [`COPILOT_DEFAULT_EMBED_DIM`] (1536)
/// follow the same prior art. Reuses the identical GitHub-token ->
/// short-lived Copilot API token exchange as [`CopilotProvider`] via
/// [`CopilotAuthState`] — no separate exchange path.
pub struct CopilotEmbedder {
    state: CopilotAuthState,
    model: String,
    dim: u32,
}

impl CopilotEmbedder {
    /// Build an embedder from resolved Copilot auth inputs.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] when no GitHub/direct token is
    /// available.
    pub fn new(auth: CopilotAuth, model: impl Into<String>, dim: u32) -> LlmResult<Self> {
        Ok(Self {
            state: CopilotAuthState::new(auth)?,
            model: model.into(),
            dim,
        })
    }

    /// Override the per-request timeout (default
    /// [`crate::DEFAULT_REQUEST_TIMEOUT_SECS`]).
    #[must_use]
    pub fn with_timeout_secs(mut self, secs: u64) -> Self {
        self.state.timeout = Duration::from_secs(secs);
        self
    }
}

#[async_trait]
impl Embedder for CopilotEmbedder {
    fn provider(&self) -> &'static str {
        "copilot"
    }

    fn model(&self) -> &str {
        &self.model
    }

    fn dim(&self) -> u32 {
        self.dim
    }

    async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
        let token = self.state.current_token().await?;
        let input = truncate_for_embedding(text, OPENAI_EMBED_MAX_TOKENS);
        let url = format!("{}/embeddings", token.base_url.trim_end_matches('/'));
        debug!(url = %url, model = %self.model, "POST copilot embeddings");
        let req = CopilotEmbeddingRequest {
            input: &input,
            model: &self.model,
        };
        let mut attempt = 0u32;
        let mut waited = Duration::ZERO;
        loop {
            let resp = self
                .state
                .client
                .post(&url)
                .timeout(self.state.timeout)
                .bearer_auth(token.access.expose_secret())
                .headers(copilot_runtime_headers())
                .json(&req)
                .send()
                .await
                .map_err(LlmError::from)?;
            let status = resp.status();
            let retry_after = resp.headers().get(reqwest::header::RETRY_AFTER);
            if let Some(delay) = retry_delay(status, retry_after, attempt + 1, waited) {
                attempt += 1;
                waited += delay;
                debug!(
                    attempt,
                    ?delay,
                    status = status.as_u16(),
                    "copilot embeddings 429/503; retrying"
                );
                tokio::time::sleep(delay).await;
                continue;
            }
            // Client errors (e.g. input too long) are not retried.
            if status.as_u16() == 400 {
                return Err(provider_error(resp).await);
            }
            if !status.is_success() {
                return Err(provider_error(resp).await);
            }
            let body = response_text_limited(resp).await?;
            let values = parse_openai_embedding_values(&body, status.as_u16())?;
            if values.len() as u32 != self.dim {
                return Err(LlmError::UnexpectedShape(format!(
                    "expected dim {}, got {}",
                    self.dim,
                    values.len()
                )));
            }
            return Ok(normalise(values));
        }
    }
}

#[derive(Debug, Deserialize)]
struct CopilotExchangeResponse {
    token: String,
    expires_at: u64,
}

async fn exchange_copilot_token(
    client: &reqwest::Client,
    timeout: Duration,
    github_token: &SecretString,
    token_url: &str,
) -> LlmResult<CopilotApiToken> {
    let resp = client
        .get(token_url)
        .timeout(timeout)
        .bearer_auth(github_token.expose_secret())
        .headers(copilot_token_exchange_headers())
        .send()
        .await
        .map_err(LlmError::from)?;
    let status = resp.status();
    if !status.is_success() {
        let error = provider_error(resp).await;
        let LlmError::Provider {
            body, retry_after, ..
        } = error
        else {
            return Err(error);
        };
        // GitHub rate-limits this endpoint per account. A 429/5xx here says
        // nothing about the credential, and `LlmError::Auth` is not transient,
        // so classifying it as auth stops the fallback chain and tells the
        // operator to fix a token that is fine.
        if LlmError::status_is_transient(status.as_u16()) {
            return Err(LlmError::Provider {
                status: status.as_u16(),
                body: format!("copilot token exchange: {body}"),
                retry_after,
            });
        }
        return Err(LlmError::Auth(format!(
            "copilot token exchange failed ({status}): {body}"
        )));
    }
    let exchanged = response_json_limited::<CopilotExchangeResponse>(resp).await?;
    let expires_at_ms = unix_epoch_to_ms(exchanged.expires_at);
    Ok(CopilotApiToken {
        base_url: derive_copilot_api_base_url_from_token(&exchanged.token)
            .unwrap_or_else(|| DEFAULT_COPILOT_API_BASE_URL.into()),
        access: SecretString::from(exchanged.token),
        expires_at_ms,
    })
}

fn build_chat_request<'a>(
    model: &'a str,
    request: &'a ChatRequest,
    response_format: Option<CopilotResponseFormat>,
) -> CopilotChatRequest<'a> {
    let mut messages = Vec::new();
    if let Some(sys) = request.system.as_deref() {
        messages.push(CopilotMsg {
            role: "system",
            content: sys,
        });
    }
    for m in &request.messages {
        messages.push(CopilotMsg {
            role: m.role.as_str(),
            content: &m.content,
        });
    }
    CopilotChatRequest {
        model,
        messages,
        max_tokens: Some(request.max_tokens),
        temperature: if model_uses_default_temperature(model) {
            None
        } else {
            request.temperature
        },
        stream: false,
        response_format,
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum CopilotEndpoint {
    ChatCompletions,
    Responses,
}

impl CopilotEndpoint {
    fn from_supported(endpoints: &[String]) -> Option<Self> {
        if endpoints
            .iter()
            .any(|endpoint| endpoint == "/chat/completions")
        {
            Some(Self::ChatCompletions)
        } else if endpoints.iter().any(|endpoint| endpoint == "/responses") {
            Some(Self::Responses)
        } else {
            None
        }
    }
}

#[derive(Debug, Deserialize)]
struct CopilotModelsResponse {
    #[serde(default)]
    data: Vec<CopilotModelMetadata>,
}

#[derive(Debug, Deserialize)]
struct CopilotModelMetadata {
    id: String,
    #[serde(default)]
    supported_endpoints: Vec<String>,
}

fn build_responses_request<'a>(
    model: &'a str,
    request: &'a ChatRequest,
    schema: Option<serde_json::Value>,
) -> CopilotResponsesRequest<'a> {
    CopilotResponsesRequest {
        model,
        instructions: request.system.as_deref(),
        input: request
            .messages
            .iter()
            .map(|message| CopilotResponsesInput {
                kind: "message",
                role: message.role.as_str(),
                content: vec![CopilotResponsesInputText {
                    kind: "input_text",
                    text: &message.content,
                }],
            })
            .collect(),
        max_output_tokens: request.max_tokens,
        temperature: (!model_uses_default_temperature(model))
            .then_some(request.temperature)
            .flatten(),
        store: false,
        stream: false,
        text: schema.map(|schema| CopilotResponsesText {
            format: CopilotResponsesTextFormat {
                kind: "json_schema",
                name: STRUCTURED_OUTPUT_SCHEMA_NAME,
                schema,
                strict: true,
            },
        }),
    }
}

#[derive(Debug, Serialize)]
struct CopilotResponsesRequest<'a> {
    model: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    instructions: Option<&'a str>,
    input: Vec<CopilotResponsesInput<'a>>,
    max_output_tokens: u32,
    #[serde(skip_serializing_if = "Option::is_none")]
    temperature: Option<f32>,
    store: bool,
    stream: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    text: Option<CopilotResponsesText>,
}

#[derive(Debug, Serialize)]
struct CopilotResponsesInput<'a> {
    #[serde(rename = "type")]
    kind: &'static str,
    role: &'a str,
    content: Vec<CopilotResponsesInputText<'a>>,
}

#[derive(Debug, Serialize)]
struct CopilotResponsesInputText<'a> {
    #[serde(rename = "type")]
    kind: &'static str,
    text: &'a str,
}

#[derive(Debug, Serialize)]
struct CopilotResponsesText {
    format: CopilotResponsesTextFormat,
}

#[derive(Debug, Serialize)]
struct CopilotResponsesTextFormat {
    #[serde(rename = "type")]
    kind: &'static str,
    name: &'static str,
    schema: serde_json::Value,
    strict: bool,
}

#[derive(Debug, Serialize)]
struct CopilotChatRequest<'a> {
    model: &'a str,
    messages: Vec<CopilotMsg<'a>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    max_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    temperature: Option<f32>,
    stream: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    response_format: Option<CopilotResponseFormat>,
}

#[derive(Debug, Serialize)]
struct CopilotMsg<'a> {
    role: &'a str,
    content: &'a str,
}

#[derive(Debug, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum CopilotResponseFormat {
    JsonSchema { json_schema: CopilotJsonSchema },
}

#[derive(Debug, Serialize)]
struct CopilotJsonSchema {
    name: String,
    schema: serde_json::Value,
    strict: bool,
}

#[derive(Debug, Deserialize)]
struct CopilotResponsesResponse {
    #[serde(default)]
    model: Option<String>,
    #[serde(default)]
    output_text: Option<String>,
    #[serde(default)]
    output: Vec<CopilotResponsesOutput>,
    #[serde(default)]
    usage: Option<CopilotResponsesUsage>,
    #[serde(default)]
    status: Option<String>,
    #[serde(default)]
    incomplete_details: Option<CopilotIncompleteDetails>,
    #[serde(default)]
    error: Option<CopilotResponsesError>,
}

#[derive(Debug, Deserialize)]
struct CopilotResponsesOutput {
    #[serde(rename = "type")]
    kind: String,
    #[serde(default)]
    content: Vec<CopilotResponsesContent>,
}

#[derive(Debug, Deserialize)]
struct CopilotResponsesContent {
    #[serde(rename = "type")]
    kind: String,
    #[serde(default)]
    text: Option<String>,
    #[serde(default)]
    refusal: Option<String>,
}

#[derive(Debug, Deserialize)]
struct CopilotResponsesUsage {
    #[serde(default)]
    input_tokens: u32,
    #[serde(default)]
    output_tokens: u32,
}

/// Why a `/responses` answer stopped short. `error` is null on an incomplete
/// response, so this is the only field that explains one.
#[derive(Debug, Deserialize)]
struct CopilotIncompleteDetails {
    #[serde(default)]
    reason: Option<String>,
}

#[derive(Debug, Deserialize)]
struct CopilotResponsesError {
    #[serde(default)]
    code: Option<String>,
    #[serde(default)]
    message: Option<String>,
}

fn response_text(response: &CopilotResponsesResponse, model: &str) -> LlmResult<String> {
    if response
        .status
        .as_deref()
        .is_some_and(|status| status != "completed")
    {
        // `max_output_tokens` is the one non-completed status the operator can
        // act on, and it is not an unexpected shape: raising `max_tokens` fixes
        // it. The OpenAI path reports the same stop as `TruncatedResponse`.
        if response
            .incomplete_details
            .as_ref()
            .and_then(|details| details.reason.as_deref())
            == Some("max_output_tokens")
        {
            return Err(LlmError::TruncatedResponse {
                model: model.to_owned(),
                completion_tokens: response.usage.as_ref().map(|usage| usage.output_tokens),
            });
        }
        let detail = response
            .error
            .as_ref()
            .and_then(|error| error.message.as_deref().or(error.code.as_deref()))
            .unwrap_or("no error detail");
        return Err(LlmError::UnexpectedShape(format!(
            "copilot /responses finished with status {:?}: {detail}",
            response.status
        )));
    }
    if let Some(text) = response
        .output_text
        .as_deref()
        .filter(|text| !text.is_empty())
    {
        return Ok(text.to_owned());
    }
    for output in &response.output {
        if output.kind != "message" {
            continue;
        }
        for content in &output.content {
            if content.kind == "refusal" {
                return Err(LlmError::UnexpectedShape(format!(
                    "copilot /responses refused the request: {}",
                    content.refusal.as_deref().unwrap_or("no refusal detail")
                )));
            }
            if content.kind == "output_text"
                && let Some(text) = content.text.as_deref().filter(|text| !text.is_empty())
            {
                return Ok(text.to_owned());
            }
        }
    }
    Err(LlmError::UnexpectedShape(
        "copilot /responses returned no text content".into(),
    ))
}

fn to_responses_chat_response(
    response: CopilotResponsesResponse,
    model: &str,
) -> LlmResult<ChatResponse> {
    let text = response_text(&response, model)?;
    Ok(ChatResponse {
        text,
        usage: response.usage.map(|usage| Usage {
            input_tokens: usage.input_tokens,
            output_tokens: usage.output_tokens,
        }),
        model: response.model.unwrap_or_else(|| "copilot".into()),
    })
}

#[derive(Debug, Deserialize)]
struct CopilotChatResponse {
    choices: Vec<CopilotChoice>,
    #[serde(default)]
    model: Option<String>,
    #[serde(default)]
    usage: Option<CopilotUsage>,
}

#[derive(Debug, Deserialize)]
struct CopilotChoice {
    message: CopilotMessageResponse,
}

#[derive(Debug, Deserialize)]
struct CopilotMessageResponse {
    content: Option<String>,
}

#[derive(Debug, Deserialize)]
struct CopilotUsage {
    #[serde(default)]
    prompt_tokens: u32,
    #[serde(default)]
    completion_tokens: u32,
}

fn to_chat_response(response: CopilotChatResponse) -> LlmResult<ChatResponse> {
    let text = response
        .choices
        .first()
        .and_then(|c| c.message.content.as_deref())
        .filter(|text| !text.is_empty())
        .ok_or_else(|| {
            LlmError::UnexpectedShape("copilot /chat/completions returned no text content".into())
        })?
        .to_string();
    Ok(ChatResponse {
        text,
        usage: response.usage.map(|u| Usage {
            input_tokens: u.prompt_tokens,
            output_tokens: u.completion_tokens,
        }),
        model: response.model.unwrap_or_else(|| "copilot".into()),
    })
}

fn copilot_token_exchange_headers() -> reqwest::header::HeaderMap {
    let mut headers = copilot_ide_headers(true);
    headers.insert(
        reqwest::header::HeaderName::from_static("copilot-integration-id"),
        reqwest::header::HeaderValue::from_static(COPILOT_INTEGRATION_ID),
    );
    headers
}

fn copilot_runtime_headers() -> reqwest::header::HeaderMap {
    let mut headers = copilot_ide_headers(false);
    headers.insert(
        reqwest::header::ACCEPT,
        reqwest::header::HeaderValue::from_static("application/json"),
    );
    headers.insert(
        reqwest::header::CONTENT_TYPE,
        reqwest::header::HeaderValue::from_static("application/json"),
    );
    headers.insert(
        reqwest::header::HeaderName::from_static("copilot-integration-id"),
        reqwest::header::HeaderValue::from_static(COPILOT_INTEGRATION_ID),
    );
    headers.insert(
        reqwest::header::HeaderName::from_static("openai-organization"),
        reqwest::header::HeaderValue::from_static("github-copilot"),
    );
    headers.insert(
        reqwest::header::HeaderName::from_static("x-initiator"),
        reqwest::header::HeaderValue::from_static("user"),
    );
    headers
}

fn copilot_ide_headers(include_api_version: bool) -> reqwest::header::HeaderMap {
    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert(
        reqwest::header::ACCEPT,
        reqwest::header::HeaderValue::from_static("application/json"),
    );
    headers.insert(
        reqwest::header::ACCEPT_ENCODING,
        reqwest::header::HeaderValue::from_static("identity"),
    );
    headers.insert(
        reqwest::header::HeaderName::from_static("editor-version"),
        reqwest::header::HeaderValue::from_static(COPILOT_EDITOR_VERSION),
    );
    headers.insert(
        reqwest::header::HeaderName::from_static("editor-plugin-version"),
        reqwest::header::HeaderValue::from_static(COPILOT_EDITOR_PLUGIN_VERSION),
    );
    headers.insert(
        reqwest::header::USER_AGENT,
        reqwest::header::HeaderValue::from_static(COPILOT_USER_AGENT),
    );
    if include_api_version {
        headers.insert(
            reqwest::header::HeaderName::from_static("x-github-api-version"),
            reqwest::header::HeaderValue::from_static(COPILOT_GITHUB_API_VERSION),
        );
    }
    headers
}

/// Derive Copilot API base URL from the `proxy-ep` field in a Copilot token.
#[must_use]
pub fn derive_copilot_api_base_url_from_token(token: &str) -> Option<String> {
    let proxy_ep = token.split(';').find_map(|field| {
        field
            .trim()
            .strip_prefix("proxy-ep=")
            .map(str::trim)
            .filter(|value| !value.is_empty())
    })?;
    let url_text = if proxy_ep.starts_with("http://") || proxy_ep.starts_with("https://") {
        proxy_ep.to_string()
    } else {
        format!("https://{proxy_ep}")
    };
    let url = reqwest::Url::parse(&url_text).ok()?;
    let host = url.host_str()?.to_ascii_lowercase();
    let host = host
        .strip_prefix("proxy.")
        .map(|rest| format!("api.{rest}"))
        .unwrap_or(host);
    let port = url.port().map(|p| format!(":{p}")).unwrap_or_default();
    Some(format!("{}://{host}{port}", url.scheme()))
}

fn resolve_copilot_api_base_url(override_url: Option<&str>, token: &str) -> String {
    override_url
        .filter(|url| !url.trim().is_empty())
        .map(ToOwned::to_owned)
        .or_else(|| derive_copilot_api_base_url_from_token(token))
        .unwrap_or_else(|| DEFAULT_COPILOT_API_BASE_URL.into())
}

#[derive(Debug, Serialize, Deserialize)]
struct CopilotEntry {
    #[serde(rename = "type")]
    kind: String,
    #[serde(rename = "githubAccess", skip_serializing_if = "Option::is_none")]
    github_access: Option<String>,
    #[serde(rename = "githubExpires", skip_serializing_if = "Option::is_none")]
    github_expires: Option<u64>,
    #[serde(rename = "copilotAccess", skip_serializing_if = "Option::is_none")]
    copilot_access: Option<String>,
    #[serde(rename = "copilotExpires", skip_serializing_if = "Option::is_none")]
    copilot_expires: Option<u64>,
    #[serde(rename = "apiBaseUrl", skip_serializing_if = "Option::is_none")]
    api_base_url: Option<String>,
}

fn unix_epoch_to_ms(value: u64) -> u64 {
    if value > 100_000_000_000 {
        value
    } else {
        value.saturating_mul(1000)
    }
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use super::*;

    #[tokio::test]
    async fn token_exchange_treats_a_throttled_endpoint_as_transient() {
        use wiremock::matchers::method;
        use wiremock::{Mock, MockServer, ResponseTemplate};

        for (code, transient) in [(429u16, true), (503, true), (401, false)] {
            let server = MockServer::start().await;
            Mock::given(method("GET"))
                .respond_with(ResponseTemplate::new(code).set_body_string("{}"))
                .expect(1)
                .mount(&server)
                .await;

            let Err(err) = exchange_copilot_token(
                &reqwest::Client::new(),
                Duration::from_secs(5),
                &SecretString::from("gho_test"),
                &server.uri(),
            )
            .await
            else {
                panic!("{code} from the token endpoint must fail");
            };

            assert_eq!(err.is_transient(), transient, "{code}: {err:?}");
            if transient {
                assert_eq!(err.http_status(), Some(code), "{code}: {err:?}");
                assert!(err.to_string().contains("copilot token exchange"), "{err}");
            } else {
                assert!(matches!(err, LlmError::Auth(_)), "{code}: {err:?}");
            }
        }
    }

    #[test]
    fn token_file_round_trips_copilot_entry() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("auth.json");
        let token = CopilotToken {
            github_access: Some(SecretString::from("ghu-test")),
            github_expires_at_ms: None,
            copilot_access: Some(SecretString::from("copilot-test")),
            copilot_expires_at_ms: Some(1234),
            api_base_url: Some("https://api.example.test".into()),
        };

        token.save(&path).unwrap();
        let loaded = CopilotToken::load(&path).unwrap().unwrap();

        assert_eq!(loaded.github_access.unwrap().expose_secret(), "ghu-test");
        assert_eq!(
            loaded.copilot_access.unwrap().expose_secret(),
            "copilot-test"
        );
        assert_eq!(loaded.copilot_expires_at_ms, Some(1234));
        assert_eq!(
            loaded.api_base_url.as_deref(),
            Some("https://api.example.test")
        );
    }

    #[test]
    fn token_file_preserves_unknown_entries() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("auth.json");
        std::fs::write(
            &path,
            serde_json::to_vec_pretty(&json!({
                "openai": { "type": "oauth", "access": "x", "refresh": "y", "expires": 1 }
            }))
            .unwrap(),
        )
        .unwrap();

        CopilotToken::from_github_token("ghu-test", None)
            .save(&path)
            .unwrap();
        let value =
            serde_json::from_slice::<serde_json::Value>(&std::fs::read(&path).unwrap()).unwrap();

        assert!(value.get("openai").is_some());
        assert_eq!(value["copilot"]["githubAccess"], "ghu-test");
    }

    #[test]
    fn token_file_ignores_non_oauth_copilot_entry() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("auth.json");
        std::fs::write(
            &path,
            serde_json::to_vec_pretty(&json!({
                "copilot": { "type": "api", "key": "token" }
            }))
            .unwrap(),
        )
        .unwrap();

        assert!(CopilotToken::load(&path).unwrap().is_none());
    }

    #[test]
    fn remove_deletes_only_copilot_entry() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("auth.json");
        std::fs::write(
            &path,
            serde_json::to_vec_pretty(&json!({
                "copilot": { "type": "oauth", "githubAccess": "ghu" },
                "other": { "type": "oauth", "access": "x" }
            }))
            .unwrap(),
        )
        .unwrap();

        CopilotToken::remove(&path).unwrap();
        let value =
            serde_json::from_slice::<serde_json::Value>(&std::fs::read(&path).unwrap()).unwrap();
        assert!(value.get("copilot").is_none());
        assert!(value.get("other").is_some());
    }

    #[test]
    fn derives_api_base_url_from_proxy_ep() {
        assert_eq!(
            derive_copilot_api_base_url_from_token(
                "tid=abc;proxy-ep=https://proxy.individual.githubcopilot.com;exp=1:mac"
            ),
            Some("https://api.individual.githubcopilot.com".into())
        );
        assert_eq!(
            derive_copilot_api_base_url_from_token(
                "tid=abc;proxy-ep=proxy.enterprise.example.com:443;exp=1:mac"
            ),
            Some("https://api.enterprise.example.com".into())
        );
    }

    #[test]
    fn resolves_direct_token_base_url_from_override_or_proxy_ep() {
        let token = "tid=abc;proxy-ep=https://proxy.individual.githubcopilot.com;exp=1:mac";

        assert_eq!(
            resolve_copilot_api_base_url(Some("https://api.override.test"), token),
            "https://api.override.test"
        );
        assert_eq!(
            resolve_copilot_api_base_url(None, token),
            "https://api.individual.githubcopilot.com"
        );
        assert_eq!(
            resolve_copilot_api_base_url(None, "no-proxy"),
            DEFAULT_COPILOT_API_BASE_URL
        );
    }

    #[test]
    fn status_helpers_reject_expired_unrefreshable_cache() {
        let expired = now_ms().saturating_sub(10_000);
        let token = CopilotToken {
            github_access: None,
            github_expires_at_ms: None,
            copilot_access: Some(SecretString::from("cached")),
            copilot_expires_at_ms: Some(expired),
            api_base_url: None,
        };

        assert!(!token.has_refreshable_github_token());
        assert!(!token.has_valid_cached_copilot_token());
    }

    #[test]
    fn status_helpers_accept_refreshable_github_token() {
        let token = CopilotToken::from_github_token("ghu-test", None);

        assert!(token.has_refreshable_github_token());
        assert!(!token.has_valid_cached_copilot_token());
    }

    #[test]
    fn token_exchange_headers_include_vscode_chat_scope() {
        let headers = copilot_token_exchange_headers();
        assert_eq!(
            headers.get("Copilot-Integration-Id").unwrap(),
            COPILOT_INTEGRATION_ID
        );
        assert_eq!(
            headers.get("X-GitHub-Api-Version").unwrap(),
            COPILOT_GITHUB_API_VERSION
        );
    }

    #[test]
    fn runtime_headers_include_copilot_org() {
        let headers = copilot_runtime_headers();
        assert_eq!(
            headers.get("Copilot-Integration-Id").unwrap(),
            COPILOT_INTEGRATION_ID
        );
        assert_eq!(
            headers.get("Openai-Organization").unwrap(),
            "github-copilot"
        );
    }

    #[test]
    fn chat_request_uses_openai_compatible_shape() {
        let request = ChatRequest {
            system: Some("sys".into()),
            messages: vec![crate::types::ChatMessage::user("hello")],
            temperature: Some(0.2),
            max_tokens: 123,
        };
        let value = serde_json::to_value(build_chat_request("gpt-5.5", &request, None)).unwrap();
        assert_eq!(value["messages"][0]["role"], "system");
        assert_eq!(value["messages"][1]["content"], "hello");
        assert_eq!(value["max_tokens"], 123);
        assert!(value.get("temperature").is_none());
        assert_eq!(value["stream"], false);
    }

    #[test]
    fn chat_request_omits_gpt6_temperature() {
        let request = ChatRequest {
            system: None,
            messages: vec![crate::types::ChatMessage::user("hello")],
            temperature: Some(0.2),
            max_tokens: 123,
        };
        let value = serde_json::to_value(build_chat_request("gpt-6-sol", &request, None)).unwrap();
        assert!(value.get("temperature").is_none());
    }

    #[test]
    fn responses_request_omits_gpt6_temperature() {
        let request = ChatRequest {
            system: None,
            messages: vec![crate::types::ChatMessage::user("hello")],
            temperature: Some(0.2),
            max_tokens: 123,
        };
        let value =
            serde_json::to_value(build_responses_request("gpt-6-sol", &request, None)).unwrap();
        assert!(value.get("temperature").is_none());
    }

    #[test]
    fn structured_request_uses_json_schema_format() {
        let request = ChatRequest::user_prompt("json please");
        let response_format = CopilotResponseFormat::JsonSchema {
            json_schema: CopilotJsonSchema {
                name: STRUCTURED_OUTPUT_SCHEMA_NAME.into(),
                schema: json!({ "type": "object", "properties": {} }),
                strict: true,
            },
        };
        let value = serde_json::to_value(build_chat_request(
            "gpt-5.5",
            &request,
            Some(response_format),
        ))
        .unwrap();
        assert_eq!(value["response_format"]["type"], "json_schema");
        assert_eq!(value["response_format"]["json_schema"]["name"], "Result");
        assert_eq!(value["response_format"]["json_schema"]["strict"], true);
    }

    #[test]
    fn epoch_seconds_convert_to_millis() {
        assert_eq!(unix_epoch_to_ms(1_700_000_000), 1_700_000_000_000);
        assert_eq!(unix_epoch_to_ms(1_700_000_000_000), 1_700_000_000_000);
    }
}