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
//! One owned Hermes default/provider transition, with private conditional restore state.
use super::hermes_yaml::{HermesDocument, HermesNativeError, at, hermes_error};
use hiroute_domain::{AdditionalAgentModelV1, CanonicalDigest};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::collections::BTreeMap;
use zeroize::Zeroizing;
pub const HERMES_PLUGIN_NAME: &str = "hiroute";
const COMPACT_PROVIDER_PREFIX: &str = "hiroute-main-";
// The native file already scopes this identity to one effective Hermes profile.
// Full context/grant authority stays in the sealed effect and protected restore record.
fn native_provider_id(alias: &str) -> String {
let digest = CanonicalDigest::of_bytes(alias.as_bytes());
format!("{COMPACT_PROVIDER_PREFIX}{}", &digest.as_str()[7..19])
}
fn compact_provider_key(key: &str) -> bool {
key.strip_prefix("providers/hiroute-main-")
.is_some_and(|suffix| {
suffix.len() == 12
&& suffix
.bytes()
.all(|c| c.is_ascii_digit() || (b'a'..=b'f').contains(&c))
})
}
const SELECTORS: &[&str] = &[
"default",
"provider",
"context_length",
"base_url",
"api_mode",
"transport",
"api_key",
"api_key_env",
"key_env",
"key_cmd",
"model",
"url",
"api",
];
/// This record contains native credentials; it belongs only in the protected restore port.
#[derive(Deserialize, Serialize)]
pub struct HermesConfigRestoreV1 {
schema: String,
provider_id: String,
original: Vec<u8>,
managed_file_digest: CanonicalDigest,
before: BTreeMap<String, Option<Value>>,
after: BTreeMap<String, Option<Value>>,
original_enabled: bool,
}
impl Drop for HermesConfigRestoreV1 {
fn drop(&mut self) {
use zeroize::Zeroize;
self.original.zeroize();
self.before
.values_mut()
.chain(self.after.values_mut())
.filter_map(Option::as_mut)
.for_each(super::pi_sources::clear_native_value);
}
}
pub fn hermes_configure(
current: &[u8],
previous: Option<&HermesConfigRestoreV1>,
provider_id: &str,
endpoint: &str,
model: &AdditionalAgentModelV1,
token: &str,
) -> Result<(Zeroizing<Vec<u8>>, HermesConfigRestoreV1), HermesNativeError> {
model
.validate_pi()
.map_err(|_| hermes_error("Plan budget"))?;
if !provider_id.starts_with("hiroute-main-") || token.is_empty() {
return Err(hermes_error("owned provider"));
}
let doc = HermesDocument::parse(current)?;
if doc
.value
.pointer("/plugins/disabled")
.and_then(Value::as_array)
.is_some_and(|entries| {
entries
.iter()
.any(|v| v.as_str() == Some(HERMES_PLUGIN_NAME))
})
{
return Err(hermes_error("native plugin explicitly disabled"));
}
let concrete_provider = native_provider_id(&model.alias);
if let Some(previous) = previous
&& (previous.provider_id != provider_id || !previous.applied(current)?)
{
return Err(hermes_error("owned configuration changed"));
}
if doc
.value
.get("providers")
.and_then(|p| p.get(&concrete_provider))
.is_some()
&& previous.is_none_or(|p| {
!p.after
.get(&format!("providers/{concrete_provider}"))
.is_some_and(Option::is_some)
|| p.after.get("model/default").and_then(Option::as_ref)
!= Some(&json!(model.alias))
})
|| previous.is_none() && doc.value.pointer("/plugins/entries/hiroute").is_some()
{
return Err(hermes_error("foreign provider or plugin entry"));
}
for key in ["model", "providers", "plugins"] {
if doc.value.get(key).is_some_and(|v| !v.is_object()) {
return Err(hermes_error("native mapping shape"));
}
}
let mode = match model.protocol {
hiroute_domain::AgentIngressProtocolV1::Responses => "codex_responses",
hiroute_domain::AgentIngressProtocolV1::Messages => "anthropic_messages",
hiroute_domain::AgentIngressProtocolV1::ChatCompletions => "chat_completions",
};
let base = if model.protocol == hiroute_domain::AgentIngressProtocolV1::Messages {
endpoint
.strip_suffix("/v1")
.ok_or_else(|| hermes_error("Messages base"))?
} else {
endpoint
};
let mut changes = BTreeMap::new();
for key in SELECTORS {
changes.insert(vec!["model".into(), (*key).into()], None);
}
changes.insert(
vec!["model".into(), "default".into()],
Some(json!(model.alias)),
);
changes.insert(
vec!["model".into(), "provider".into()],
Some(json!(concrete_provider)),
);
changes.insert(
vec!["model".into(), "context_length".into()],
Some(json!(model.context_window_tokens)),
);
// Hermes auxiliary Chat calls bypass request middleware and use this
// provider's standard API key. Reuse the same scoped model grant; global
// model headers could send it to an unrelated auxiliary provider.
changes.insert(vec!["providers".into(),concrete_provider.clone()],Some(json!({
"name":"HiRoute","api":base,"transport":mode,"api_key":token,
"default_model":model.alias,"models":{&model.alias:{"context_length":model.context_window_tokens}},
"extra_headers":{"X-HiRoute-Token":token}
})));
changes.insert(
vec![
"plugins".into(),
"entries".into(),
HERMES_PLUGIN_NAME.into(),
],
Some(json!({
"provider_id":concrete_provider,"model":model.alias,"base_url":base,"api_mode":mode
})),
);
// A provider alias cannot distinguish another user entry selecting the same route.
if let Some(providers) = doc.value.get("providers").and_then(Value::as_object) {
for (id, p) in providers {
if id == &concrete_provider
|| previous.is_some_and(|p| p.after.contains_key(&format!("providers/{id}")))
{
continue;
}
let address = p
.get("api")
.or_else(|| p.get("url"))
.or_else(|| p.get("base_url"))
.and_then(Value::as_str);
if address == Some(base) {
return Err(hermes_error("route-matching provider ambiguity"));
}
}
}
let mut enabled = enabled_plugins(&doc.value)?;
let original_enabled = previous.map_or(enabled.iter().any(|v| v == HERMES_PLUGIN_NAME), |p| {
p.original_enabled
});
if !enabled.iter().any(|v| v == HERMES_PLUGIN_NAME) {
enabled.push(HERMES_PLUGIN_NAME.into());
}
changes.insert(
vec!["plugins".into(), "enabled".into()],
Some(json!(enabled)),
);
if let Some(previous) = previous {
// Reconfiguration must remove the prior per-Plan provider only after owned selectors
// move, and only if no foreign native reference still uses it.
for key in previous
.after
.keys()
.filter(|k| k.starts_with("providers/"))
{
let path: Vec<_> = key.split('/').map(str::to_owned).collect();
changes.entry(path).or_insert(None);
}
}
let bytes = doc.edit(&changes)?;
// A later native consumer may reference the previous Plan provider. Never remove
// that provider while an unowned selector still references it.
if let Some(previous) = previous {
let next = HermesDocument::parse(&bytes)?;
for key in previous
.after
.keys()
.filter_map(|k| k.strip_prefix("providers/"))
{
if key != concrete_provider && refers_to(&next.value, key) {
return Err(hermes_error("remaining native provider reference"));
}
}
}
let original = previous.map_or_else(|| current.to_vec(), |p| p.original.clone());
let base_doc = HermesDocument::parse(&original)?;
let mut before = BTreeMap::new();
let mut after = BTreeMap::new();
for (path, value) in &changes {
if path == &["plugins".to_owned(), "enabled".to_owned()] {
continue;
}
before.insert(path.join("/"), at(&base_doc.value, path).cloned());
after.insert(path.join("/"), value.clone());
}
let restore = HermesConfigRestoreV1 {
schema: "hiroute.hermes-config-restore/v1".into(),
provider_id: provider_id.into(),
original,
managed_file_digest: CanonicalDigest::of_bytes(&bytes),
before,
after,
original_enabled,
};
Ok((bytes, restore))
}
fn enabled_plugins(root: &Value) -> Result<Vec<String>, HermesNativeError> {
match root.pointer("/plugins/enabled") {
None => Ok(Vec::new()),
Some(Value::Array(a)) if a.len() <= 256 => a
.iter()
.map(|v| {
v.as_str()
.map(str::to_owned)
.ok_or_else(|| hermes_error("enabled plugin list"))
})
.collect(),
_ => Err(hermes_error("enabled plugin list")),
}
}
impl HermesConfigRestoreV1 {
pub fn encode(&self) -> Result<Zeroizing<Vec<u8>>, HermesNativeError> {
self.validate()?;
serde_json::to_vec(self)
.map(Zeroizing::new)
.map_err(|_| hermes_error("restore encode"))
}
pub fn decode(bytes: &[u8]) -> Result<Self, HermesNativeError> {
let value: Self =
serde_json::from_slice(bytes).map_err(|_| hermes_error("restore decode"))?;
value.validate()?;
Ok(value)
}
fn validate(&self) -> Result<(), HermesNativeError> {
if self.schema != "hiroute.hermes-config-restore/v1"
|| !self.provider_id.starts_with("hiroute-main-")
|| self.before.len() != self.after.len()
|| self.before.keys().ne(self.after.keys())
{
return Err(hermes_error("restore record"));
}
for key in self.after.keys() {
let compact = compact_provider_key(key)
&& self.before[key].is_none()
&& (self.after[key].is_none()
|| self
.after
.get("model/default")
.and_then(Option::as_ref)
.and_then(Value::as_str)
.is_some_and(|alias| {
key == &format!("providers/{}", native_provider_id(alias))
}));
if !(key.starts_with("model/") && SELECTORS.contains(&&key[6..]))
&& !key.starts_with(&format!("providers/{}-", self.provider_id))
&& !compact
&& key != "plugins/entries/hiroute"
{
return Err(hermes_error("restore ownership"));
}
}
Ok(())
}
pub fn applied(&self, current: &[u8]) -> Result<bool, HermesNativeError> {
self.validate()?;
let doc = HermesDocument::parse(current)?;
Ok(self.after.iter().all(|(key, value)| {
at(
&doc.value,
&key.split('/').map(str::to_owned).collect::<Vec<_>>(),
) == value.as_ref()
}) && enabled_plugins(&doc.value)?
.iter()
.any(|v| v == HERMES_PLUGIN_NAME))
}
pub fn restore(&self, current: &[u8]) -> Result<Zeroizing<Vec<u8>>, HermesNativeError> {
if !self.applied(current)? {
return Err(hermes_error("owned configuration changed"));
}
if CanonicalDigest::of_bytes(current) == self.managed_file_digest {
return Ok(Zeroizing::new(self.original.clone()));
}
let doc = HermesDocument::parse(current)?;
let mut changes: BTreeMap<Vec<String>, Option<Value>> = self
.before
.iter()
.map(|(key, value)| (key.split('/').map(str::to_owned).collect(), value.clone()))
.collect();
let mut enabled = enabled_plugins(&doc.value)?;
if !self.original_enabled {
enabled.retain(|v| v != HERMES_PLUGIN_NAME);
}
let original = HermesDocument::parse(&self.original)?;
changes.insert(
vec!["plugins".into(), "enabled".into()],
if enabled.is_empty() && original.value.pointer("/plugins/enabled").is_none() {
None
} else {
Some(json!(enabled))
},
);
let mut next = doc.edit(&changes)?;
// Removing the final owned member must not leave a YAML null overriding a native
// default. Only empty containers introduced by this adapter can be released.
for path in [
vec!["model".into()],
vec!["providers".into()],
vec!["plugins".into(), "entries".into()],
vec!["plugins".into()],
] {
let restored = HermesDocument::parse(&next)?;
let value = at(&restored.value, &path);
let before = at(&original.value, &path);
if value.is_some_and(|v| v.is_null() || v.as_object().is_some_and(|m| m.is_empty()))
&& before.is_none_or(|v| v.as_object().is_some_and(|m| m.is_empty()))
{
next = restored.edit(&BTreeMap::from([(path, before.cloned())]))?;
}
}
let next_doc = HermesDocument::parse(&next)?;
for key in self
.after
.keys()
.filter_map(|k| k.strip_prefix("providers/"))
{
if self.before[&format!("providers/{key}")].is_none() && refers_to(&next_doc.value, key)
{
return Err(hermes_error("remaining native provider reference"));
}
}
Ok(next)
}
}
fn refers_to(value: &Value, id: &str) -> bool {
match value {
Value::String(s) => s == id || s.starts_with(&format!("{id}/")),
Value::Array(a) => a.iter().any(|v| refers_to(v, id)),
Value::Object(o) => o.values().any(|v| refers_to(v, id)),
_ => false,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture_model(alias: &str) -> AdditionalAgentModelV1 {
AdditionalAgentModelV1 {
alias: alias.into(),
protocol: hiroute_domain::AgentIngressProtocolV1::Responses,
context_window_tokens: 64000,
max_output_tokens: 8192,
}
}
#[test]
fn prior_long_name_restore_bytes_reconfigure_compactly_and_keep_original_baseline() {
// Captured with the unchanged 80269c5 production library, not this producer.
let fixture: Value = serde_json::from_str(include_str!(
"../../tests/fixtures/hermes-config-restore-80269c5.json"
))
.unwrap();
let original = fixture["original"].as_str().unwrap().as_bytes();
let legacy = fixture["managed"].as_str().unwrap().as_bytes();
let record: HermesConfigRestoreV1 =
serde_json::from_value(fixture["restore"].clone()).unwrap();
assert!(record.applied(legacy).unwrap());
assert_eq!(record.restore(legacy).unwrap().as_slice(), original);
let model = fixture_model("hiroute-fixture");
let (compact, updated) = hermes_configure(
legacy,
Some(&record),
&record.provider_id,
"http://127.0.0.1:8317/v1",
&model,
"synthetic-local-grant-token",
)
.unwrap();
let doc = HermesDocument::parse(&compact).unwrap();
let provider = doc.value["model"]["provider"].as_str().unwrap();
assert_eq!(provider.len(), 25);
assert_eq!(provider, native_provider_id(&model.alias));
assert_eq!(doc.value["providers"][provider]["name"], "HiRoute");
assert_eq!(
doc.value["providers"][provider]["api_key"],
"synthetic-local-grant-token"
);
assert_eq!(doc.value["providers"].as_object().unwrap().len(), 1);
let reopened = HermesConfigRestoreV1::decode(&updated.encode().unwrap()).unwrap();
assert!(reopened.applied(&compact).unwrap());
assert_eq!(reopened.restore(&compact).unwrap().as_slice(), original);
let (again, next) = hermes_configure(
&compact,
Some(&reopened),
&record.provider_id,
"http://127.0.0.1:8317/v1",
&fixture_model("hiroute-second"),
"synthetic-local-grant-token",
)
.unwrap();
assert_ne!(
HermesDocument::parse(&again).unwrap().value["model"]["provider"],
provider
);
assert_eq!(next.restore(&again).unwrap().as_slice(), original);
}
#[test]
fn chat_auxiliary_key_is_provider_scoped_and_the_complete_before_image_survives() {
let original = br#"model:
default: user-model
provider: user-provider
default_headers: {X-User-Header: preserve}
providers:
user-provider: {api: 'https://user.invalid/v1', api_key: unrelated-user-key}
auxiliary:
title: {provider: user-provider, model: user-title-model}
"#;
let mut model = fixture_model("hiroute-auxiliary-chat");
model.protocol = hiroute_domain::AgentIngressProtocolV1::ChatCompletions;
let (managed, record) = hermes_configure(
original,
None,
"hiroute-main-owner",
"http://127.0.0.1:8317/v1",
&model,
"synthetic-local-grant-token",
)
.unwrap();
let doc = HermesDocument::parse(&managed).unwrap();
let provider = doc.value["model"]["provider"].as_str().unwrap();
assert_eq!(
doc.value["providers"][provider]["api_key"],
"synthetic-local-grant-token"
);
assert_eq!(
doc.value["providers"][provider]["extra_headers"]["X-HiRoute-Token"],
"synthetic-local-grant-token"
);
assert!(doc.value.pointer("/model/extra_headers").is_none());
let prior = HermesDocument::parse(original).unwrap();
for path in [
"/model/default_headers",
"/providers/user-provider",
"/auxiliary",
] {
assert_eq!(doc.value.pointer(path), prior.value.pointer(path));
}
let reopened = HermesConfigRestoreV1::decode(&record.encode().unwrap()).unwrap();
assert_eq!(reopened.restore(&managed).unwrap().as_slice(), original);
}
#[test]
fn compact_name_never_adopts_foreign_destination_or_drops_native_references() {
let namespace = "hiroute-main-owner";
let first = fixture_model("hiroute-first");
let second = fixture_model("hiroute-second");
let (managed, record) = hermes_configure(
b"user_note: preserve\n",
None,
namespace,
"http://127.0.0.1:8317/v1",
&first,
"synthetic-local-grant-token",
)
.unwrap();
let doc = HermesDocument::parse(&managed).unwrap();
let foreign = doc
.edit(&BTreeMap::from([(
vec!["providers".into(), native_provider_id(&second.alias)],
Some(json!({"api":"https://foreign.invalid/v1"})),
)]))
.unwrap();
assert!(record.applied(&foreign).unwrap());
assert!(
hermes_configure(
&foreign,
Some(&record),
namespace,
"http://127.0.0.1:8317/v1",
&second,
"synthetic-local-grant-token"
)
.is_err()
);
let referenced = doc
.edit(&BTreeMap::from([(
vec!["auxiliary".into(), "provider".into()],
Some(json!(native_provider_id(&first.alias))),
)]))
.unwrap();
assert!(record.applied(&referenced).unwrap());
assert!(
hermes_configure(
&referenced,
Some(&record),
namespace,
"http://127.0.0.1:8317/v1",
&second,
"synthetic-local-grant-token"
)
.is_err()
);
assert!(record.restore(&referenced).is_err());
}
#[test]
fn selected_transport_uses_native_sdk_base_and_restores_exact_original() {
use hiroute_domain::AgentIngressProtocolV1::*;
let original = b"user_note: preserve\n";
for (protocol, transport, base) in [
(Responses, "codex_responses", "http://127.0.0.1:8317/v1"),
(Messages, "anthropic_messages", "http://127.0.0.1:8317"),
(
ChatCompletions,
"chat_completions",
"http://127.0.0.1:8317/v1",
),
] {
let model = AdditionalAgentModelV1 {
alias: "hiroute_test".into(),
protocol,
context_window_tokens: 64000,
max_output_tokens: 8192,
};
let (managed, record) = hermes_configure(
original,
None,
"hiroute-main-test",
"http://127.0.0.1:8317/v1",
&model,
"local-token",
)
.unwrap();
let doc = HermesDocument::parse(&managed).unwrap();
let provider = doc.value["model"]["provider"].as_str().unwrap();
assert_eq!(doc.value["providers"][provider]["transport"], transport);
assert_eq!(doc.value["providers"][provider]["api"], base);
assert_eq!(doc.value["user_note"], "preserve");
assert_eq!(record.restore(&managed).unwrap().as_slice(), original);
}
}
#[test]
fn conditional_restore_releases_only_introduced_empty_containers() {
let model = AdditionalAgentModelV1 {
alias: "hiroute_test".into(),
protocol: hiroute_domain::AgentIngressProtocolV1::Responses,
context_window_tokens: 64000,
max_output_tokens: 8192,
};
for original in [
b"unrelated: true\n".as_slice(),
b"model: {}\nproviders: {}\nunrelated: true\n".as_slice(),
] {
let (managed, record) = hermes_configure(
original,
None,
"hiroute-main-test",
"http://127.0.0.1:8317/v1",
&model,
"local-token",
)
.unwrap();
let mut edited = managed.to_vec();
edited.extend_from_slice(b"later: retained\n");
let restored = HermesDocument::parse(&record.restore(&edited).unwrap()).unwrap();
let mut expected = HermesDocument::parse(original).unwrap().value.clone();
expected["later"] = json!("retained");
assert_eq!(restored.value, expected);
}
}
#[test]
fn scoped_default_restore_keeps_foreign_edits_and_plugin_members() {
let original=b"model:\n default: glm-5.3\n provider: glm\n base_url: https://stale.example\nproviders:\n glm:\n api: https://coding.example\nplugins:\n enabled: [other]\nauxiliary:\n title: native # unchanged\n";
let model = AdditionalAgentModelV1 {
alias: "hiroute_test".into(),
protocol: hiroute_domain::AgentIngressProtocolV1::Responses,
context_window_tokens: 64000,
max_output_tokens: 8192,
};
let (managed, record) = hermes_configure(
original,
None,
"hiroute-main-test",
"http://127.0.0.1:8317/v1",
&model,
"local-token",
)
.unwrap();
assert!(record.applied(&managed).unwrap());
assert_eq!(record.restore(&managed).unwrap().as_slice(), original);
let mut edited = managed.to_vec();
edited.extend_from_slice(b"user_note: preserve\n");
let restored = record.restore(&edited).unwrap();
let doc = HermesDocument::parse(&restored).unwrap();
assert_eq!(doc.value["model"]["default"], "glm-5.3");
assert_eq!(doc.value["user_note"], "preserve");
assert_eq!(doc.value["plugins"]["enabled"], json!(["other"]));
let changed = HermesDocument::parse(&managed)
.unwrap()
.edit(&BTreeMap::from([(
vec!["model".into(), "default".into()],
Some(json!("foreign")),
)]))
.unwrap();
assert!(record.restore(&changed).is_err());
}
}