Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
//! Lossless native TOML edits. Callers own protected file IO and Journal persistence.
//! This module never opens a file, executes a helper, or accepts upstream credential material.
use hiroute_domain::{
AgentAccessGrantMaterial, CanonicalDigest, ModelAlias, valid_client_model_name,
};
use toml_edit::{DocumentMut, Item, Table};
use zeroize::Zeroizing;
#[path = "codex_restore_record.rs"]
mod restore_record;
const MAX_BYTES: usize = 1024 * 1024;
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum CodexSelectionTarget {
/// User config or a separately selected native profile file, as proven by discovery.
Root,
LegacyProfile(String),
}
/// Contains local credential material. No Debug/serde implementation or public diagnostics.
pub struct CodexNativeEdit {
pub rendered: Zeroizing<String>,
pub restore: CodexNativeRestore,
}
impl CodexNativeEdit {
pub fn with_managed_aliases(mut self, aliases: &[String]) -> Result<Self, CodexNativeError> {
if aliases.len() > 128
|| aliases
.iter()
.any(|alias| ModelAlias::parse(alias.clone()).is_err())
|| aliases
.iter()
.collect::<std::collections::BTreeSet<_>>()
.len()
!= aliases.len()
{
return Err(CodexNativeError::InvalidIntent);
}
self.restore.managed_aliases = aliases.to_vec();
Ok(self)
}
pub fn with_model_catalog(mut self, path: &std::path::Path) -> Result<Self, CodexNativeError> {
let path_text = path.to_str().ok_or(CodexNativeError::InvalidIntent)?;
if !path.is_absolute()
|| path
.components()
.any(|component| matches!(component, std::path::Component::ParentDir))
|| path_text.contains(['\0', '\r', '\n'])
|| self.restore.fields.iter().any(|field| {
field
.path
.last()
.is_some_and(|key| key == "model_catalog_json")
})
{
return Err(CodexNativeError::InvalidIntent);
}
let selection = self
.restore
.fields
.iter()
.find(|field| field.path.last().is_some_and(|key| key == "model_provider"))
.ok_or(CodexNativeError::UnsupportedLayout)?;
let parent = selection.path[..selection.path.len() - 1].to_vec();
let mut document = parse(&self.rendered)?;
set(
&mut document,
&parent,
"model_catalog_json",
toml_edit::value(path_text),
&mut self.restore,
)?;
self.rendered = render_bounded(&document)?;
Ok(self)
}
}
/// The Operation must store this in its protected restoration store, never the public Journal.
pub struct CodexNativeRestore {
fields: Vec<FieldRestore>,
created_tables: Vec<Vec<String>>,
managed_aliases: Vec<String>,
}
struct FieldRestore {
path: Vec<String>,
before: Option<Item>,
after: CanonicalDigest,
// PreserveNative observes the user's default without writing it. Only a later
// alias in the sealed grant is reverted; another native user choice survives.
passive_model: bool,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum CodexNativeError {
#[error("native TOML is invalid or exceeds the input limit")]
InvalidToml,
#[error("configuration changed after preview")]
SourceChanged,
#[error("the selected native configuration shape is not proven")]
UnsupportedLayout,
#[error("a user provider already occupies the proposed managed identity")]
ProviderAlreadyExists,
#[error("a managed field changed after application")]
FieldConflict,
#[error("the managed model or local endpoint is invalid")]
InvalidIntent,
}
pub fn configure_codex_native(
current: &str,
expected: &CanonicalDigest,
target: CodexSelectionTarget,
provider_id: &str,
endpoint: &str,
model: Option<&str>,
local_grant: &AgentAccessGrantMaterial,
) -> Result<CodexNativeEdit, CodexNativeError> {
if &CanonicalDigest::of_bytes(current.as_bytes()) != expected {
return Err(CodexNativeError::SourceChanged);
}
configure_codex_base(
current,
target,
provider_id,
endpoint,
model,
local_grant,
false,
)
}
/// Replace fields from a configuration whose protected restore record proves this provider is
/// already HiRoute-owned. The new restore record is rebased onto the original user fields, so a
/// later formal restore never leaves an older local bearer or managed model behind.
#[allow(clippy::too_many_arguments)]
pub(super) fn reconfigure_codex_native(
current: &str,
expected: &CanonicalDigest,
previous: &CodexNativeRestore,
target: CodexSelectionTarget,
provider_id: &str,
endpoint: &str,
model: Option<&str>,
local_grant: &AgentAccessGrantMaterial,
) -> Result<CodexNativeEdit, CodexNativeError> {
if &CanonicalDigest::of_bytes(current.as_bytes()) != expected {
return Err(CodexNativeError::SourceChanged);
}
if !managed_provider_shape(&parse(current)?) {
return Err(CodexNativeError::FieldConflict);
}
let base = restore_codex_native(current, previous)?;
configure_codex_base(
&base,
target,
provider_id,
endpoint,
model,
local_grant,
previous.owns_provider(provider_id),
)
}
#[allow(clippy::too_many_arguments)]
fn configure_codex_base(
current: &str,
target: CodexSelectionTarget,
provider_id: &str,
endpoint: &str,
model: Option<&str>,
local_grant: &AgentAccessGrantMaterial,
owned_provider: bool,
) -> Result<CodexNativeEdit, CodexNativeError> {
if provider_id != "hiroute"
|| !local_endpoint(endpoint)
|| model.is_some_and(|name| !valid_client_model_name(name))
{
return Err(CodexNativeError::InvalidIntent);
}
let mut document = parse(current)?;
let selection = match target {
CodexSelectionTarget::Root => Vec::new(),
CodexSelectionTarget::LegacyProfile(name) if identifier(&name) => {
let path = vec!["profiles".to_owned(), name];
table_at(&document, &path)?;
path
}
_ => return Err(CodexNativeError::UnsupportedLayout),
};
if let Some(providers) = document.get("model_providers") {
let providers = providers
.as_table()
.ok_or(CodexNativeError::UnsupportedLayout)?;
if providers.contains_key(provider_id) && !owned_provider {
return Err(CodexNativeError::ProviderAlreadyExists);
}
}
let mut restore = CodexNativeRestore {
fields: Vec::new(),
created_tables: Vec::new(),
managed_aliases: Vec::new(),
};
if let Some(model) = model {
set(
&mut document,
&selection,
"model",
toml_edit::value(model),
&mut restore,
)?;
} else {
let mut path = selection.clone();
path.push("model".to_owned());
let before = table_at(&document, &selection)?.get("model").cloned();
if before.as_ref().is_some_and(|item| item.as_str().is_none()) {
return Err(CodexNativeError::UnsupportedLayout);
}
restore.fields.push(FieldRestore {
path,
after: before
.as_ref()
.map(fingerprint)
.unwrap_or_else(|| CanonicalDigest::of_bytes(b"codex.absent-model")),
before,
passive_model: true,
});
}
set(
&mut document,
&selection,
"model_provider",
toml_edit::value(provider_id),
&mut restore,
)?;
let provider = vec!["model_providers".to_owned(), provider_id.to_owned()];
create_tables(&mut document, &provider, &mut restore.created_tables)?;
let token =
std::str::from_utf8(local_grant.expose()).map_err(|_| CodexNativeError::InvalidIntent)?;
for (key, value) in [
("name", "HiRoute"),
("base_url", endpoint),
("wire_api", "responses"),
] {
set(
&mut document,
&provider,
key,
toml_edit::value(value),
&mut restore,
)?;
}
for (key, value) in [
("requires_openai_auth", false),
("supports_websockets", false),
] {
set(
&mut document,
&provider,
key,
toml_edit::value(value),
&mut restore,
)?;
}
let headers = vec![
"model_providers".to_owned(),
provider_id.to_owned(),
"http_headers".to_owned(),
];
create_tables(&mut document, &headers, &mut restore.created_tables)?;
set(
&mut document,
&headers,
"X-HiRoute-Token",
toml_edit::value(token),
&mut restore,
)?;
Ok(CodexNativeEdit {
rendered: render_bounded(&document)?,
restore,
})
}
impl CodexNativeRestore {
/// Status follows the fields HiRoute wrote. Other native settings and TOML formatting
/// may change independently after the configuration Operation succeeds.
pub fn conflicting_fields(&self, current: &str) -> Vec<String> {
let Ok(document) = parse(current) else {
return vec!["invalid TOML".into()];
};
self.fields
.iter()
.filter(|field| {
if field.passive_model {
return false;
}
let Some((key, parent)) = field.path.split_last() else {
return true;
};
let item = optional_table(&document, parent)
.ok()
.flatten()
.and_then(|t| t.get(key));
item.map(fingerprint) != field.before.as_ref().map(fingerprint)
&& item.map(fingerprint).as_ref() != Some(&field.after)
})
.map(|field| field.path.join("."))
.collect()
}
/// Pending cleanup names are safe to display; no previous values or credentials escape.
pub fn pending_restoration_fields(&self, current: &str) -> Vec<String> {
let Ok(document) = parse(current) else {
return vec!["invalid TOML".into()];
};
self.fields
.iter()
.filter(|field| {
let Some((key, parent)) = field.path.split_last() else {
return true;
};
let item = optional_table(&document, parent)
.ok()
.flatten()
.and_then(|t| t.get(key));
if field.passive_model {
return item.and_then(Item::as_str).is_some_and(|model| {
self.managed_aliases.iter().any(|alias| alias == model)
});
}
item.map(fingerprint) != field.before.as_ref().map(fingerprint)
})
.map(|field| field.path.join("."))
.collect()
}
pub fn managed_fields_are_applied(&self, current: &str) -> bool {
let Ok(document) = parse(current) else {
return false;
};
managed_provider_shape(&document)
&& self
.fields
.iter()
.filter(|field| !field.passive_model)
.all(|field| {
let Some((key, parent)) = field.path.split_last() else {
return false;
};
optional_table(&document, parent)
.ok()
.flatten()
.and_then(|table| table.get(key))
.is_some_and(|item| fingerprint(item) == field.after)
})
}
fn owns_provider(&self, provider_id: &str) -> bool {
[
"name",
"base_url",
"wire_api",
"requires_openai_auth",
"supports_websockets",
]
.into_iter()
.all(|key| {
self.fields.iter().any(|field| {
field.before.is_none()
&& field.path
== [
"model_providers".to_owned(),
provider_id.to_owned(),
key.to_owned(),
]
})
})
}
/// When this edit wrote the managed catalog pointer, the user's original pointer it
/// replaced (None inside means the user had none). Absent when the edit never touched
/// the pointer, so the scope's own configuration still carries the user's state.
pub fn catalog_pointer_before(&self) -> Option<Option<String>> {
self.fields
.iter()
.find(|field| {
field
.path
.last()
.is_some_and(|key| key == "model_catalog_json")
})
.map(|field| {
field
.before
.as_ref()
.and_then(|item| item.as_str().map(str::to_owned))
})
}
}
pub fn restore_codex_native(
current: &str,
restore: &CodexNativeRestore,
) -> Result<Zeroizing<String>, CodexNativeError> {
restore_codex_native_with_model(current, restore, None)
}
pub fn codex_explicit_model(text: &str) -> Result<Option<String>, CodexNativeError> {
Ok(parse(text)?
.get("model")
.and_then(Item::as_str)
.map(str::to_owned))
}
pub fn codex_explicit_reasoning_effort(text: &str) -> Result<Option<String>, CodexNativeError> {
parse(text)?
.get("model_reasoning_effort")
.map(|item| {
item.as_str()
.map(str::to_owned)
.ok_or(CodexNativeError::UnsupportedLayout)
})
.transpose()
}
/// Restore native ownership and, when explicitly chosen, set a model proven by the original
/// catalog in the caller's preview. The same choice is rechecked by the daemon at Apply.
pub fn restore_codex_native_with_model(
current: &str,
restore: &CodexNativeRestore,
native_model: Option<&str>,
) -> Result<Zeroizing<String>, CodexNativeError> {
if native_model.is_some_and(|model| !valid_client_model_name(model)) {
return Err(CodexNativeError::InvalidIntent);
}
let mut document = parse(current)?;
let mut pending = Vec::new();
for field in &restore.fields {
let (key, parent) = field
.path
.split_last()
.ok_or(CodexNativeError::UnsupportedLayout)?;
let item = optional_table(&document, parent)?.and_then(|table| table.get(key));
if field.passive_model {
// This field was observed, not written. Release only a route alias
// authorized by this exact settings Operation; other user edits survive.
if item
.and_then(Item::as_str)
.is_some_and(|model| restore.managed_aliases.iter().any(|alias| alias == model))
&& item.map(fingerprint) != field.before.as_ref().map(fingerprint)
{
pending.push(field);
}
continue;
}
if item.map(fingerprint) == field.before.as_ref().map(fingerprint) {
continue;
}
if item.map(fingerprint).as_ref() != Some(&field.after) {
return Err(CodexNativeError::FieldConflict);
}
pending.push(field);
}
for field in pending {
let (key, parent) = field
.path
.split_last()
.ok_or(CodexNativeError::UnsupportedLayout)?;
let table = table_at_mut(&mut document, parent)?;
match &field.before {
Some(before) => {
let mut restored = before.clone();
if let (Some(current), Some(value)) = (
table.get(key).and_then(Item::as_value),
restored.as_value_mut(),
) {
*value.decor_mut() = current.decor().clone();
}
*table.get_mut(key).ok_or(CodexNativeError::FieldConflict)? = restored;
}
None => {
table.remove(key);
}
}
}
// Newly added user keys keep their table alive. Only tables created by this edit can go.
for path in restore.created_tables.iter().rev() {
if optional_table(&document, path)?.is_some_and(Table::is_empty) {
let (key, parent) = path
.split_last()
.ok_or(CodexNativeError::UnsupportedLayout)?;
table_at_mut(&mut document, parent)?.remove(key);
}
}
if let Some(native_model) = native_model {
let field = restore
.fields
.iter()
.find(|field| field.path.last().is_some_and(|key| key == "model"))
.ok_or(CodexNativeError::UnsupportedLayout)?;
let (_, parent) = field
.path
.split_last()
.ok_or(CodexNativeError::UnsupportedLayout)?;
let table = table_at_mut(&mut document, parent)?;
table["model"] = toml_edit::value(native_model);
}
render_bounded(&document)
}
fn render_bounded(document: &DocumentMut) -> Result<Zeroizing<String>, CodexNativeError> {
let rendered = Zeroizing::new(document.to_string());
if rendered.len() > MAX_BYTES {
return Err(CodexNativeError::InvalidToml);
}
Ok(rendered)
}
fn parse(text: &str) -> Result<DocumentMut, CodexNativeError> {
if text.len() > MAX_BYTES || text.contains('\0') {
return Err(CodexNativeError::InvalidToml);
}
text.parse().map_err(|_| CodexNativeError::InvalidToml)
}
fn identifier(text: &str) -> bool {
!text.is_empty()
&& text.len() <= 128
&& text
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || b"_-".contains(&byte))
}
fn local_endpoint(text: &str) -> bool {
let Some(port) = text
.strip_prefix("http://127.0.0.1:")
.or_else(|| text.strip_prefix("http://[::1]:"))
.and_then(|value| value.strip_suffix("/v1"))
else {
return false;
};
!port.is_empty()
&& port.bytes().all(|byte| byte.is_ascii_digit())
&& port.parse::<u16>().is_ok_and(|port| port != 0)
}
fn fingerprint(item: &Item) -> CanonicalDigest {
match (item.as_str(), item.as_bool()) {
(Some(value), _) => CanonicalDigest::of_bytes(format!("string\0{value}").as_bytes()),
(_, Some(value)) => CanonicalDigest::of_bytes(format!("boolean\0{value}").as_bytes()),
_ => CanonicalDigest::of_bytes(format!("other\0{item}").as_bytes()),
}
}
fn optional_table<'a>(
document: &'a DocumentMut,
path: &[String],
) -> Result<Option<&'a Table>, CodexNativeError> {
let mut table = document.as_table();
for key in path {
let Some(item) = table.get(key) else {
return Ok(None);
};
table = item.as_table().ok_or(CodexNativeError::UnsupportedLayout)?;
}
Ok(Some(table))
}
fn table_at<'a>(document: &'a DocumentMut, path: &[String]) -> Result<&'a Table, CodexNativeError> {
let mut table = document.as_table();
for key in path {
table = table
.get(key)
.and_then(Item::as_table)
.ok_or(CodexNativeError::UnsupportedLayout)?;
}
Ok(table)
}
fn table_at_mut<'a>(
document: &'a mut DocumentMut,
path: &[String],
) -> Result<&'a mut Table, CodexNativeError> {
let mut table = document.as_table_mut();
for key in path {
table = table
.get_mut(key)
.and_then(Item::as_table_mut)
.ok_or(CodexNativeError::UnsupportedLayout)?;
}
Ok(table)
}
fn create_tables(
document: &mut DocumentMut,
path: &[String],
created: &mut Vec<Vec<String>>,
) -> Result<(), CodexNativeError> {
for index in 0..path.len() {
let parent = table_at_mut(document, &path[..index])?;
if !parent.contains_key(&path[index]) {
let mut table = Table::new();
table.set_implicit(true);
parent.insert(&path[index], Item::Table(table));
created.push(path[..=index].to_vec());
}
table_at(document, &path[..=index])?;
}
Ok(())
}
fn set(
document: &mut DocumentMut,
parent: &[String],
key: &str,
mut after: Item,
restore: &mut CodexNativeRestore,
) -> Result<(), CodexNativeError> {
let table = table_at_mut(document, parent)?;
let before = table.get(key).cloned();
if let Some(before) = &before {
let previous = before
.as_value()
.ok_or(CodexNativeError::UnsupportedLayout)?;
if !previous.is_str() {
return Err(CodexNativeError::UnsupportedLayout);
}
if let Some(value) = after.as_value_mut() {
*value.decor_mut() = previous.decor().clone();
}
}
let mut path = parent.to_vec();
path.push(key.to_owned());
restore.fields.push(FieldRestore {
path,
before,
after: fingerprint(&after),
passive_model: false,
});
if let Some(current) = table.get_mut(key) {
// Replacing via insert would also replace the key's decoration (leading comments).
*current = after;
} else {
table.insert(key, after);
}
Ok(())
}
#[cfg(test)]
mod tests;
fn managed_provider_shape(document: &DocumentMut) -> bool {
let Some(provider) = document
.get("model_providers")
.and_then(|v| v.get("hiroute"))
.and_then(Item::as_table)
else {
return false;
};
provider.iter().all(|(key, _)| {
matches!(
key,
"name"
| "base_url"
| "wire_api"
| "requires_openai_auth"
| "supports_websockets"
| "http_headers"
)
}) && provider
.get("http_headers")
.and_then(Item::as_table)
.is_some_and(|headers| headers.iter().all(|(key, _)| key == "X-HiRoute-Token"))
}