Skip to content

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

Rust

feat(llm): add oauth-backed OpenAI and Copilot providers

AkitaOnRailsc8c54be5674d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2aa7a526..d9ed1567 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- `memory_write_page` MCP tool for explicit durable annotations, so agents can
write permanent wiki knowledge without abusing single-use handoffs.
+- `openai-oauth` LLM provider for ChatGPT/Codex accounts, including
+ `ai-memory auth login|logout|status` device-flow commands and token storage
+ in `<data_dir>/auth.json`.
+- `copilot` LLM provider for GitHub Copilot Chat accounts. It stores a GitHub
+ token via `ai-memory auth login copilot`, exchanges it for a short-lived
+ Copilot API token, and sends Copilot Chat requests with `vscode-chat`
+ integration headers.
### Fixed
- `install-mcp`, `install-hooks`, and `setup-agent` now honor configured
diff --git a/Cargo.lock b/Cargo.lock
index f7df7f90..c25fadae 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -151,15 +151,18 @@ dependencies = [
"ai-memory-core",
"anyhow",
"async-trait",
+ "base64",
"regex",
"reqwest",
"schemars",
"secrecy",
"serde",
"serde_json",
+ "tempfile",
"thiserror 2.0.18",
"tokio",
"tracing",
+ "uuid",
]
[[package]]
diff --git a/README.md b/README.md
index 860db046..f5da14de 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
| Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
| OpenClaw | Supported | MCP config + native plugin lifecycle hooks. |
| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). |
-| LLM providers | Supported | Anthropic, OpenAI, Gemini, and OpenAI-compatible endpoints. |
+| LLM providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, and OpenAI-compatible endpoints. |
| Embedding providers | Supported | OpenAI, Voyage, and Google Gemini. |
## What it is
@@ -286,9 +286,21 @@ Recommended defaults:
|---|---|---|
| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
+| `openai-oauth` | `gpt-5.5` | ChatGPT Pro/Plus/Codex backend via `ai-memory auth login openai-oauth`; no Platform API key. |
+| `copilot` | `gpt-5.5` | GitHub Copilot Chat backend via `ai-memory auth login copilot` or `COPILOT_GITHUB_TOKEN`; requires a Copilot subscription. |
| `gemini` | `gemini-2.5-flash` | Google-hosted option with a generous free tier. |
| `openai-compat` | no default | OpenRouter, Ollama, vLLM, LM Studio, and other compatible endpoints. |
+`openai-oauth` stores a refresh token in `<data_dir>/auth.json` and talks to
+the ChatGPT/Codex Responses backend, not `api.openai.com`. For Docker quick
+starts, run `ai-memory auth login openai-oauth` with the wrapper so the token
+lands in the same `ai-memory-data` volume as the server.
+
+`copilot` stores a GitHub user token in the same auth file, exchanges it for a
+short-lived Copilot API token via GitHub's `/copilot_internal/v2/token`, and
+uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can
+also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.
+
Embeddings are optional and separate from the LLM provider. Set
`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`, or `gemini` when
you want vector reranking in addition to FTS5 + graph-neighbor retrieval.
diff --git a/bin/ai-memory b/bin/ai-memory
index 75af9837..1116c030 100755
--- a/bin/ai-memory
+++ b/bin/ai-memory
@@ -18,6 +18,7 @@
# AI_MEMORY_SERVER_URL server URL for thin-client commands; if unset,
# the wrapper reaches the host loopback server
# started by the README quick start.
+# COPILOT_GITHUB_TOKEN GitHub token for AI_MEMORY_LLM_PROVIDER=copilot
# AI_MEMORY_NO_TTY=1 force non-interactive even on a real tty
# AI_MEMORY_NO_VERSION_CHECK=1 skip the once-per-day update check
set -euo pipefail
@@ -212,6 +213,7 @@ for var in \
AI_MEMORY_LLM_PROVIDER \
AI_MEMORY_LLM_MODEL \
AI_MEMORY_LLM_BASE_URL \
+ AI_MEMORY_COPILOT_CLIENT_ID \
AI_MEMORY_EMBEDDING_PROVIDER \
AI_MEMORY_EMBEDDING_MODEL \
AI_MEMORY_EMBEDDING_BASE_URL \
@@ -221,6 +223,9 @@ for var in \
AI_MEMORY_HOOKS_HOST_ROOT \
ANTHROPIC_API_KEY \
OPENAI_API_KEY \
+ COPILOT_GITHUB_TOKEN \
+ GITHUB_COPILOT_API_TOKEN \
+ COPILOT_API_URL \
VOYAGE_API_KEY \
LLM_API_KEY \
RUST_LOG
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 67dc752f..692486f0 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -95,8 +95,67 @@ pub enum Command {
/// Remove ai-memory's wiring (hooks, MCP, instructions) from all
/// detected agents. Dry-run unless `--apply`.
Uninstall(UninstallArgs),
+ /// Manage optional upstream LLM provider authentication.
+ Auth(AuthArgs),
}
+/// Arguments for `auth`.
+#[derive(Debug, Args)]
+pub struct AuthArgs {
+ /// Auth action to run.
+ #[command(subcommand)]
+ pub command: AuthCommand,
+}
+
+/// Subcommands for `auth`.
+#[derive(Debug, Subcommand)]
+pub enum AuthCommand {
+ /// Sign in to an upstream provider.
+ Login(AuthLoginArgs),
+ /// Remove stored provider credentials.
+ Logout(AuthLogoutArgs),
+ /// Show stored provider auth state without printing secrets.
+ Status(AuthStatusArgs),
+}
+
+/// Provider choices for `auth`.
+#[derive(Debug, Clone, Copy, clap::ValueEnum)]
+pub enum AuthProviderChoice {
+ /// OpenAI ChatGPT/Codex OAuth backend.
+ OpenaiOauth,
+ /// GitHub Copilot Chat backend.
+ Copilot,
+}
+
+/// Arguments for `auth login`.
+#[derive(Debug, Args)]
+pub struct AuthLoginArgs {
+ /// Provider to sign in to.
+ #[arg(value_enum)]
+ pub provider: AuthProviderChoice,
+ /// Stop waiting for browser/device authorization after this many seconds.
+ #[arg(long, default_value_t = 600)]
+ pub timeout_secs: u64,
+ /// GitHub token to persist for Copilot instead of running device auth.
+ #[arg(long, hide_env_values = true)]
+ pub github_token: Option<String>,
+ /// OAuth client id override for Copilot device auth.
+ #[arg(long)]
+ pub client_id: Option<String>,
+}
+
+/// Arguments for `auth logout`.
+#[derive(Debug, Args)]
+pub struct AuthLogoutArgs {
+ /// Provider to sign out from.
+ #[arg(value_enum)]
+ pub provider: AuthProviderChoice,
+}
+
+/// Arguments for `auth status`.
+#[derive(Debug, Args)]
+pub struct AuthStatusArgs {}
+
/// Which concern `uninstall` should touch. Omitted = all three.
#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
pub enum UninstallOnly {
@@ -464,6 +523,10 @@ pub enum LlmProviderChoice {
Gemini,
/// OpenAI-compatible local (Ollama, vLLM, LM Studio).
OpenaiCompat,
+ /// OpenAI ChatGPT/Codex OAuth backend.
+ OpenaiOauth,
+ /// GitHub Copilot Chat backend.
+ Copilot,
}
/// Arguments for `embed`.
@@ -769,4 +832,53 @@ mod tests {
assert!(matches!(hook_args.agent, AgentChoice::AntigravityCli));
}
}
+
+ #[test]
+ fn auth_login_openai_oauth_parses() {
+ let cli = Cli::try_parse_from([
+ "ai-memory",
+ "auth",
+ "login",
+ "openai-oauth",
+ "--timeout-secs",
+ "30",
+ ])
+ .unwrap();
+
+ let Command::Auth(args) = cli.command else {
+ panic!("expected auth command");
+ };
+ let AuthCommand::Login(login) = args.command else {
+ panic!("expected auth login command");
+ };
+ assert!(matches!(login.provider, AuthProviderChoice::OpenaiOauth));
+ assert_eq!(login.timeout_secs, 30);
+ assert!(login.github_token.is_none());
+ assert!(login.client_id.is_none());
+ }
+
+ #[test]
+ fn auth_login_copilot_parses_token_and_client_override() {
+ let cli = Cli::try_parse_from([
+ "ai-memory",
+ "auth",
+ "login",
+ "copilot",
+ "--github-token",
+ "ghu-test",
+ "--client-id",
+ "Iv1.test",
+ ])
+ .unwrap();
+
+ let Command::Auth(args) = cli.command else {
+ panic!("expected auth command");
+ };
+ let AuthCommand::Login(login) = args.command else {
+ panic!("expected auth login command");
+ };
+ assert!(matches!(login.provider, AuthProviderChoice::Copilot));
+ assert_eq!(login.github_token.as_deref(), Some("ghu-test"));
+ assert_eq!(login.client_id.as_deref(), Some("Iv1.test"));
+ }
}
diff --git a/crates/ai-memory-cli/src/commands/auth.rs b/crates/ai-memory-cli/src/commands/auth.rs
new file mode 100644
index 00000000..0c726bbd
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/auth.rs
@@ -0,0 +1,438 @@
+//! `ai-memory auth` — manage upstream LLM provider credentials.
+
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use ai_memory_llm::{
+ CODEX_CLIENT_ID, CopilotToken, GITHUB_ACCESS_TOKEN_URL, GITHUB_COPILOT_CLIENT_ID,
+ GITHUB_DEVICE_CODE_URL, OPENAI_OAUTH_TOKEN_URL, OpenAiOAuthToken, OpenAiOAuthTokenResponse,
+};
+use anyhow::{Context, Result, anyhow, bail};
+use secrecy::ExposeSecret as _;
+use serde::{Deserialize, Serialize};
+use tokio::time::sleep;
+
+use crate::cli::{AuthArgs, AuthCommand, AuthProviderChoice};
+use crate::config::Config;
+
+const DEVICE_USER_CODE_URL: &str = "https://auth.openai.com/api/accounts/deviceauth/usercode";
+const DEVICE_TOKEN_URL: &str = "https://auth.openai.com/api/accounts/deviceauth/token";
+const DEVICE_BROWSER_URL: &str = "https://auth.openai.com/codex/device";
+const DEVICE_REDIRECT_URI: &str = "https://auth.openai.com/deviceauth/callback";
+const POLLING_SAFETY_MARGIN_SECS: u64 = 3;
+
+/// Run the `auth` subcommand.
+///
+/// # Errors
+/// Returns an error if token storage or provider auth requests fail.
+pub async fn run(config: &Config, args: AuthArgs) -> Result<()> {
+ match args.command {
+ AuthCommand::Login(args) => match args.provider {
+ AuthProviderChoice::OpenaiOauth => {
+ if args.github_token.is_some() || args.client_id.is_some() {
+ bail!("--github-token and --client-id apply only to `auth login copilot`");
+ }
+ login_openai_oauth(config, args.timeout_secs).await
+ }
+ AuthProviderChoice::Copilot => {
+ login_copilot(config, args.timeout_secs, args.github_token, args.client_id).await
+ }
+ },
+ AuthCommand::Logout(args) => match args.provider {
+ AuthProviderChoice::OpenaiOauth => logout_openai_oauth(config),
+ AuthProviderChoice::Copilot => logout_copilot(config),
+ },
+ AuthCommand::Status(_) => status(config),
+ }
+}
+
+async fn login_openai_oauth(config: &Config, timeout_secs: u64) -> Result<()> {
+ let client = auth_http_client()?;
+ let device = start_device_authorization(&client).await?;
+ println!("Open this URL: {DEVICE_BROWSER_URL}");
+ println!("Enter code: {}", device.user_code);
+ println!("Waiting for authorization...");
+
+ let code =
+ poll_device_authorization(&client, &device, Duration::from_secs(timeout_secs)).await?;
+ let tokens = exchange_authorization_code(&client, code).await?;
+ let refresh = tokens.refresh_token.clone().ok_or_else(|| {
+ anyhow::anyhow!("openai-oauth token response did not include refresh_token")
+ })?;
+ let token = OpenAiOAuthToken::from_token_response(
+ tokens.access_token,
+ refresh,
+ tokens.expires_in.unwrap_or(3600),
+ tokens.id_token.as_deref(),
+ None,
+ );
+ let path = config.openai_oauth_token_path();
+ token.save(&path).map_err(anyhow::Error::from)?;
+
+ println!("openai-oauth: logged in");
+ if let Some(account_id) = token.account_id.as_deref() {
+ println!("account: {account_id}");
+ }
+ println!("token file: {}", path.display());
+ Ok(())
+}
+
+fn logout_openai_oauth(config: &Config) -> Result<()> {
+ let path = config.openai_oauth_token_path();
+ OpenAiOAuthToken::remove(&path).map_err(anyhow::Error::from)?;
+ println!("openai-oauth: logged out");
+ println!("token file: {}", path.display());
+ Ok(())
+}
+
+async fn login_copilot(
+ config: &Config,
+ timeout_secs: u64,
+ github_token_arg: Option<String>,
+ client_id_arg: Option<String>,
+) -> Result<()> {
+ let github_token = match github_token_arg.filter(|s| !s.trim().is_empty()) {
+ Some(token) => token,
+ None => match config.copilot_github_token() {
+ Some(token) => token.expose_secret().to_string(),
+ None => {
+ let client_id = client_id_arg
+ .as_deref()
+ .or_else(|| config.copilot_client_id())
+ .unwrap_or(GITHUB_COPILOT_CLIENT_ID);
+ run_copilot_device_flow(client_id, timeout_secs).await?
+ }
+ },
+ };
+
+ let token = CopilotToken::from_github_token(github_token, None);
+ let path = config.copilot_token_path();
+ token.save(&path).map_err(anyhow::Error::from)?;
+ println!("copilot: logged in");
+ println!("token file: {}", path.display());
+ Ok(())
+}
+
+fn logout_copilot(config: &Config) -> Result<()> {
+ let path = config.copilot_token_path();
+ CopilotToken::remove(&path).map_err(anyhow::Error::from)?;
+ println!("copilot: logged out");
+ println!("token file: {}", path.display());
+ Ok(())
+}
+
+fn status(config: &Config) -> Result<()> {
+ let openai_path = config.openai_oauth_token_path();
+ match OpenAiOAuthToken::load(&openai_path).map_err(anyhow::Error::from)? {
+ Some(token) => {
+ println!("openai-oauth: logged in");
+ if let Some(account_id) = token.account_id.as_deref() {
+ println!("account: {account_id}");
+ }
+ println!("expires in: {}", format_duration_until(token.expires_at_ms));
+ println!("token file: {}", openai_path.display());
+ }
+ None => {
+ println!("openai-oauth: not logged in");
+ println!("token file: {}", openai_path.display());
+ }
+ }
+
+ let copilot_path = config.copilot_token_path();
+ match CopilotToken::load(&copilot_path).map_err(anyhow::Error::from)? {
+ Some(token) => {
+ let has_refreshable_github = token.has_refreshable_github_token();
+ let has_valid_cached = token.has_valid_cached_copilot_token();
+ if has_refreshable_github {
+ println!("copilot: logged in");
+ } else if has_valid_cached {
+ println!("copilot: cached token valid (no GitHub token stored for refresh)");
+ } else {
+ println!(
+ "copilot: not logged in (cached token expired and no refreshable GitHub token stored)"
+ );
+ }
+ if let Some(expires_at_ms) = token.github_expires_at_ms {
+ println!(
+ "github token expires in: {}",
+ format_duration_until(expires_at_ms)
+ );
+ }
+ if let Some(expires_at_ms) = token.copilot_expires_at_ms {
+ println!(
+ "cached copilot token expires in: {}",
+ format_duration_until(expires_at_ms)
+ );
+ }
+ if let Some(api_base_url) = token.api_base_url.as_deref() {
+ println!("api base: {api_base_url}");
+ }
+ println!("token file: {}", copilot_path.display());
+ }
+ None => {
+ println!("copilot: not logged in");
+ println!("token file: {}", copilot_path.display());
+ }
+ }
+ Ok(())
+}
+
+async fn run_copilot_device_flow(client_id: &str, timeout_secs: u64) -> Result<String> {
+ let client = auth_http_client()?;
+ let device = start_github_device_authorization(&client, client_id).await?;
+ println!("Open this URL: {}", device.verification_uri);
+ println!("Enter code: {}", device.user_code);
+ println!("Waiting for authorization...");
+ poll_github_device_authorization(
+ &client,
+ client_id,
+ &device,
+ Duration::from_secs(timeout_secs),
+ )
+ .await
+}
+
+fn auth_http_client() -> Result<reqwest::Client> {
+ reqwest::Client::builder()
+ .timeout(Duration::from_secs(60))
+ .user_agent(format!("ai-memory/{}", env!("CARGO_PKG_VERSION")))
+ .build()
+ .context("building HTTP client")
+}
+
+async fn start_device_authorization(client: &reqwest::Client) -> Result<DeviceAuthorization> {
+ let resp = client
+ .post(DEVICE_USER_CODE_URL)
+ .json(&DeviceAuthorizationRequest {
+ client_id: CODEX_CLIENT_ID,
+ })
+ .send()
+ .await
+ .context("starting openai-oauth device authorization")?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ bail!("openai-oauth device authorization failed ({status}): {body}");
+ }
+ resp.json::<DeviceAuthorization>()
+ .await
+ .context("parsing openai-oauth device authorization response")
+}
+
+async fn poll_device_authorization(
+ client: &reqwest::Client,
+ device: &DeviceAuthorization,
+ timeout: Duration,
+) -> Result<DeviceAuthorizationCode> {
+ let started = Instant::now();
+ let interval = Duration::from_secs(
+ device
+ .interval
+ .parse::<u64>()
+ .unwrap_or(5)
+ .max(1)
+ .saturating_add(POLLING_SAFETY_MARGIN_SECS),
+ );
+ loop {
+ if started.elapsed() >= timeout {
+ bail!("timed out waiting for openai-oauth authorization");
+ }
+ let resp = client
+ .post(DEVICE_TOKEN_URL)
+ .json(&DeviceTokenRequest {
+ device_auth_id: &device.device_auth_id,
+ user_code: &device.user_code,
+ })
+ .send()
+ .await
+ .context("polling openai-oauth device authorization")?;
+ if resp.status().is_success() {
+ return resp
+ .json::<DeviceAuthorizationCode>()
+ .await
+ .context("parsing openai-oauth authorization code");
+ }
+ if resp.status() != reqwest::StatusCode::FORBIDDEN
+ && resp.status() != reqwest::StatusCode::NOT_FOUND
+ {
+ let status = resp.status();
+ let body = resp.text().await.unwrap_or_default();
+ bail!("openai-oauth authorization polling failed ({status}): {body}");
+ }
+ sleep(interval).await;
+ }
+}
+
+async fn exchange_authorization_code(
+ client: &reqwest::Client,
+ code: DeviceAuthorizationCode,
+) -> Result<OpenAiOAuthTokenResponse> {
+ let resp = client
+ .post(OPENAI_OAUTH_TOKEN_URL)
+ .form(&[
+ ("grant_type", "authorization_code"),
+ ("code", code.authorization_code.as_str()),
+ ("redirect_uri", DEVICE_REDIRECT_URI),
+ ("client_id", CODEX_CLIENT_ID),
+ ("code_verifier", code.code_verifier.as_str()),
+ ])
+ .send()
+ .await
+ .context("exchanging openai-oauth authorization code")?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ bail!("openai-oauth token exchange failed ({status}): {body}");
+ }
+ resp.json::<OpenAiOAuthTokenResponse>()
+ .await
+ .context("parsing openai-oauth token response")
+}
+
+async fn start_github_device_authorization(
+ client: &reqwest::Client,
+ client_id: &str,
+) -> Result<GitHubDeviceAuthorization> {
+ let resp = client
+ .post(GITHUB_DEVICE_CODE_URL)
+ .header(reqwest::header::ACCEPT, "application/json")
+ .form(&[("client_id", client_id), ("scope", "read:user")])
+ .send()
+ .await
+ .context("starting copilot GitHub device authorization")?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ bail!("copilot GitHub device authorization failed ({status}): {body}");
+ }
+ resp.json::<GitHubDeviceAuthorization>()
+ .await
+ .context("parsing copilot GitHub device authorization response")
+}
+
+async fn poll_github_device_authorization(
+ client: &reqwest::Client,
+ client_id: &str,
+ device: &GitHubDeviceAuthorization,
+ timeout: Duration,
+) -> Result<String> {
+ let started = Instant::now();
+ let mut interval = Duration::from_secs(device.interval.unwrap_or(5).max(1));
+ let device_timeout = Duration::from_secs(device.expires_in.max(1));
+ let timeout = timeout.min(device_timeout);
+ loop {
+ if started.elapsed() >= timeout {
+ bail!("timed out waiting for copilot GitHub authorization");
+ }
+ let resp = client
+ .post(GITHUB_ACCESS_TOKEN_URL)
+ .header(reqwest::header::ACCEPT, "application/json")
+ .form(&[
+ ("client_id", client_id),
+ ("device_code", device.device_code.as_str()),
+ ("grant_type", "urn:ietf:params:oauth:grant-type:device_code"),
+ ])
+ .send()
+ .await
+ .context("polling copilot GitHub device authorization")?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ bail!("copilot GitHub authorization polling failed ({status}): {body}");
+ }
+ let body = resp
+ .json::<GitHubDeviceAccessToken>()
+ .await
+ .context("parsing copilot GitHub token response")?;
+ if let Some(token) = body.access_token {
+ return Ok(token);
+ }
+ match body.error.as_deref() {
+ Some("authorization_pending") => {}
+ Some("slow_down") => interval = interval.saturating_add(Duration::from_secs(5)),
+ Some("expired_token") => bail!("copilot GitHub device code expired"),
+ Some("access_denied") => bail!("copilot GitHub authorization denied"),
+ Some(error) => {
+ let description = body.error_description.unwrap_or_default();
+ return Err(anyhow!(
+ "copilot GitHub authorization failed: {error} {description}"
+ ));
+ }
+ None => bail!("copilot GitHub token response did not include access_token"),
+ }
+ sleep(interval).await;
+ }
+}
+
+fn format_duration_until(expires_at_ms: u64) -> String {
+ let now = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_millis()
+ .try_into()
+ .unwrap_or(u64::MAX);
+ if expires_at_ms <= now {
+ return "expired".into();
+ }
+ let secs = (expires_at_ms - now) / 1000;
+ let hours = secs / 3600;
+ let minutes = (secs % 3600) / 60;
+ if hours > 0 {
+ format!("{hours}h {minutes}m")
+ } else {
+ format!("{minutes}m")
+ }
+}
+
+#[derive(Debug, Serialize)]
+struct DeviceAuthorizationRequest {
+ client_id: &'static str,
+}
+
+#[derive(Debug, Deserialize)]
+struct DeviceAuthorization {
+ device_auth_id: String,
+ user_code: String,
+ interval: String,
+}
+
+#[derive(Debug, Serialize)]
+struct DeviceTokenRequest<'a> {
+ device_auth_id: &'a str,
+ user_code: &'a str,
+}
+
+#[derive(Debug, Deserialize)]
+struct DeviceAuthorizationCode {
+ authorization_code: String,
+ code_verifier: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct GitHubDeviceAuthorization {
+ device_code: String,
+ user_code: String,
+ verification_uri: String,
+ expires_in: u64,
+ #[serde(default)]
+ interval: Option<u64>,
+}
+
+#[derive(Debug, Deserialize)]
+struct GitHubDeviceAccessToken {
+ #[serde(default)]
+ access_token: Option<String>,
+ #[serde(default)]
+ error: Option<String>,
+ #[serde(default)]
+ error_description: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn expiry_status_does_not_print_exact_token_time() {
+ assert_eq!(format_duration_until(0), "expired");
+ }
+}
diff --git a/crates/ai-memory-cli/src/commands/llm_test.rs b/crates/ai-memory-cli/src/commands/llm_test.rs
index 89edee29..200022ab 100644
--- a/crates/ai-memory-cli/src/commands/llm_test.rs
+++ b/crates/ai-memory-cli/src/commands/llm_test.rs
@@ -14,15 +14,14 @@ use crate::config::Config;
/// lacks the required keys, or the HTTP call fails.
pub async fn run(config: &Config, args: LlmTestArgs) -> Result<()> {
let provider = ProviderChoice::from(args.provider);
- let api_key = args
+ let api_key_override = args
.api_key
.filter(|s| !s.is_empty())
- .map(secrecy::SecretString::from)
- .or_else(|| config.provider_api_key(provider));
+ .map(secrecy::SecretString::from);
let provider_config = ProviderConfig {
provider,
model: args.model,
- api_key,
+ auth: config.provider_auth(provider, api_key_override),
base_url: args.base_url.or_else(|| config.llm_test_base_url()),
};
let client = build_provider(provider_config).context("building LLM provider")?;
@@ -54,6 +53,8 @@ impl From<LlmProviderChoice> for ProviderChoice {
LlmProviderChoice::Openai => Self::OpenAi,
LlmProviderChoice::Gemini => Self::Gemini,
LlmProviderChoice::OpenaiCompat => Self::OpenAiCompat,
+ LlmProviderChoice::OpenaiOauth => Self::OpenAiOAuth,
+ LlmProviderChoice::Copilot => Self::Copilot,
}
}
}
diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rs
index eae3f356..37c8436d 100644
--- a/crates/ai-memory-cli/src/commands/mod.rs
+++ b/crates/ai-memory-cli/src/commands/mod.rs
@@ -5,6 +5,7 @@ use anyhow::{Context, Result, anyhow, bail};
use crate::config::Config;
pub mod apply_shared;
+pub mod auth;
pub mod backup;
pub mod bootstrap;
pub mod commit;
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 7f9d5639..c39e0616 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -9,7 +9,8 @@
use std::path::{Path, PathBuf};
use ai_memory_llm::{
- EmbedderChoice, EmbedderConfig, LlmError, LlmResult, ProviderChoice, ProviderConfig,
+ AuthRequirement, EmbedderChoice, EmbedderConfig, LlmError, LlmResult, ProviderAuth,
+ ProviderChoice, ProviderConfig,
};
use anyhow::{Context, Result};
use figment::{
@@ -52,7 +53,7 @@ pub struct Config {
pub server_url: String,
/// Per-subsystem log filter (overridable by `RUST_LOG`).
pub log_level: String,
- /// Optional LLM provider (`anthropic`, `openai`, `gemini`, `openai-compat`).
+ /// Optional LLM provider (`anthropic`, `openai`, `gemini`, `openai-compat`, `openai-oauth`, `copilot`).
pub llm_provider: Option<String>,
/// Optional LLM model override.
pub llm_model: Option<String>,
@@ -113,6 +114,10 @@ pub struct RuntimeEnv {
gemini_api_key: Option<SecretString>,
llm_api_key: Option<SecretString>,
llm_base_url: Option<String>,
+ copilot_github_token: Option<SecretString>,
+ github_copilot_api_token: Option<SecretString>,
+ copilot_api_url: Option<String>,
+ copilot_client_id: Option<String>,
voyage_api_key: Option<SecretString>,
}
@@ -130,6 +135,12 @@ impl RuntimeEnv {
gemini_api_key: env_secret("GEMINI_API_KEY").or_else(|| env_secret("GOOGLE_API_KEY")),
llm_api_key: env_secret("LLM_API_KEY"),
llm_base_url: env_string("LLM_BASE_URL"),
+ copilot_github_token: env_secret("COPILOT_GITHUB_TOKEN")
+ .or_else(|| env_secret("GH_TOKEN"))
+ .or_else(|| env_secret("GITHUB_TOKEN")),
+ github_copilot_api_token: env_secret("GITHUB_COPILOT_API_TOKEN"),
+ copilot_api_url: env_string("COPILOT_API_URL"),
+ copilot_client_id: env_string("AI_MEMORY_COPILOT_CLIENT_ID"),
voyage_api_key: env_secret("VOYAGE_API_KEY"),
}
}
@@ -312,10 +323,12 @@ impl Config {
"openai" => ProviderChoice::OpenAi,
"gemini" | "google" => ProviderChoice::Gemini,
"openai-compat" | "openai_compat" => ProviderChoice::OpenAiCompat,
+ "openai-oauth" | "openai_oauth" => ProviderChoice::OpenAiOAuth,
+ "copilot" | "github-copilot" | "github_copilot" => ProviderChoice::Copilot,
other => {
return Err(LlmError::NotConfigured(format!(
"AI_MEMORY_LLM_PROVIDER={other} is not one of \
- anthropic|openai|gemini|openai-compat"
+ anthropic|openai|gemini|openai-compat|openai-oauth|copilot"
)));
}
};
@@ -325,6 +338,8 @@ impl Config {
ProviderChoice::Anthropic => "claude-sonnet-4-6".to_string(),
ProviderChoice::OpenAi => "gpt-4o-mini".to_string(),
ProviderChoice::Gemini => "gemini-2.5-flash".to_string(),
+ ProviderChoice::OpenAiOAuth => "gpt-5.5".to_string(),
+ ProviderChoice::Copilot => "gpt-5.5".to_string(),
ProviderChoice::OpenAiCompat => {
return Err(LlmError::NotConfigured(
"AI_MEMORY_LLM_MODEL must be set explicitly for openai-compat \
@@ -337,7 +352,7 @@ impl Config {
Ok(Some(ProviderConfig {
provider,
model,
- api_key: self.provider_api_key(provider),
+ auth: self.provider_auth(provider, None),
base_url: self.llm_base_url.clone(),
}))
}
@@ -418,6 +433,72 @@ impl Config {
ProviderChoice::OpenAi => self.runtime_env.openai_api_key.clone(),
ProviderChoice::Gemini => self.runtime_env.gemini_api_key.clone(),
ProviderChoice::OpenAiCompat => self.runtime_env.llm_api_key.clone(),
+ ProviderChoice::OpenAiOAuth => None,
+ ProviderChoice::Copilot => None,
+ }
+ }
+
+ /// Shared provider auth token file path.
+ #[must_use]
+ pub fn auth_token_path(&self) -> PathBuf {
+ self.data_dir.join("auth.json")
+ }
+
+ /// Shared OpenAI OAuth token file path.
+ #[must_use]
+ pub fn openai_oauth_token_path(&self) -> PathBuf {
+ self.auth_token_path()
+ }
+
+ /// Shared Copilot auth token file path.
+ #[must_use]
+ pub fn copilot_token_path(&self) -> PathBuf {
+ self.auth_token_path()
+ }
+
+ /// GitHub token resolved for Copilot auth login/provider use.
+ #[must_use]
+ pub fn copilot_github_token(&self) -> Option<SecretString> {
+ self.runtime_env.copilot_github_token.clone()
+ }
+
+ /// Copilot OAuth client id override for `auth login copilot`.
+ #[must_use]
+ pub fn copilot_client_id(&self) -> Option<&str> {
+ self.runtime_env.copilot_client_id.as_deref()
+ }
+
+ /// Resolve typed auth material for a provider.
+ ///
+ /// `api_key_override` is used by `llm-test --api-key`; normal server
+ /// startup passes `None` so env/config resolution remains the single path.
+ #[must_use]
+ pub fn provider_auth(
+ &self,
+ provider: ProviderChoice,
+ api_key_override: Option<SecretString>,
+ ) -> ProviderAuth {
+ match provider.auth_requirement() {
+ AuthRequirement::RequiredApiKey { env_var } => {
+ ProviderAuth::required_api_key_from_env(env_var, self.provider_api_key(provider))
+ .with_cli_api_key_override(api_key_override)
+ }
+ AuthRequirement::OptionalApiKey { env_var } => {
+ ProviderAuth::optional_api_key_from_env(env_var, self.provider_api_key(provider))
+ .with_cli_api_key_override(api_key_override)
+ }
+ AuthRequirement::OpenAiOAuthToken => {
+ ProviderAuth::openai_oauth_token_file(self.openai_oauth_token_path())
+ }
+ AuthRequirement::CopilotToken => ProviderAuth::copilot(
+ self.copilot_token_path(),
+ self.runtime_env.copilot_github_token.clone(),
+ self.runtime_env.github_copilot_api_token.clone(),
+ self.runtime_env
+ .copilot_api_url
+ .clone()
+ .or_else(|| self.llm_base_url.clone()),
+ ),
}
}
@@ -595,4 +676,118 @@ mod tests {
let err = cfg.embedder_config().unwrap_err();
assert!(matches!(err, LlmError::NotConfigured(msg) if msg == "OPENAI_API_KEY"));
}
+
+ #[test]
+ fn llm_provider_config_uses_typed_provider_auth() {
+ let cfg = Config {
+ llm_provider: Some("openai".into()),
+ runtime_env: RuntimeEnv {
+ openai_api_key: Some(SecretString::from("sk-test-key")),
+ ..RuntimeEnv::default()
+ },
+ ..Config::default()
+ };
+
+ let provider = cfg.llm_provider_config().unwrap().unwrap();
+ assert_eq!(provider.provider, ProviderChoice::OpenAi);
+ assert_eq!(provider.model, "gpt-4o-mini");
+ assert_eq!(
+ provider.auth.requirement(),
+ AuthRequirement::RequiredApiKey {
+ env_var: "OPENAI_API_KEY"
+ }
+ );
+ assert_eq!(
+ provider.auth.source(),
+ ai_memory_llm::CredentialSource::Environment {
+ name: "OPENAI_API_KEY"
+ }
+ );
+ assert_eq!(
+ provider.auth.require_api_key().unwrap().expose_secret(),
+ "sk-test-key"
+ );
+ }
+
+ #[test]
+ fn llm_test_api_key_override_wins_over_env_auth() {
+ let cfg = Config {
+ runtime_env: RuntimeEnv {
+ openai_api_key: Some(SecretString::from("env-key")),
+ ..RuntimeEnv::default()
+ },
+ ..Config::default()
+ };
+
+ let auth = cfg.provider_auth(
+ ProviderChoice::OpenAi,
+ Some(SecretString::from("override-key")),
+ );
+
+ assert_eq!(auth.source(), ai_memory_llm::CredentialSource::CliOverride);
+ assert_eq!(
+ auth.require_api_key().unwrap().expose_secret(),
+ "override-key"
+ );
+ }
+
+ #[test]
+ fn openai_compat_auth_remains_optional() {
+ let cfg = Config::default();
+
+ let auth = cfg.provider_auth(ProviderChoice::OpenAiCompat, None);
+
+ assert_eq!(
+ auth.requirement(),
+ AuthRequirement::OptionalApiKey {
+ env_var: "LLM_API_KEY"
+ }
+ );
+ assert!(auth.optional_api_key().is_none());
+ }
+
+ #[test]
+ fn openai_oauth_provider_uses_data_dir_token_file() {
+ let tmp = TempDir::new().unwrap();
+ let cfg = Config {
+ data_dir: tmp.path().to_path_buf(),
+ llm_provider: Some("openai-oauth".into()),
+ ..Config::default()
+ };
+
+ let provider = cfg.llm_provider_config().unwrap().unwrap();
+
+ assert_eq!(provider.provider, ProviderChoice::OpenAiOAuth);
+ assert_eq!(provider.model, "gpt-5.5");
+ assert_eq!(
+ provider.auth.requirement(),
+ AuthRequirement::OpenAiOAuthToken
+ );
+ assert_eq!(
+ provider.auth.require_openai_oauth_token_file().unwrap(),
+ tmp.path().join("auth.json")
+ );
+ }
+
+ #[test]
+ fn copilot_provider_uses_data_dir_token_file_and_env_token() {
+ let tmp = TempDir::new().unwrap();
+ let cfg = Config {
+ data_dir: tmp.path().to_path_buf(),
+ llm_provider: Some("copilot".into()),
+ runtime_env: RuntimeEnv {
+ copilot_github_token: Some(SecretString::from("ghu-test")),
+ ..RuntimeEnv::default()
+ },
+ ..Config::default()
+ };
+
+ let provider = cfg.llm_provider_config().unwrap().unwrap();
+ let auth = provider.auth.require_copilot_auth().unwrap();
+
+ assert_eq!(provider.provider, ProviderChoice::Copilot);
+ assert_eq!(provider.model, "gpt-5.5");
+ assert_eq!(auth.token_file, tmp.path().join("auth.json"));
+ assert_eq!(auth.github_token.unwrap().expose_secret(), "ghu-test");
+ }
}
diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rs
index 241186f6..bce9fea7 100644
--- a/crates/ai-memory-cli/src/main.rs
+++ b/crates/ai-memory-cli/src/main.rs
@@ -62,5 +62,6 @@ async fn main() -> Result<()> {
Command::PurgeProject(args) => commands::purge_project::run(&config, args).await,
Command::RenameProject(args) => commands::rename_project::run(&config, args).await,
Command::Uninstall(args) => commands::uninstall::run(&config, args),
+ Command::Auth(args) => commands::auth::run(&config, args).await,
}
}
diff --git a/crates/ai-memory-llm/Cargo.toml b/crates/ai-memory-llm/Cargo.toml
index 00640ab6..a7960e33 100644
--- a/crates/ai-memory-llm/Cargo.toml
+++ b/crates/ai-memory-llm/Cargo.toml
@@ -6,7 +6,7 @@ rust-version.workspace = true
license.workspace = true
repository.workspace = true
authors.workspace = true
-description = "LLM provider trait with typed Anthropic, OpenAI and OpenAI-compat clients."
+description = "LLM provider trait with typed Anthropic, OpenAI, Gemini, OpenAI OAuth, GitHub Copilot and OpenAI-compat clients."
[dependencies]
ai-memory-core.workspace = true
@@ -21,9 +21,12 @@ tracing.workspace = true
reqwest.workspace = true
async-trait.workspace = true
regex.workspace = true
+base64.workspace = true
+uuid.workspace = true
[dev-dependencies]
tokio = { workspace = true }
+tempfile.workspace = true
[lints]
workspace = true
diff --git a/crates/ai-memory-llm/src/auth.rs b/crates/ai-memory-llm/src/auth.rs
new file mode 100644
index 00000000..2cd81bad
--- /dev/null
+++ b/crates/ai-memory-llm/src/auth.rs
@@ -0,0 +1,322 @@
+//! Provider authentication material.
+//!
+//! This module is the narrow boundary between configuration / login flows and
+//! provider wire clients. API-key, OAuth-token-file, and token-exchange backed
+//! providers extend this layer instead of teaching each provider to read env
+//! vars directly.
+
+use std::path::{Path, PathBuf};
+
+use secrecy::SecretString;
+
+use crate::error::{LlmError, LlmResult};
+
+/// Credential source used for diagnostics and future `auth status` output.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CredentialSource {
+ /// Explicit CLI argument, such as `llm-test --api-key`.
+ CliOverride,
+ /// Process environment variable.
+ Environment {
+ /// Environment variable name.
+ name: &'static str,
+ },
+ /// On-disk token file under ai-memory's data dir.
+ TokenFile,
+ /// No credential was supplied.
+ NotProvided,
+}
+
+/// Auth requirement declared by a provider.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AuthRequirement {
+ /// Provider cannot be constructed without an API key.
+ RequiredApiKey {
+ /// Environment variable operators normally use for this API key.
+ env_var: &'static str,
+ },
+ /// Provider accepts an API key but can also run without one.
+ OptionalApiKey {
+ /// Environment variable operators normally use for this API key.
+ env_var: &'static str,
+ },
+ /// Provider requires a ChatGPT/Codex OAuth token file.
+ OpenAiOAuthToken,
+ /// Provider requires a GitHub token or stored auth for Copilot.
+ CopilotToken,
+}
+
+/// Resolved Copilot auth inputs.
+#[derive(Debug, Clone)]
+pub struct CopilotAuth {
+ /// Shared auth file under ai-memory's data dir.
+ pub token_file: PathBuf,
+ /// GitHub user token from env/config, if present.
+ pub github_token: Option<SecretString>,
+ /// Direct short-lived Copilot API token from env/config, if present.
+ pub direct_api_token: Option<SecretString>,
+ /// Optional Copilot API base URL override.
+ pub api_base_url: Option<String>,
+}
+
+/// Materialized provider credential.
+#[derive(Debug, Clone)]
+pub enum Credential {
+ /// Static API key / bearer secret.
+ ApiKey(SecretString),
+ /// Path to the OpenAI OAuth token file.
+ OpenAiOAuthTokenFile(PathBuf),
+ /// GitHub Copilot auth inputs.
+ Copilot(CopilotAuth),
+}
+
+/// Resolved authentication for one provider instance.
+#[derive(Debug, Clone)]
+pub struct ProviderAuth {
+ requirement: AuthRequirement,
+ credential: Option<Credential>,
+ source: CredentialSource,
+}
+
+impl ProviderAuth {
+ /// Resolve a required API-key auth method from an environment value.
+ #[must_use]
+ pub fn required_api_key_from_env(env_var: &'static str, key: Option<SecretString>) -> Self {
+ Self::from_api_key(
+ AuthRequirement::RequiredApiKey { env_var },
+ key,
+ CredentialSource::Environment { name: env_var },
+ )
+ }
+
+ /// Resolve an optional API-key auth method from an environment value.
+ #[must_use]
+ pub fn optional_api_key_from_env(env_var: &'static str, key: Option<SecretString>) -> Self {
+ Self::from_api_key(
+ AuthRequirement::OptionalApiKey { env_var },
+ key,
+ CredentialSource::Environment { name: env_var },
+ )
+ }
+
+ /// Resolve OpenAI OAuth auth from a token file path.
+ #[must_use]
+ pub fn openai_oauth_token_file(path: impl Into<PathBuf>) -> Self {
+ Self {
+ requirement: AuthRequirement::OpenAiOAuthToken,
+ credential: Some(Credential::OpenAiOAuthTokenFile(path.into())),
+ source: CredentialSource::TokenFile,
+ }
+ }
+
+ /// Resolve Copilot auth from a shared token file plus optional env tokens.
+ #[must_use]
+ pub fn copilot(
+ token_file: impl Into<PathBuf>,
+ github_token: Option<SecretString>,
+ direct_api_token: Option<SecretString>,
+ api_base_url: Option<String>,
+ ) -> Self {
+ Self {
+ requirement: AuthRequirement::CopilotToken,
+ credential: Some(Credential::Copilot(CopilotAuth {
+ token_file: token_file.into(),
+ github_token,
+ direct_api_token,
+ api_base_url,
+ })),
+ source: CredentialSource::TokenFile,
+ }
+ }
+
+ fn from_api_key(
+ requirement: AuthRequirement,
+ key: Option<SecretString>,
+ source_if_present: CredentialSource,
+ ) -> Self {
+ let has_key = key.is_some();
+ Self {
+ requirement,
+ credential: key.map(Credential::ApiKey),
+ source: if has_key {
+ source_if_present
+ } else {
+ CredentialSource::NotProvided
+ },
+ }
+ }
+
+ /// Override the resolved credential with a CLI-provided API key.
+ #[must_use]
+ pub fn with_cli_api_key_override(mut self, key: Option<SecretString>) -> Self {
+ if let Some(key) = key {
+ self.credential = Some(Credential::ApiKey(key));
+ self.source = CredentialSource::CliOverride;
+ }
+ self
+ }
+
+ /// Return the declared auth requirement.
+ #[must_use]
+ pub const fn requirement(&self) -> AuthRequirement {
+ self.requirement
+ }
+
+ /// Return where the credential came from, if any.
+ #[must_use]
+ pub const fn source(&self) -> CredentialSource {
+ self.source
+ }
+
+ /// Extract a required API key, preserving today's missing-env error shape.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::NotConfigured`] with the required env var name when
+ /// the provider requires an API key and none was resolved.
+ pub fn require_api_key(&self) -> LlmResult<SecretString> {
+ match (&self.requirement, &self.credential) {
+ (_, Some(Credential::ApiKey(key))) => Ok(key.clone()),
+ (_, Some(Credential::OpenAiOAuthTokenFile(_))) => Err(LlmError::NotConfigured(
+ "API key credential expected, got openai-oauth token file".into(),
+ )),
+ (_, Some(Credential::Copilot(_))) => Err(LlmError::NotConfigured(
+ "API key credential expected, got copilot auth".into(),
+ )),
+ (AuthRequirement::RequiredApiKey { env_var }, None) => {
+ Err(LlmError::NotConfigured((*env_var).into()))
+ }
+ (AuthRequirement::OptionalApiKey { env_var }, None) => {
+ Err(LlmError::NotConfigured((*env_var).into()))
+ }
+ (AuthRequirement::OpenAiOAuthToken, None) => Err(LlmError::NotConfigured(
+ "openai-oauth token file missing; run `ai-memory auth login openai-oauth`".into(),
+ )),
+ (AuthRequirement::CopilotToken, None) => Err(LlmError::NotConfigured(
+ "copilot auth missing; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN"
+ .into(),
+ )),
+ }
+ }
+
+ /// Extract an optional API key.
+ #[must_use]
+ pub fn optional_api_key(&self) -> Option<SecretString> {
+ match &self.credential {
+ Some(Credential::ApiKey(key)) => Some(key.clone()),
+ Some(Credential::OpenAiOAuthTokenFile(_) | Credential::Copilot(_)) | None => None,
+ }
+ }
+
+ /// Extract the OpenAI OAuth token file path.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::NotConfigured`] if this auth material is not an
+ /// OpenAI OAuth token-file credential.
+ pub fn require_openai_oauth_token_file(&self) -> LlmResult<&Path> {
+ match (&self.requirement, &self.credential) {
+ (AuthRequirement::OpenAiOAuthToken, Some(Credential::OpenAiOAuthTokenFile(path))) => {
+ Ok(path)
+ }
+ (AuthRequirement::OpenAiOAuthToken, None) => Err(LlmError::NotConfigured(
+ "openai-oauth token file missing; run `ai-memory auth login openai-oauth`".into(),
+ )),
+ _ => Err(LlmError::NotConfigured(
+ "openai-oauth token file credential required".into(),
+ )),
+ }
+ }
+
+ /// Extract Copilot auth inputs.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::NotConfigured`] if this auth material is not a
+ /// Copilot credential.
+ pub fn require_copilot_auth(&self) -> LlmResult<CopilotAuth> {
+ match (&self.requirement, &self.credential) {
+ (AuthRequirement::CopilotToken, Some(Credential::Copilot(auth))) => Ok(auth.clone()),
+ (AuthRequirement::CopilotToken, None) => Err(LlmError::NotConfigured(
+ "copilot auth missing; run `ai-memory auth login copilot` or set COPILOT_GITHUB_TOKEN"
+ .into(),
+ )),
+ _ => Err(LlmError::NotConfigured(
+ "copilot auth credential required".into(),
+ )),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use secrecy::ExposeSecret as _;
+
+ use super::*;
+
+ #[test]
+ fn required_api_key_reports_env_name_when_missing() {
+ let auth = ProviderAuth::required_api_key_from_env("OPENAI_API_KEY", None);
+ let err = auth.require_api_key().unwrap_err();
+ assert!(matches!(err, LlmError::NotConfigured(msg) if msg == "OPENAI_API_KEY"));
+ assert_eq!(auth.source(), CredentialSource::NotProvided);
+ }
+
+ #[test]
+ fn required_api_key_returns_secret_when_present() {
+ let auth = ProviderAuth::required_api_key_from_env(
+ "OPENAI_API_KEY",
+ Some(SecretString::from("sk-test")),
+ );
+ assert_eq!(auth.require_api_key().unwrap().expose_secret(), "sk-test");
+ assert_eq!(
+ auth.source(),
+ CredentialSource::Environment {
+ name: "OPENAI_API_KEY"
+ }
+ );
+ }
+
+ #[test]
+ fn cli_override_takes_precedence() {
+ let auth = ProviderAuth::required_api_key_from_env(
+ "OPENAI_API_KEY",
+ Some(SecretString::from("env-key")),
+ )
+ .with_cli_api_key_override(Some(SecretString::from("cli-key")));
+
+ assert_eq!(auth.require_api_key().unwrap().expose_secret(), "cli-key");
+ assert_eq!(auth.source(), CredentialSource::CliOverride);
+ }
+
+ #[test]
+ fn optional_api_key_allows_absence() {
+ let auth = ProviderAuth::optional_api_key_from_env("LLM_API_KEY", None);
+ assert!(auth.optional_api_key().is_none());
+ assert_eq!(auth.source(), CredentialSource::NotProvided);
+ }
+
+ #[test]
+ fn openai_oauth_token_file_round_trips_path() {
+ let auth = ProviderAuth::openai_oauth_token_file("/tmp/oauth_token.json");
+ assert_eq!(auth.source(), CredentialSource::TokenFile);
+ assert_eq!(
+ auth.require_openai_oauth_token_file().unwrap(),
+ Path::new("/tmp/oauth_token.json")
+ );
+ }
+
+ #[test]
+ fn copilot_auth_round_trips_inputs() {
+ let auth = ProviderAuth::copilot(
+ "/tmp/auth.json",
+ Some(SecretString::from("ghu-test")),
+ None,
+ Some("https://api.example.test".into()),
+ );
+ let copilot = auth.require_copilot_auth().unwrap();
+ assert_eq!(copilot.token_file, Path::new("/tmp/auth.json"));
+ assert_eq!(copilot.github_token.unwrap().expose_secret(), "ghu-test");
+ assert_eq!(
+ copilot.api_base_url.as_deref(),
+ Some("https://api.example.test")
+ );
+ }
+}
diff --git a/crates/ai-memory-llm/src/auth_file.rs b/crates/ai-memory-llm/src/auth_file.rs
new file mode 100644
index 00000000..71f5faea
--- /dev/null
+++ b/crates/ai-memory-llm/src/auth_file.rs
@@ -0,0 +1,112 @@
+//! Shared JSON auth-file helpers for token-backed providers.
+
+use std::path::Path;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::{Serialize, de::DeserializeOwned};
+
+use crate::error::{LlmError, LlmResult};
+
+pub(crate) fn load_entry<T>(path: &Path, key: &str) -> LlmResult<Option<T>>
+where
+ T: DeserializeOwned,
+{
+ if !path.exists() {
+ return Ok(None);
+ }
+ let bytes = std::fs::read(path)
+ .map_err(|e| LlmError::Auth(format!("read auth file {}: {e}", path.display())))?;
+ let mut value = serde_json::from_slice::<serde_json::Value>(&bytes)
+ .map_err(|e| LlmError::Auth(format!("parse auth file {}: {e}", path.display())))?;
+ let Some(entry) = value.as_object_mut().and_then(|obj| obj.remove(key)) else {
+ return Ok(None);
+ };
+ if entry.get("type").and_then(serde_json::Value::as_str) != Some("oauth") {
+ return Ok(None);
+ }
+ serde_json::from_value::<T>(entry)
+ .map(Some)
+ .map_err(|e| LlmError::Auth(format!("parse {key} auth entry: {e}")))
+}
+
+pub(crate) fn save_entry<T>(path: &Path, key: &str, entry: Option<T>) -> LlmResult<()>
+where
+ T: Serialize,
+{
+ let mut root = if path.exists() {
+ let bytes = std::fs::read(path)
+ .map_err(|e| LlmError::Auth(format!("read auth file {}: {e}", path.display())))?;
+ serde_json::from_slice::<serde_json::Value>(&bytes)
+ .map_err(|e| LlmError::Auth(format!("parse auth file {}: {e}", path.display())))?
+ } else {
+ serde_json::json!({})
+ };
+ if !root.is_object() {
+ return Err(LlmError::Auth(format!(
+ "auth file {} must contain a JSON object",
+ path.display()
+ )));
+ }
+ let Some(obj) = root.as_object_mut() else {
+ return Err(LlmError::Auth(format!(
+ "auth file {} must contain a JSON object",
+ path.display()
+ )));
+ };
+ match entry {
+ Some(entry) => {
+ obj.insert(key.to_string(), serde_json::to_value(entry)?);
+ }
+ None => {
+ obj.remove(key);
+ }
+ }
+ if obj.is_empty() {
+ if path.exists() {
+ std::fs::remove_file(path)
+ .map_err(|e| LlmError::Auth(format!("remove auth file {}: {e}", path.display())))?;
+ }
+ return Ok(());
+ }
+ write_auth_file(path, &root)
+}
+
+fn write_auth_file(path: &Path, value: &serde_json::Value) -> LlmResult<()> {
+ use std::io::Write as _;
+ if let Some(parent) = path.parent() {
+ std::fs::create_dir_all(parent)
+ .map_err(|e| LlmError::Auth(format!("create auth dir {}: {e}", parent.display())))?;
+ }
+ let tmp = path.with_extension("json.tmp");
+ let bytes = serde_json::to_vec_pretty(value)?;
+ {
+ let mut file = std::fs::OpenOptions::new()
+ .create(true)
+ .truncate(true)
+ .write(true)
+ .open(&tmp)
+ .map_err(|e| LlmError::Auth(format!("open auth tmp {}: {e}", tmp.display())))?;
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt as _;
+ file.set_permissions(std::fs::Permissions::from_mode(0o600))
+ .map_err(|e| LlmError::Auth(format!("chmod auth tmp {}: {e}", tmp.display())))?;
+ }
+ file.write_all(&bytes)
+ .map_err(|e| LlmError::Auth(format!("write auth tmp {}: {e}", tmp.display())))?;
+ file.sync_all()
+ .map_err(|e| LlmError::Auth(format!("fsync auth tmp {}: {e}", tmp.display())))?;
+ }
+ std::fs::rename(&tmp, path)
+ .map_err(|e| LlmError::Auth(format!("rename auth file {}: {e}", path.display())))?;
+ Ok(())
+}
+
+pub(crate) fn now_ms() -> u64 {
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_millis()
+ .try_into()
+ .unwrap_or(u64::MAX)
+}
diff --git a/crates/ai-memory-llm/src/copilot.rs b/crates/ai-memory-llm/src/copilot.rs
new file mode 100644
index 00000000..90d64ac7
--- /dev/null
+++ b/crates/ai-memory-llm/src/copilot.rs
@@ -0,0 +1,850 @@
+//! 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};
+
+use crate::auth::CopilotAuth;
+use crate::auth_file::{load_entry, now_ms, save_entry};
+use crate::error::{LlmError, LlmResult};
+use crate::openai::enforce_strict_object_schemas;
+use crate::provider::LlmProvider;
+use crate::text::truncate_with_ellipsis;
+use crate::types::{ChatRequest, ChatResponse, Role, 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)
+ }
+}
+
+/// Copilot provider backed by Copilot chat completions.
+pub struct CopilotProvider {
+ client: reqwest::Client,
+ model: String,
+ auth: CopilotAuth,
+ stored: Mutex<CopilotToken>,
+}
+
+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> {
+ 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()
+ .timeout(Duration::from_secs(300))
+ .user_agent(COPILOT_USER_AGENT)
+ .build()
+ .map_err(LlmError::from)?;
+ Ok(Self {
+ client,
+ model: model.into(),
+ auth,
+ stored: Mutex::new(stored),
+ })
+ }
+
+ 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, &github).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()),
+ })
+ }
+
+ async fn post(&self, body: &CopilotChatRequest<'_>) -> LlmResult<CopilotChatResponse> {
+ let token = self.current_token().await?;
+ let url = format!("{}/chat/completions", token.base_url.trim_end_matches('/'));
+ debug!(url = %url, "POST copilot chat completions");
+ let resp = self
+ .client
+ .post(&url)
+ .bearer_auth(token.access.expose_secret())
+ .headers(copilot_runtime_headers())
+ .json(body)
+ .send()
+ .await
+ .map_err(LlmError::from)?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ return Err(LlmError::Provider {
+ status: status.as_u16(),
+ body: truncate_with_ellipsis(&body, 1024),
+ });
+ }
+ resp.json::<CopilotChatResponse>()
+ .await
+ .map_err(LlmError::from)
+ }
+}
+
+#[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 response = self
+ .post(&build_chat_request(&self.model, &request, None))
+ .await?;
+ Ok(to_chat_response(response))
+ }
+
+ async fn complete_structured_raw(
+ &self,
+ request: ChatRequest,
+ mut schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ enforce_strict_object_schemas(&mut schema);
+ let response_format = CopilotResponseFormat::JsonSchema {
+ json_schema: CopilotJsonSchema {
+ name: "Result".into(),
+ schema,
+ strict: true,
+ },
+ };
+ let response = self
+ .post(&build_chat_request(
+ &self.model,
+ &request,
+ Some(response_format),
+ ))
+ .await?;
+ let text = response
+ .choices
+ .first()
+ .and_then(|c| c.message.content.as_deref())
+ .unwrap_or("");
+ 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,
+}
+
+#[derive(Debug, Deserialize)]
+struct CopilotExchangeResponse {
+ token: String,
+ expires_at: u64,
+}
+
+async fn exchange_copilot_token(
+ client: &reqwest::Client,
+ github_token: &SecretString,
+) -> LlmResult<CopilotApiToken> {
+ let resp = client
+ .get(GITHUB_COPILOT_TOKEN_URL)
+ .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 body = resp.text().await.unwrap_or_default();
+ return Err(LlmError::Auth(format!(
+ "copilot token exchange failed ({status}): {body}"
+ )));
+ }
+ let exchanged = resp
+ .json::<CopilotExchangeResponse>()
+ .await
+ .map_err(LlmError::from)?;
+ 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: match m.role {
+ Role::User => "user",
+ Role::Assistant => "assistant",
+ },
+ 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,
+ }
+}
+
+fn model_uses_default_temperature(model: &str) -> bool {
+ let m = model.to_ascii_lowercase();
+ m.starts_with("gpt-5") || m.starts_with('o')
+}
+
+#[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 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) -> ChatResponse {
+ let text = response
+ .choices
+ .first()
+ .and_then(|c| c.message.content.as_deref())
+ .unwrap_or_default()
+ .to_string();
+ 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 secrecy::ExposeSecret as _;
+ use serde_json::json;
+
+ use super::*;
+
+ #[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 {
+ role: Role::User,
+ content: "hello".into(),
+ }],
+ 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 structured_request_uses_json_schema_format() {
+ let request = ChatRequest::user_prompt("json please");
+ let response_format = CopilotResponseFormat::JsonSchema {
+ json_schema: CopilotJsonSchema {
+ name: "Result".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);
+ }
+}
diff --git a/crates/ai-memory-llm/src/error.rs b/crates/ai-memory-llm/src/error.rs
index 1780ced3..5e88e5ea 100644
--- a/crates/ai-memory-llm/src/error.rs
+++ b/crates/ai-memory-llm/src/error.rs
@@ -35,6 +35,10 @@ pub enum LlmError {
#[error("provider not configured: {0}")]
NotConfigured(String),
+ /// Provider authentication failed or expired.
+ #[error("auth: {0}")]
+ Auth(String),
+
/// JSON schema for structured output could not be derived.
#[error("schema: {0}")]
Schema(String),
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index 0fc9a141..233ba4d2 100644
--- a/crates/ai-memory-llm/src/factory.rs
+++ b/crates/ai-memory-llm/src/factory.rs
@@ -8,15 +8,18 @@ use std::sync::Arc;
use secrecy::SecretString;
use crate::AnthropicProvider;
+use crate::CopilotProvider;
use crate::GeminiProvider;
use crate::OpenAiCompatProvider;
+use crate::OpenAiOAuthProvider;
use crate::OpenAiProvider;
+use crate::auth::{AuthRequirement, ProviderAuth};
use crate::embedding::{Embedder, OpenAiEmbedder, VoyageEmbedder};
use crate::error::{LlmError, LlmResult};
use crate::google::GoogleEmbedder;
use crate::provider::LlmProvider;
-/// Four providers ship in v1.
+/// LLM providers available to ai-memory.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProviderChoice {
/// Anthropic Messages API.
@@ -27,17 +30,44 @@ pub enum ProviderChoice {
Gemini,
/// OpenAI-compatible (Ollama / vLLM / LM Studio).
OpenAiCompat,
+ /// OpenAI ChatGPT/Codex OAuth backend.
+ OpenAiOAuth,
+ /// GitHub Copilot Chat backend.
+ Copilot,
}
-/// All settings needed to construct one of the three providers.
+impl ProviderChoice {
+ /// Auth requirement for this provider.
+ #[must_use]
+ pub const fn auth_requirement(self) -> AuthRequirement {
+ match self {
+ Self::Anthropic => AuthRequirement::RequiredApiKey {
+ env_var: "ANTHROPIC_API_KEY",
+ },
+ Self::OpenAi => AuthRequirement::RequiredApiKey {
+ env_var: "OPENAI_API_KEY",
+ },
+ Self::Gemini => AuthRequirement::RequiredApiKey {
+ env_var: "GEMINI_API_KEY",
+ },
+ Self::OpenAiCompat => AuthRequirement::OptionalApiKey {
+ env_var: "LLM_API_KEY",
+ },
+ Self::OpenAiOAuth => AuthRequirement::OpenAiOAuthToken,
+ Self::Copilot => AuthRequirement::CopilotToken,
+ }
+ }
+}
+
+/// All settings needed to construct one LLM provider instance.
#[derive(Debug, Clone)]
pub struct ProviderConfig {
/// Provider selection.
pub provider: ProviderChoice,
/// Model id (`claude-opus-4-7`, `gpt-4o-mini`, `llama3.1:8b`, …).
pub model: String,
- /// API key. Required for Anthropic + OpenAI; optional for compat.
- pub api_key: Option<SecretString>,
+ /// Resolved provider authentication material.
+ pub auth: ProviderAuth,
/// Base URL override (required for OpenAI-compat).
pub base_url: Option<String>,
}
@@ -138,21 +168,15 @@ pub fn default_embedding_dim(provider: EmbedderChoice, model: &str) -> u32 {
pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>> {
match config.provider {
ProviderChoice::Anthropic => {
- let key = config
- .api_key
- .ok_or_else(|| LlmError::NotConfigured("ANTHROPIC_API_KEY".into()))?;
+ let key = config.auth.require_api_key()?;
Ok(Arc::new(AnthropicProvider::new(key, config.model)?))
}
ProviderChoice::OpenAi => {
- let key = config
- .api_key
- .ok_or_else(|| LlmError::NotConfigured("OPENAI_API_KEY".into()))?;
+ let key = config.auth.require_api_key()?;
Ok(Arc::new(OpenAiProvider::new(key, config.model)?))
}
ProviderChoice::Gemini => {
- let key = config
- .api_key
- .ok_or_else(|| LlmError::NotConfigured("GEMINI_API_KEY".into()))?;
+ let key = config.auth.require_api_key()?;
Ok(Arc::new(GeminiProvider::new(key, config.model)?))
}
ProviderChoice::OpenAiCompat => {
@@ -161,9 +185,74 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>
.ok_or_else(|| LlmError::NotConfigured("LLM_BASE_URL".into()))?;
Ok(Arc::new(OpenAiCompatProvider::new(
base,
- config.api_key,
+ config.auth.optional_api_key(),
config.model,
)?))
}
+ ProviderChoice::OpenAiOAuth => {
+ let path = config.auth.require_openai_oauth_token_file()?.to_path_buf();
+ Ok(Arc::new(OpenAiOAuthProvider::new(path, config.model)?))
+ }
+ ProviderChoice::Copilot => {
+ let auth = config.auth.require_copilot_auth()?;
+ Ok(Arc::new(CopilotProvider::new(auth, config.model)?))
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn provider_choices_declare_current_auth_requirements() {
+ assert_eq!(
+ ProviderChoice::Anthropic.auth_requirement(),
+ AuthRequirement::RequiredApiKey {
+ env_var: "ANTHROPIC_API_KEY"
+ }
+ );
+ assert_eq!(
+ ProviderChoice::OpenAi.auth_requirement(),
+ AuthRequirement::RequiredApiKey {
+ env_var: "OPENAI_API_KEY"
+ }
+ );
+ assert_eq!(
+ ProviderChoice::Gemini.auth_requirement(),
+ AuthRequirement::RequiredApiKey {
+ env_var: "GEMINI_API_KEY"
+ }
+ );
+ assert_eq!(
+ ProviderChoice::OpenAiCompat.auth_requirement(),
+ AuthRequirement::OptionalApiKey {
+ env_var: "LLM_API_KEY"
+ }
+ );
+ assert_eq!(
+ ProviderChoice::OpenAiOAuth.auth_requirement(),
+ AuthRequirement::OpenAiOAuthToken
+ );
+ assert_eq!(
+ ProviderChoice::Copilot.auth_requirement(),
+ AuthRequirement::CopilotToken
+ );
+ }
+
+ #[test]
+ fn missing_required_provider_auth_preserves_error_shape() {
+ let cfg = ProviderConfig {
+ provider: ProviderChoice::OpenAi,
+ model: "gpt-4o-mini".into(),
+ auth: ProviderAuth::required_api_key_from_env("OPENAI_API_KEY", None),
+ base_url: None,
+ };
+
+ let err = match build_provider(cfg) {
+ Ok(_) => panic!("provider should fail without OPENAI_API_KEY"),
+ Err(err) => err,
+ };
+ assert!(matches!(err, LlmError::NotConfigured(msg) if msg == "OPENAI_API_KEY"));
}
}
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index 6df853f9..077f4156 100644
--- a/crates/ai-memory-llm/src/lib.rs
+++ b/crates/ai-memory-llm/src/lib.rs
@@ -1,6 +1,6 @@
//! LLM provider abstraction for ai-memory.
//!
-//! Four providers ship in v1, each with a *native, typed*
+//! Each provider ships with a *native, typed*
//! `reqwest`-based client — never a generic gateway. The cognee
//! issue tracker showed that LiteLLM + Instructor silently drop
//! unknown kwargs, which makes the wrapper layer drift away from
@@ -8,12 +8,16 @@
//! Our clients deserialise into named structs that `serde` rejects
//! on unknown fields, surfacing breakage immediately.
//!
-//! Four structured-output strategies:
+//! Structured-output strategies:
//!
//! * **Anthropic**: `tools[0]` is set to a single tool whose input
//! schema we want filled, with `tool_choice = "tool"`. The
//! model's `tool_use` content block is the structured payload.
//! * **OpenAI**: `response_format = { type: "json_schema", strict: true }`.
+//! * **OpenAI OAuth/Codex**: ChatGPT/Codex Responses API with
+//! `text.format = { type: "json_schema", strict: true }`.
+//! * **GitHub Copilot**: GitHub token exchange to a short-lived Copilot API
+//! token, then OpenAI-style Chat Completions with JSON schema format.
//! * **Gemini**: `generationConfig.responseMimeType = "application/json"`
//! plus `responseSchema` (OpenAPI 3 subset; `$ref`s inlined,
//! Draft-2020-12 keywords stripped before send).
@@ -23,6 +27,8 @@
//! No tenacity-style 8-128s backoff (cognee #2840 lesson).
pub mod anthropic;
+pub mod auth;
+pub mod copilot;
pub mod embedding;
pub mod error;
pub mod factory;
@@ -30,12 +36,20 @@ pub mod gemini;
pub mod google;
pub mod openai;
pub mod openai_compat;
+pub mod openai_oauth;
pub mod provider;
pub mod types;
+mod auth_file;
mod text;
pub use anthropic::AnthropicProvider;
+pub use auth::{AuthRequirement, CopilotAuth, Credential, CredentialSource, ProviderAuth};
+pub use copilot::{
+ COPILOT_INTEGRATION_ID, CopilotProvider, CopilotToken, DEFAULT_COPILOT_API_BASE_URL,
+ GITHUB_ACCESS_TOKEN_URL, GITHUB_COPILOT_CLIENT_ID, GITHUB_COPILOT_TOKEN_URL,
+ GITHUB_DEVICE_CODE_URL,
+};
pub use embedding::{Embedder, OpenAiEmbedder, SyntheticEmbedder, VoyageEmbedder, cosine};
pub use error::{LlmError, LlmResult};
pub use factory::{
@@ -46,5 +60,9 @@ pub use gemini::GeminiProvider;
pub use google::{DEFAULT_MODEL as GOOGLE_DEFAULT_EMBED_MODEL, GoogleEmbedder};
pub use openai::OpenAiProvider;
pub use openai_compat::OpenAiCompatProvider;
+pub use openai_oauth::{
+ CODEX_CLIENT_ID, CODEX_RESPONSES_URL, OPENAI_OAUTH_AUTH_URL, OPENAI_OAUTH_ISSUER,
+ OPENAI_OAUTH_TOKEN_URL, OpenAiOAuthProvider, OpenAiOAuthToken, OpenAiOAuthTokenResponse,
+};
pub use provider::{LlmProvider, complete_structured};
pub use types::{ChatMessage, ChatRequest, ChatResponse, Role, Usage};
diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rs
index 8b4048a6..1794f46e 100644
--- a/crates/ai-memory-llm/src/openai.rs
+++ b/crates/ai-memory-llm/src/openai.rs
@@ -343,7 +343,7 @@ impl OpenAiProvider {
/// and re-introduce the 400 this function exists to prevent. Callers
/// that need looser schemas should use the `Compat` dialect (which
/// skips this normalisation entirely) or a non-strict path.
-fn enforce_strict_object_schemas(value: &mut serde_json::Value) {
+pub(crate) fn enforce_strict_object_schemas(value: &mut serde_json::Value) {
match value {
serde_json::Value::Object(map) => {
// OpenAI's structured-output subset rejects any sibling
diff --git a/crates/ai-memory-llm/src/openai_oauth.rs b/crates/ai-memory-llm/src/openai_oauth.rs
new file mode 100644
index 00000000..b76610c9
--- /dev/null
+++ b/crates/ai-memory-llm/src/openai_oauth.rs
@@ -0,0 +1,671 @@
+//! OpenAI ChatGPT/Codex OAuth provider.
+//!
+//! This is intentionally not a thin wrapper around `api.openai.com`: ChatGPT
+//! OAuth access tokens are Codex/ChatGPT credentials, not Platform API keys.
+//! Requests go to the Codex Responses backend and include the account id when
+//! the token exposes one.
+
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use async_trait::async_trait;
+use base64::Engine as _;
+use secrecy::{ExposeSecret as _, SecretString};
+use serde::{Deserialize, Serialize};
+use tokio::sync::Mutex;
+use tracing::{debug, info};
+
+use crate::auth_file::{load_entry, now_ms, save_entry};
+use crate::error::{LlmError, LlmResult};
+use crate::openai::enforce_strict_object_schemas;
+use crate::provider::LlmProvider;
+use crate::text::truncate_with_ellipsis;
+use crate::types::{ChatRequest, ChatResponse, Role, Usage};
+
+/// OpenAI OAuth issuer used by Codex/OpenCode.
+pub const OPENAI_OAUTH_ISSUER: &str = "https://auth.openai.com";
+
+/// OpenAI OAuth authorization endpoint.
+pub const OPENAI_OAUTH_AUTH_URL: &str = "https://auth.openai.com/oauth/authorize";
+
+/// OpenAI OAuth token endpoint.
+pub const OPENAI_OAUTH_TOKEN_URL: &str = "https://auth.openai.com/oauth/token";
+
+/// ChatGPT/Codex Responses backend.
+pub const CODEX_RESPONSES_URL: &str = "https://chatgpt.com/backend-api/codex/responses";
+
+/// Public Codex/OpenCode OAuth client id.
+pub const CODEX_CLIENT_ID: &str = "app_EMoamEEZ73f0CkXaXp7hrann";
+
+/// Scopes used by Codex/OpenCode for ChatGPT sign-in.
+pub const OAUTH_SCOPES: &str = "openid profile email offline_access";
+
+const REFRESH_MARGIN_MS: u64 = 60_000;
+
+/// Stored OpenAI OAuth token.
+#[derive(Clone)]
+pub struct OpenAiOAuthToken {
+ /// Access token sent as the bearer token.
+ pub access: SecretString,
+ /// Refresh token used to mint a new access token.
+ pub refresh: SecretString,
+ /// Expiry in milliseconds since Unix epoch.
+ pub expires_at_ms: u64,
+ /// ChatGPT account/workspace id, when present in the token claims.
+ pub account_id: Option<String>,
+}
+
+impl std::fmt::Debug for OpenAiOAuthToken {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("OpenAiOAuthToken")
+ .field("access", &"<redacted>")
+ .field("refresh", &"<redacted>")
+ .field("expires_at_ms", &self.expires_at_ms)
+ .field("account_id", &self.account_id)
+ .finish()
+ }
+}
+
+impl OpenAiOAuthToken {
+ /// Build a token from an OAuth token response.
+ #[must_use]
+ pub fn from_token_response(
+ access: impl Into<String>,
+ refresh: impl Into<String>,
+ expires_in_secs: u64,
+ id_token: Option<&str>,
+ previous_account_id: Option<String>,
+ ) -> Self {
+ let access = access.into();
+ let account_id = id_token
+ .and_then(extract_account_id_from_jwt)
+ .or_else(|| extract_account_id_from_jwt(&access))
+ .or(previous_account_id);
+ Self {
+ access: SecretString::from(access),
+ refresh: SecretString::from(refresh.into()),
+ expires_at_ms: now_ms().saturating_add(expires_in_secs.saturating_mul(1000)),
+ account_id,
+ }
+ }
+
+ /// True when the access token is expired or within the refresh margin.
+ #[must_use]
+ pub fn needs_refresh(&self) -> bool {
+ now_ms().saturating_add(REFRESH_MARGIN_MS) >= self.expires_at_ms
+ }
+
+ /// Load the OpenAI OAuth token from a shared token 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::<OAuthEntry>(path, "openai")? else {
+ return Ok(None);
+ };
+ if entry.kind != "oauth" {
+ return Ok(None);
+ }
+ Ok(Some(Self {
+ access: SecretString::from(entry.access),
+ refresh: SecretString::from(entry.refresh),
+ expires_at_ms: entry.expires,
+ account_id: entry.account_id,
+ }))
+ }
+
+ /// Save the token into the shared token file, preserving unknown keys.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::Auth`] when the file cannot be written.
+ pub fn save(&self, path: &Path) -> LlmResult<()> {
+ let entry = OAuthEntry {
+ kind: "oauth".into(),
+ access: self.access.expose_secret().to_string(),
+ refresh: self.refresh.expose_secret().to_string(),
+ expires: self.expires_at_ms,
+ account_id: self.account_id.clone(),
+ };
+ save_entry(path, "openai", Some(entry))
+ }
+
+ /// Remove the OpenAI entry from the shared token file.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::Auth`] when the file cannot be updated.
+ pub fn remove(path: &Path) -> LlmResult<()> {
+ save_entry::<OAuthEntry>(path, "openai", None)
+ }
+}
+
+/// OAuth token response returned by `auth.openai.com`.
+#[derive(Debug, Deserialize)]
+pub struct OpenAiOAuthTokenResponse {
+ /// Access token.
+ pub access_token: String,
+ /// Refresh token. Refresh responses may omit it, meaning keep old refresh.
+ #[serde(default)]
+ pub refresh_token: Option<String>,
+ /// Expires-in seconds. Codex/OpenCode default to one hour when omitted.
+ #[serde(default)]
+ pub expires_in: Option<u64>,
+ /// Optional ID token carrying ChatGPT account claims.
+ #[serde(default)]
+ pub id_token: Option<String>,
+}
+
+/// OpenAI OAuth provider backed by the ChatGPT/Codex Responses endpoint.
+pub struct OpenAiOAuthProvider {
+ client: reqwest::Client,
+ model: String,
+ token_path: PathBuf,
+ token: Mutex<OpenAiOAuthToken>,
+}
+
+impl OpenAiOAuthProvider {
+ /// Build a provider from an OAuth token file.
+ ///
+ /// # Errors
+ /// Returns [`LlmError::NotConfigured`] when no token is present.
+ pub fn new(token_path: PathBuf, model: impl Into<String>) -> LlmResult<Self> {
+ let token = OpenAiOAuthToken::load(&token_path)?.ok_or_else(|| {
+ LlmError::NotConfigured(format!(
+ "no openai-oauth token found at {}; run `ai-memory auth login openai-oauth`",
+ token_path.display()
+ ))
+ })?;
+ let client = reqwest::Client::builder()
+ .timeout(Duration::from_secs(300))
+ .build()
+ .map_err(LlmError::from)?;
+ Ok(Self {
+ client,
+ model: model.into(),
+ token_path,
+ token: Mutex::new(token),
+ })
+ }
+
+ async fn current_token(&self) -> LlmResult<OpenAiOAuthToken> {
+ let mut guard = self.token.lock().await;
+ if guard.needs_refresh() {
+ info!("openai-oauth token expired or near-expiry, refreshing");
+ let refreshed = refresh_access_token(&self.client, &guard).await?;
+ refreshed.save(&self.token_path)?;
+ *guard = refreshed;
+ }
+ Ok(guard.clone())
+ }
+
+ async fn post(&self, body: &CodexResponsesRequest<'_>) -> LlmResult<CodexResponsesResponse> {
+ let token = self.current_token().await?;
+ debug!(
+ url = CODEX_RESPONSES_URL,
+ "POST openai-oauth codex responses"
+ );
+ let mut request = self
+ .client
+ .post(CODEX_RESPONSES_URL)
+ .bearer_auth(token.access.expose_secret())
+ .header("content-type", "application/json")
+ .header("accept", "application/json")
+ .header("openai-beta", "responses=experimental")
+ .header("originator", "codex_cli_rs")
+ .header("session_id", uuid::Uuid::new_v4().to_string())
+ .json(body);
+ if let Some(account_id) = token.account_id.as_deref() {
+ request = request.header("chatgpt-account-id", account_id);
+ }
+ let resp = request.send().await.map_err(LlmError::from)?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ return Err(LlmError::Provider {
+ status: status.as_u16(),
+ body: truncate_with_ellipsis(&body, 1024),
+ });
+ }
+ resp.json::<CodexResponsesResponse>()
+ .await
+ .map_err(LlmError::from)
+ }
+}
+
+#[async_trait]
+impl LlmProvider for OpenAiOAuthProvider {
+ fn name(&self) -> &'static str {
+ "openai-oauth"
+ }
+
+ fn model(&self) -> &str {
+ &self.model
+ }
+
+ async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
+ let response = self
+ .post(&build_request(&self.model, &request, None))
+ .await?;
+ Ok(into_chat_response(response))
+ }
+
+ async fn complete_structured_raw(
+ &self,
+ request: ChatRequest,
+ mut schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ enforce_strict_object_schemas(&mut schema);
+ let response_format = CodexText {
+ format: CodexTextFormat::JsonSchema {
+ name: "Result".into(),
+ schema,
+ strict: true,
+ },
+ };
+ let response = self
+ .post(&build_request(&self.model, &request, Some(response_format)))
+ .await?;
+ let text = extract_output_text(&response).unwrap_or_default();
+ serde_json::from_str::<serde_json::Value>(&text).map_err(LlmError::from)
+ }
+}
+
+async fn refresh_access_token(
+ client: &reqwest::Client,
+ current: &OpenAiOAuthToken,
+) -> LlmResult<OpenAiOAuthToken> {
+ let resp = client
+ .post(OPENAI_OAUTH_TOKEN_URL)
+ .header("content-type", "application/x-www-form-urlencoded")
+ .form(&[
+ ("grant_type", "refresh_token"),
+ ("refresh_token", current.refresh.expose_secret()),
+ ("client_id", CODEX_CLIENT_ID),
+ ])
+ .send()
+ .await
+ .map_err(LlmError::from)?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ return Err(LlmError::Auth(format!(
+ "openai-oauth refresh failed ({status}): {body}. Run `ai-memory auth login openai-oauth` again."
+ )));
+ }
+ let token_response = resp
+ .json::<OpenAiOAuthTokenResponse>()
+ .await
+ .map_err(LlmError::from)?;
+ Ok(OpenAiOAuthToken::from_token_response(
+ token_response.access_token,
+ token_response
+ .refresh_token
+ .unwrap_or_else(|| current.refresh.expose_secret().to_string()),
+ token_response.expires_in.unwrap_or(3600),
+ token_response.id_token.as_deref(),
+ current.account_id.clone(),
+ ))
+}
+
+fn build_request<'a>(
+ model: &'a str,
+ request: &'a ChatRequest,
+ text: Option<CodexText>,
+) -> CodexResponsesRequest<'a> {
+ let input = request
+ .messages
+ .iter()
+ .map(|msg| CodexInputMessage {
+ role: match msg.role {
+ Role::User => "user",
+ Role::Assistant => "assistant",
+ },
+ content: vec![CodexInputContent {
+ kind: "input_text",
+ text: &msg.content,
+ }],
+ })
+ .collect();
+ CodexResponsesRequest {
+ model,
+ instructions: request.system.as_deref(),
+ input,
+ max_output_tokens: Some(request.max_tokens),
+ temperature: if model_uses_default_temperature(model) {
+ None
+ } else {
+ request.temperature
+ },
+ store: false,
+ stream: false,
+ text,
+ }
+}
+
+fn model_uses_default_temperature(model: &str) -> bool {
+ let m = model.to_ascii_lowercase();
+ m.starts_with("gpt-5") || m.starts_with('o')
+}
+
+#[derive(Debug, Serialize)]
+struct CodexResponsesRequest<'a> {
+ model: &'a str,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ instructions: Option<&'a str>,
+ input: Vec<CodexInputMessage<'a>>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ max_output_tokens: Option<u32>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ temperature: Option<f32>,
+ store: bool,
+ stream: bool,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ text: Option<CodexText>,
+}
+
+#[derive(Debug, Serialize)]
+struct CodexInputMessage<'a> {
+ role: &'a str,
+ content: Vec<CodexInputContent<'a>>,
+}
+
+#[derive(Debug, Serialize)]
+struct CodexInputContent<'a> {
+ #[serde(rename = "type")]
+ kind: &'a str,
+ text: &'a str,
+}
+
+#[derive(Debug, Serialize)]
+struct CodexText {
+ format: CodexTextFormat,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+enum CodexTextFormat {
+ JsonSchema {
+ name: String,
+ schema: serde_json::Value,
+ strict: bool,
+ },
+}
+
+#[derive(Debug, Deserialize)]
+struct CodexResponsesResponse {
+ #[serde(default)]
+ output_text: Option<String>,
+ #[serde(default)]
+ output: Vec<CodexOutputItem>,
+ #[serde(default)]
+ usage: Option<CodexUsage>,
+ #[serde(default)]
+ model: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct CodexOutputItem {
+ #[serde(default)]
+ content: Vec<CodexOutputContent>,
+}
+
+#[derive(Debug, Deserialize)]
+struct CodexOutputContent {
+ #[serde(default)]
+ text: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct CodexUsage {
+ #[serde(default)]
+ input_tokens: u32,
+ #[serde(default)]
+ output_tokens: u32,
+}
+
+fn into_chat_response(response: CodexResponsesResponse) -> ChatResponse {
+ let model = response
+ .model
+ .clone()
+ .unwrap_or_else(|| "openai-oauth".into());
+ ChatResponse {
+ text: extract_output_text(&response).unwrap_or_default(),
+ usage: response.usage.map(|u| Usage {
+ input_tokens: u.input_tokens,
+ output_tokens: u.output_tokens,
+ }),
+ model,
+ }
+}
+
+fn extract_output_text(response: &CodexResponsesResponse) -> Option<String> {
+ if let Some(text) = response
+ .output_text
+ .as_deref()
+ .filter(|text| !text.is_empty())
+ {
+ return Some(text.to_string());
+ }
+ response
+ .output
+ .iter()
+ .flat_map(|item| item.content.iter())
+ .filter_map(|content| content.text.as_deref())
+ .find(|text| !text.is_empty())
+ .map(ToOwned::to_owned)
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct OAuthEntry {
+ #[serde(rename = "type")]
+ kind: String,
+ access: String,
+ refresh: String,
+ expires: u64,
+ #[serde(rename = "accountId", skip_serializing_if = "Option::is_none")]
+ account_id: Option<String>,
+}
+
+fn extract_account_id_from_jwt(token: &str) -> Option<String> {
+ let payload = token.split('.').nth(1)?;
+ let bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD
+ .decode(payload)
+ .ok()?;
+ let value = serde_json::from_slice::<serde_json::Value>(&bytes).ok()?;
+ value
+ .get("chatgpt_account_id")
+ .and_then(|v| v.as_str())
+ .or_else(|| {
+ value
+ .get("https://api.openai.com/auth")
+ .and_then(|v| v.get("chatgpt_account_id"))
+ .and_then(|v| v.as_str())
+ })
+ .or_else(|| {
+ value
+ .get("organizations")
+ .and_then(|v| v.as_array())
+ .and_then(|v| v.first())
+ .and_then(|v| v.get("id"))
+ .and_then(|v| v.as_str())
+ })
+ .map(ToOwned::to_owned)
+}
+
+#[cfg(test)]
+mod tests {
+ use secrecy::ExposeSecret as _;
+ use serde_json::json;
+
+ use super::*;
+
+ #[test]
+ fn token_file_preserves_unknown_entries() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("oauth_token.json");
+ std::fs::write(
+ &path,
+ serde_json::to_vec_pretty(&json!({
+ "other": { "type": "oauth", "access": "x" }
+ }))
+ .unwrap(),
+ )
+ .unwrap();
+ let token = OpenAiOAuthToken {
+ access: SecretString::from("access"),
+ refresh: SecretString::from("refresh"),
+ expires_at_ms: 1234,
+ account_id: Some("acct".into()),
+ };
+ token.save(&path).unwrap();
+ let value =
+ serde_json::from_slice::<serde_json::Value>(&std::fs::read(&path).unwrap()).unwrap();
+ assert!(value.get("other").is_some());
+ assert_eq!(value["openai"]["access"], "access");
+ assert_eq!(value["openai"]["accountId"], "acct");
+ }
+
+ #[test]
+ fn token_file_round_trips_openai_entry() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("oauth_token.json");
+ let token = OpenAiOAuthToken {
+ access: SecretString::from("access"),
+ refresh: SecretString::from("refresh"),
+ expires_at_ms: 1234,
+ account_id: None,
+ };
+ token.save(&path).unwrap();
+ let loaded = OpenAiOAuthToken::load(&path).unwrap().unwrap();
+ assert_eq!(loaded.access.expose_secret(), "access");
+ assert_eq!(loaded.refresh.expose_secret(), "refresh");
+ assert_eq!(loaded.expires_at_ms, 1234);
+ }
+
+ #[test]
+ fn token_file_ignores_non_oauth_openai_entry() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("oauth_token.json");
+ std::fs::write(
+ &path,
+ serde_json::to_vec_pretty(&json!({
+ "openai": { "type": "api", "key": "sk-test" }
+ }))
+ .unwrap(),
+ )
+ .unwrap();
+
+ assert!(OpenAiOAuthToken::load(&path).unwrap().is_none());
+ }
+
+ #[test]
+ fn remove_deletes_only_openai_entry() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("oauth_token.json");
+ std::fs::write(
+ &path,
+ serde_json::to_vec_pretty(&json!({
+ "openai": { "type": "oauth", "access": "a", "refresh": "r", "expires": 1 },
+ "other": { "type": "oauth", "access": "x" }
+ }))
+ .unwrap(),
+ )
+ .unwrap();
+ OpenAiOAuthToken::remove(&path).unwrap();
+ let value =
+ serde_json::from_slice::<serde_json::Value>(&std::fs::read(&path).unwrap()).unwrap();
+ assert!(value.get("openai").is_none());
+ assert!(value.get("other").is_some());
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn token_file_is_mode_0600() {
+ use std::os::unix::fs::PermissionsExt as _;
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("oauth_token.json");
+ let token = OpenAiOAuthToken {
+ access: SecretString::from("access"),
+ refresh: SecretString::from("refresh"),
+ expires_at_ms: 1234,
+ account_id: None,
+ };
+ token.save(&path).unwrap();
+ let mode = std::fs::metadata(&path).unwrap().permissions().mode();
+ assert_eq!(mode & 0o777, 0o600);
+ }
+
+ #[test]
+ fn jwt_account_id_extraction_uses_supported_fallbacks() {
+ fn jwt(payload: serde_json::Value) -> String {
+ let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
+ .encode(serde_json::to_vec(&payload).unwrap());
+ format!("x.{payload}.y")
+ }
+ assert_eq!(
+ extract_account_id_from_jwt(&jwt(json!({ "chatgpt_account_id": "top" }))),
+ Some("top".into())
+ );
+ assert_eq!(
+ extract_account_id_from_jwt(&jwt(json!({
+ "https://api.openai.com/auth": { "chatgpt_account_id": "nested" }
+ }))),
+ Some("nested".into())
+ );
+ assert_eq!(
+ extract_account_id_from_jwt(&jwt(json!({ "organizations": [{ "id": "org" }] }))),
+ Some("org".into())
+ );
+ }
+
+ #[test]
+ fn codex_request_moves_system_to_instructions_and_omits_gpt5_temperature() {
+ let request = ChatRequest {
+ system: Some("sys".into()),
+ messages: vec![crate::types::ChatMessage {
+ role: Role::User,
+ content: "hello".into(),
+ }],
+ temperature: Some(0.2),
+ max_tokens: 123,
+ };
+ let value = serde_json::to_value(build_request("gpt-5.5", &request, None)).unwrap();
+ assert_eq!(value["instructions"], "sys");
+ assert_eq!(value["input"][0]["content"][0]["type"], "input_text");
+ assert!(value.get("temperature").is_none());
+ assert_eq!(value["store"], false);
+ assert_eq!(value["stream"], false);
+ }
+
+ #[test]
+ fn structured_request_uses_responses_json_schema_format() {
+ let request = ChatRequest::user_prompt("json please");
+ let text = CodexText {
+ format: CodexTextFormat::JsonSchema {
+ name: "Result".into(),
+ schema: json!({ "type": "object", "properties": {} }),
+ strict: true,
+ },
+ };
+ let value = serde_json::to_value(build_request("gpt-5.5", &request, Some(text))).unwrap();
+ assert_eq!(value["text"]["format"]["type"], "json_schema");
+ assert_eq!(value["text"]["format"]["name"], "Result");
+ assert_eq!(value["text"]["format"]["strict"], true);
+ }
+
+ #[test]
+ fn response_text_prefers_output_text_then_output_items() {
+ let direct: CodexResponsesResponse = serde_json::from_value(json!({
+ "output_text": "direct",
+ "output": [{ "content": [{ "text": "nested" }] }]
+ }))
+ .unwrap();
+ assert_eq!(extract_output_text(&direct).as_deref(), Some("direct"));
+
+ let nested: CodexResponsesResponse = serde_json::from_value(json!({
+ "output": [{ "content": [{ "text": "nested" }] }]
+ }))
+ .unwrap();
+ assert_eq!(extract_output_text(&nested).as_deref(), Some("nested"));
+ }
+}
diff --git a/docker/.env.production.example b/docker/.env.production.example
index deb9b405..0d368cdd 100644
--- a/docker/.env.production.example
+++ b/docker/.env.production.example
@@ -15,9 +15,15 @@
# AI_MEMORY_PROJECT=homelab
# -- LLM provider ------------------------------------------------------
-# Pick one of: anthropic | openai | openai-compat
+# Pick one of: anthropic | openai | openai-oauth | copilot | gemini | openai-compat
# anthropic -> Anthropic Messages API (needs ANTHROPIC_API_KEY)
# openai -> OpenAI Chat Completions (needs OPENAI_API_KEY)
+# openai-oauth -> ChatGPT/Codex OAuth. Run `ai-memory auth login
+# openai-oauth` against this same data volume first.
+# copilot -> GitHub Copilot Chat. Run `ai-memory auth login
+# copilot` against this same data volume first, or set
+# COPILOT_GITHUB_TOKEN below.
+# gemini -> Google Gemini (needs GEMINI_API_KEY or GOOGLE_API_KEY)
# openai-compat -> Any OpenAI-compatible endpoint: Ollama, vLLM,
# LM Studio, OpenRouter, Together, etc. Set
# AI_MEMORY_LLM_BASE_URL + LLM_API_KEY.
@@ -32,6 +38,7 @@ AI_MEMORY_LLM_MODEL=moonshotai/kimi-k2.6
# AI_MEMORY_LLM_PROVIDER above.
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
+# COPILOT_GITHUB_TOKEN=ghu_or_github_pat_REPLACE_ME
LLM_API_KEY=sk-or-v1-REPLACE_ME
# -- Embeddings (hybrid retrieval) -------------------------------------
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 06b7a4e2..1a60e9fc 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -187,7 +187,7 @@ crates/
├── ai-memory-wiki/ atomic markdown writes, file watcher, git.
├── ai-memory-mcp/ rmcp transport + tool router.
├── ai-memory-hooks/ payload schemas, sanitiser, /hook ingress.
-├── ai-memory-llm/ LlmProvider + Embedder traits + 3 providers + 2 embedders.
+├── ai-memory-llm/ provider auth boundary + LlmProvider / Embedder traits.
├── ai-memory-consolidate/ Karpathy ingest / lint / sweep pipeline.
└── ai-memory-cli/ `ai-memory` binary entry point + 17 subcommands.
```
@@ -238,7 +238,7 @@ install-mcp commit llm-test
forget-sweep lint embed
generate-auth-token setup-agent bootstrap
install-instructions reorg purge-project
-rename-project uninstall
+rename-project uninstall auth
```
Run `ai-memory --help` for the full tree.
@@ -278,7 +278,12 @@ that touch the relevant area.
explicit. (cognee #2228.)
13. **Zero-LLM default path.** LLM has opt-in via env. The
system works without any provider configured.
-14. **Tracing subscribers explicitly filter their own module.**
+14. **Provider auth resolves before provider construction.** Native
+ provider clients consume typed `ProviderAuth` material; they never
+ read env vars directly. Token-backed providers receive explicit
+ auth-file paths / env-derived token material through that boundary,
+ then own provider-specific refresh and persistence.
+15. **Tracing subscribers explicitly filter their own module.**
No feedback loops. (agentmemory #519.)
## Configuration (`config.toml`)
@@ -300,12 +305,24 @@ hard_delete_after_days = 180
**LLM provider env** (opt-in):
```
-AI_MEMORY_LLM_PROVIDER anthropic | openai | gemini | openai-compat
-AI_MEMORY_LLM_MODEL e.g. claude-sonnet-4-6, gemini-2.5-flash
+AI_MEMORY_LLM_PROVIDER anthropic | openai | openai-oauth | copilot | gemini | openai-compat
+AI_MEMORY_LLM_MODEL e.g. claude-sonnet-4-6, gpt-5.5, gemini-2.5-flash
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / LLM_API_KEY
AI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)
+COPILOT_GITHUB_TOKEN optional GitHub token for copilot
+GITHUB_COPILOT_API_TOKEN optional pre-minted Copilot API token
+COPILOT_API_URL optional Copilot API base URL override
```
+`openai-oauth` uses `auth login openai-oauth` and stores the ChatGPT/Codex
+refresh token in `<data_dir>/auth.json`; it is separate from MCP/server bearer
+auth and from OpenAI Platform API keys.
+
+`copilot` uses `auth login copilot` or `COPILOT_GITHUB_TOKEN`, exchanges the
+GitHub token through `/copilot_internal/v2/token`, and calls Copilot Chat with
+the `vscode-chat` integration headers. The raw GitHub token is not sent to the
+Copilot chat endpoint.
+
**Embedder env** (opt-in):
```
AI_MEMORY_EMBEDDING_PROVIDER openai | voyage | google | gemini
diff --git a/docs/deploy.md b/docs/deploy.md
index 87c1390b..5b75dabb 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -142,6 +142,8 @@ alternatives:
| anthropic | `claude-haiku-4-5` | ~$0.02 | **Recommended default.** Best balance of speed, restraint, and classification quality. Not a reasoning model. |
| openai-compat (OpenRouter) | `moonshotai/kimi-k2.6` | ~$0.013 | Reasoning model; latency ~2-3 min per consolidation. Fine because consolidation is fire-and-forget. |
| openai | `gpt-5.4-mini` | ~$0.002 | Cheaper, faster alternative. Decent quality. |
+| openai-oauth | `gpt-5.5` | ChatGPT subscription | ChatGPT/Codex backend. Run `docker exec -it ai-memory ai-memory auth login openai-oauth` on the server host so `<data_dir>/auth.json` lands in the mounted data volume. |
+| copilot | `gpt-5.5` | GitHub Copilot subscription | GitHub Copilot Chat backend. Run `docker exec -it ai-memory ai-memory auth login copilot` on the server host or set `COPILOT_GITHUB_TOKEN`. |
| gemini | `gemini-2.5-flash` | free tier covers personal use | Google hosted, native `responseSchema` structured output. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |
| openai-compat (Ollama) | `qwen3:32b` | $0 | Self-hosted. Set `AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1`. Quality depends on the model. |
diff --git a/docs/install.md b/docs/install.md
index 12cc53be..386f00f0 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -349,6 +349,8 @@ ai-memory works in three intensity tiers:
|---|---|---|---|
| **Zero-LLM** (default) | FTS5 search, rule-based session summaries, auto-handoffs from prompt + tool-call history | (none) | $0 |
| **+ LLM consolidation** | LLM rewrites session pages as coherent narratives; PreCompact checkpoints; LLM-driven contradiction lint | `AI_MEMORY_LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY` | ~$0.01–0.05 / session |
+| **+ ChatGPT/Codex OAuth** | Same LLM features using a ChatGPT Pro/Plus login instead of an OpenAI Platform key | `AI_MEMORY_LLM_PROVIDER=openai-oauth` + `ai-memory auth login openai-oauth` | Uses your ChatGPT subscription |
+| **+ GitHub Copilot** | Same LLM features using a GitHub Copilot subscription | `AI_MEMORY_LLM_PROVIDER=copilot` + `ai-memory auth login copilot` or `COPILOT_GITHUB_TOKEN` | Uses your Copilot subscription |
| **+ Hybrid retrieval** | RRF over FTS5 + vector cosine similarity. Better recall on paraphrased queries | `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `OPENAI_API_KEY` | ~$0.0001 / page on backfill |
### Recommended models (chosen as defaults)
@@ -359,6 +361,8 @@ If you set only the provider, ai-memory picks a sensible default:
|---|---|---|
| `AI_MEMORY_LLM_PROVIDER=anthropic` | `claude-haiku-4-5` | **Recommended default.** Best balance of speed, restraint, and classification quality. Not a reasoning model. Consistently classifies durable project rules as `kind: rule`. |
| `AI_MEMORY_LLM_PROVIDER=openai` | `gpt-5.4-mini` | Cheaper + faster alternative. Same parse reliability; mild over-classification on thin sessions. |
+| `AI_MEMORY_LLM_PROVIDER=openai-oauth` | `gpt-5.5` | ChatGPT/Codex backend. Run `ai-memory auth login openai-oauth` once; ai-memory stores the refresh token in `<data_dir>/auth.json` and refreshes access tokens automatically. |
+| `AI_MEMORY_LLM_PROVIDER=copilot` | `gpt-5.5` | GitHub Copilot Chat backend. ai-memory stores a GitHub user token in `<data_dir>/auth.json`, exchanges it for a short-lived Copilot API token, and refreshes before expiry. |
| `AI_MEMORY_LLM_PROVIDER=gemini` | `gemini-2.5-flash` | Google's hosted option with a generous free tier. ai-memory disables Gemini 2.5 Flash's default dynamic thinking so hidden thought tokens do not truncate strict JSON. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` | `text-embedding-3-small` (1536-dim) | 5× cheaper than `-3-large` with marginal recall loss. |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1` | `openai/text-embedding-3-small` via [OpenRouter](https://openrouter.ai) | Reuses `LLM_API_KEY` or `OPENAI_API_KEY` with the OpenAI-compatible embedding client. |
@@ -370,6 +374,67 @@ If you set only the provider, ai-memory picks a sensible default:
> internal reasoning and hang or emit empty responses with the strict-JSON
> consolidation prompt. Turn reasoning off if you must use one.
+### OpenAI OAuth / Codex
+
+`openai-oauth` is for ChatGPT Pro/Plus/Codex accounts. It does **not** use
+`OPENAI_API_KEY` and it does **not** call `api.openai.com`; requests go to the
+ChatGPT/Codex Responses backend with a refreshable OAuth token.
+
+For the Docker quick start wrapper, this writes into the same named volume the
+server mounts at `/data`:
+
+```bash
+ai-memory auth login openai-oauth
+docker run -d --name ai-memory \
+ -p 127.0.0.1:49374:49374 \
+ -v ai-memory-data:/data \
+ -e AI_MEMORY_LLM_PROVIDER=openai-oauth \
+ akitaonrails/ai-memory:latest
+```
+
+For a remote Docker host, run the login on that host against the same container
+or data volume:
+
+```bash
+docker exec -it ai-memory ai-memory auth login openai-oauth
+```
+
+Use `ai-memory auth status` to check whether a token is present and
+`ai-memory auth logout openai-oauth` to remove it.
+
+### GitHub Copilot
+
+`copilot` uses a GitHub user token, then exchanges it for a short-lived Copilot
+API token through `https://api.github.com/copilot_internal/v2/token`. The raw
+GitHub token is never sent to `api.githubcopilot.com`.
+
+For the Docker quick start wrapper:
+
+```bash
+ai-memory auth login copilot
+docker run -d --name ai-memory \
+ -p 127.0.0.1:49374:49374 \
+ -v ai-memory-data:/data \
+ -e AI_MEMORY_LLM_PROVIDER=copilot \
+ akitaonrails/ai-memory:latest
+```
+
+For a remote Docker host, run the login against the same data volume:
+
+```bash
+docker exec -it ai-memory ai-memory auth login copilot
+```
+
+Non-interactive deploys can set `COPILOT_GITHUB_TOKEN` instead. ai-memory also
+accepts `GH_TOKEN` and `GITHUB_TOKEN` when running natively; prefer the explicit
+`COPILOT_GITHUB_TOKEN` in Docker so you do not pass a broad token by accident.
+Advanced users with a pre-minted Copilot API token can set
+`GITHUB_COPILOT_API_TOKEN` and optionally `COPILOT_API_URL`.
+
+`auth login copilot` defaults to GitHub Copilot's public device-flow client id.
+Pass `--client-id` or set `AI_MEMORY_COPILOT_CLIENT_ID` if you operate your own
+OAuth app.
+
### Self-hosted LLMs (Ollama / vLLM / LM Studio / OpenRouter)
```bash
@@ -406,8 +471,10 @@ docker exec ai-memory ai-memory status --json
docker exec ai-memory ai-memory search "karpathy"
docker exec ai-memory ai-memory backup --to /data/snapshot.tar.gz
-# B) One-shot, no running container needed (pure-stdout: generate-
-# auth-token, install-mcp, install-hooks, setup-agent, llm-test).
+# B) One-shot, no running container needed for pure-stdout helpers
+# (generate-auth-token, install-mcp, install-hooks, setup-agent, llm-test).
+# Auth login is stateful: use docker exec against the running container or
+# the wrapper so it writes into the same data volume as the server.
docker run --rm akitaonrails/ai-memory:latest generate-auth-token
docker run --rm akitaonrails/ai-memory:latest install-mcp --client cursor
docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
@@ -424,6 +491,8 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
| `commit -m "…"` | `docker exec` | Stage + commit the wiki tree |
| `reset --confirm` | `docker exec` | Wipe data (refuses while siblings alive) |
| `generate-auth-token` | `docker run --rm` | Print a random hex bearer token |
+| `auth login openai-oauth` | same data volume as the server | Store a ChatGPT/Codex OAuth refresh token for the optional `openai-oauth` LLM provider |
+| `auth login copilot` | same data volume as the server | Store a GitHub token for the optional `copilot` LLM provider |
| `install-mcp --client` | `docker run --rm` | MCP-config snippet per client |
| `install-hooks --agent` | `docker run --rm` | Hook-config snippet for an existing hooks dir |
| `setup-agent --agent --to --host-prefix` | `docker run --rm -v` | Extract bundled scripts + print config (one-shot) |
diff --git a/docs/usage.md b/docs/usage.md
index 3b100a58..9b93283e 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -97,6 +97,29 @@ sources to the running server. It requires an LLM provider on the
server. See [Installation cookbook - bootstrap mid-project](install.md#bootstrap-mid-project)
for flags, token budgets, and source priority.
+If you use the ChatGPT/Codex OAuth provider, sign in once before starting the
+server with `AI_MEMORY_LLM_PROVIDER=openai-oauth`:
+
+```bash
+ai-memory auth login openai-oauth
+ai-memory auth status
+```
+
+The login command stores only provider credentials in `<data_dir>/auth.json`.
+It is separate from `AI_MEMORY_AUTH_TOKEN`, which protects MCP, hooks, and the
+web UI.
+
+For GitHub Copilot, use the matching provider login before starting the server
+with `AI_MEMORY_LLM_PROVIDER=copilot`:
+
+```bash
+ai-memory auth login copilot
+ai-memory auth status
+```
+
+Copilot auth stores a GitHub user token, then the provider exchanges it for a
+short-lived Copilot API token before each LLM call.
+
## Browse the wiki in a browser
Start the server with `--enable-web` and open
diff --git a/evals/README.md b/evals/README.md
index 643bf3cb..17400039 100644
--- a/evals/README.md
+++ b/evals/README.md
@@ -78,6 +78,38 @@ cargo run -p ai-memory-eval -- \
--candidate-api-key ollama-local
```
+### ChatGPT/Codex OAuth as one side
+
+Run `ai-memory auth login openai-oauth` first, then point the eval harness at
+the same token file:
+
+```bash
+cargo run -p ai-memory-eval -- \
+ --baseline-provider openai-oauth \
+ --baseline-token-file ~/.local/share/ai-memory/auth.json \
+ --baseline-model gpt-5.5 \
+ --candidate-provider openai-compat \
+ --candidate-base-url http://192.168.0.90:11434/v1 \
+ --candidate-model qwen3:32b \
+ --candidate-api-key ollama-local
+```
+
+### GitHub Copilot as one side
+
+Run `ai-memory auth login copilot` first, then point the eval harness at the
+same auth file:
+
+```bash
+cargo run -p ai-memory-eval -- \
+ --baseline-provider copilot \
+ --baseline-token-file ~/.local/share/ai-memory/auth.json \
+ --baseline-model gpt-5.5 \
+ --candidate-provider openai-compat \
+ --candidate-base-url http://192.168.0.90:11434/v1 \
+ --candidate-model qwen3:32b \
+ --candidate-api-key ollama-local
+```
+
### Reading the output
```
diff --git a/evals/src/main.rs b/evals/src/main.rs
index a6e514ba..0ee1159a 100644
--- a/evals/src/main.rs
+++ b/evals/src/main.rs
@@ -52,7 +52,7 @@ use serde::{Deserialize, Serialize};
use ai_memory_consolidate::{ConsolidatedBatch, build_batch_request};
use ai_memory_core::{Observation, ObservationKind, ProjectId, SessionId, WorkspaceId};
-use ai_memory_llm::{LlmProvider, ProviderChoice, ProviderConfig};
+use ai_memory_llm::{AuthRequirement, LlmProvider, ProviderAuth, ProviderChoice, ProviderConfig};
#[derive(Parser, Debug)]
#[command(
@@ -68,7 +68,7 @@ struct Args {
#[arg(long, default_value = "evals/runs")]
out: PathBuf,
- /// Baseline provider (`anthropic` / `openai` / `openai-compat`).
+ /// Baseline provider (`anthropic` / `openai` / `openai-compat` / `openai-oauth` / `copilot`).
#[arg(long)]
baseline_provider: String,
@@ -88,6 +88,10 @@ struct Args {
#[arg(long)]
baseline_api_key_env: Option<String>,
+ /// Baseline OpenAI OAuth token file for `--baseline-provider openai-oauth`.
+ #[arg(long)]
+ baseline_token_file: Option<PathBuf>,
+
/// Candidate provider.
#[arg(long)]
candidate_provider: String,
@@ -107,6 +111,10 @@ struct Args {
/// Env var to read the candidate API key from.
#[arg(long)]
candidate_api_key_env: Option<String>,
+
+ /// Candidate OpenAI OAuth token file for `--candidate-provider openai-oauth`.
+ #[arg(long)]
+ candidate_token_file: Option<PathBuf>,
}
/// JSON shape of an eval fixture file. We only care about
@@ -264,13 +272,14 @@ async fn main() -> Result<()> {
/// Resolve `ProviderConfig` for one side from CLI args + env.
fn resolve_provider(side: &str, args: &Args) -> Result<ResolvedConfig> {
- let (provider_str, base_url, model, api_key_inline, api_key_env) = match side {
+ let (provider_str, base_url, model, api_key_inline, api_key_env, token_file) = match side {
"baseline" => (
args.baseline_provider.as_str(),
args.baseline_base_url.clone(),
args.baseline_model.clone(),
args.baseline_api_key.clone(),
args.baseline_api_key_env.clone(),
+ args.baseline_token_file.clone(),
),
"candidate" => (
args.candidate_provider.as_str(),
@@ -278,6 +287,7 @@ fn resolve_provider(side: &str, args: &Args) -> Result<ResolvedConfig> {
args.candidate_model.clone(),
args.candidate_api_key.clone(),
args.candidate_api_key_env.clone(),
+ args.candidate_token_file.clone(),
),
_ => bail!("unknown side {side}"),
};
@@ -286,7 +296,13 @@ fn resolve_provider(side: &str, args: &Args) -> Result<ResolvedConfig> {
"anthropic" => ProviderChoice::Anthropic,
"openai" => ProviderChoice::OpenAi,
"openai-compat" | "openai_compat" => ProviderChoice::OpenAiCompat,
- other => bail!("{side}: provider {other} not one of anthropic|openai|openai-compat"),
+ "openai-oauth" | "openai_oauth" => ProviderChoice::OpenAiOAuth,
+ "copilot" | "github-copilot" | "github_copilot" => ProviderChoice::Copilot,
+ other => {
+ bail!(
+ "{side}: provider {other} not one of anthropic|openai|openai-compat|openai-oauth|copilot"
+ )
+ }
};
let api_key = match (api_key_inline, api_key_env) {
@@ -298,21 +314,44 @@ fn resolve_provider(side: &str, args: &Args) -> Result<ResolvedConfig> {
_ => None,
};
+ let auth = match provider.auth_requirement() {
+ AuthRequirement::RequiredApiKey { env_var } => {
+ ProviderAuth::required_api_key_from_env(env_var, api_key)
+ }
+ AuthRequirement::OptionalApiKey { env_var } => {
+ ProviderAuth::optional_api_key_from_env(env_var, api_key)
+ }
+ AuthRequirement::OpenAiOAuthToken => {
+ ProviderAuth::openai_oauth_token_file(token_file.ok_or_else(|| {
+ anyhow::anyhow!("{side}: --{side}-token-file is required for openai-oauth")
+ })?)
+ }
+ AuthRequirement::CopilotToken => ProviderAuth::copilot(
+ token_file.ok_or_else(|| {
+ anyhow::anyhow!("{side}: --{side}-token-file is required for copilot")
+ })?,
+ None,
+ None,
+ base_url.clone(),
+ ),
+ };
+
Ok(ResolvedConfig {
provider,
provider_str: provider_str.to_string(),
model,
base_url,
- api_key,
+ auth,
})
}
+#[derive(Clone)]
struct ResolvedConfig {
provider: ProviderChoice,
provider_str: String,
model: String,
base_url: Option<String>,
- api_key: Option<SecretString>,
+ auth: ProviderAuth,
}
impl ResolvedConfig {
@@ -321,28 +360,12 @@ impl ResolvedConfig {
}
}
-impl Clone for ResolvedConfig {
- fn clone(&self) -> Self {
- Self {
- provider: self.provider,
- provider_str: self.provider_str.clone(),
- model: self.model.clone(),
- base_url: self.base_url.clone(),
- // SecretString is not Clone — re-wrap if needed.
- api_key: self.api_key.as_ref().map(|s| {
- use secrecy::ExposeSecret;
- SecretString::from(s.expose_secret().to_string())
- }),
- }
- }
-}
-
impl From<ResolvedConfig> for ProviderConfig {
fn from(r: ResolvedConfig) -> Self {
Self {
provider: r.provider,
model: r.model,
- api_key: r.api_key,
+ auth: r.auth,
base_url: r.base_url,
}
}