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
use hiroute_domain::{
AgentClaudePresetValuesV2, AgentConfigChangeV1, AgentConnectionControlIntentV1,
AgentConnectionEffectRoleV1, AgentConnectionTransactionKindV1, AgentFacetIntent,
AgentModelGrantV2, AgentOperationRead, AgentSettingsSpecV2, CanonicalDigest,
ExternalEffectIntentV1, OperationId, OperationValidationError, PortError, PortErrorCode,
PortResult,
};
use serde::{Deserialize, Serialize};
use std::path::Path;
const SCHEMA: &str = "hiroute.settings-claude-model-file/v1";
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ClaudeLaunchSnapshotIntent {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub context_window_tokens: Option<u64>,
pub native_presets: AgentClaudePresetValuesV2,
pub presets: AgentClaudePresetValuesV2,
pub executable: String,
pub installation_digest: CanonicalDigest,
}
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
pub enum ClaudeModelFileAction {
Configure {
previous_operation: Option<OperationId>,
change: AgentConfigChangeV1,
snapshot: Box<ClaudeLaunchSnapshotIntent>,
gateway_base_url: String,
trusted_hiroute_executable: String,
},
Restore {
original_operation: OperationId,
},
}
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ClaudeModelFilePayload {
schema: String,
pub context_id: String,
pub expected_content: CanonicalDigest,
pub change: ClaudeModelFileAction,
}
pub fn settings_claude_model_file_intent(
control: &AgentConnectionControlIntentV1,
context_id: &str,
expected_content: CanonicalDigest,
before_fingerprint: Option<CanonicalDigest>,
change: ClaudeModelFileAction,
) -> Result<ExternalEffectIntentV1, OperationValidationError> {
if control.transaction() != AgentConnectionTransactionKindV1::Settings {
return Err(OperationValidationError::UnregisteredEffectPlan);
}
let payload = ClaudeModelFilePayload {
schema: SCHEMA.into(),
context_id: context_id.into(),
expected_content,
change,
};
validate_payload(&payload)?;
let intent = ExternalEffectIntentV1::from_agent_connection_planner(
control,
AgentConnectionEffectRoleV1::ManagedConfiguration,
before_fingerprint,
&payload,
0o600,
)?;
decode_settings_claude_model_file(&intent)
.map_err(|_| OperationValidationError::UnregisteredEffectPlan)?;
Ok(intent)
}
pub fn decode_settings_claude_model_file(
intent: &ExternalEffectIntentV1,
) -> PortResult<ClaudeModelFilePayload> {
ExternalEffectIntentV1::from_registered_adapter(
intent.effect_id(),
intent.kind(),
intent.target(),
intent.before_fingerprint().cloned(),
intent.desired().clone(),
intent.desired_mode(),
intent.sensitive(),
)
.map_err(|_| invalid())?;
let value = intent.desired();
if intent.effect_id() != "agent-connection-managed-configuration"
|| intent.desired_mode() != 0o600
|| value["transaction"] != "settings"
|| value["subject"]["agent_id"] != "agent_claude_default"
|| value["subject"]["profile_id"] != "claude-messages-v1"
|| value["subject"]["integration_profile_ref"] != "builtin/claude-messages/v1"
{
return Err(invalid());
}
let payload: ClaudeModelFilePayload =
serde_json::from_value(value["payload"].clone()).map_err(|_| invalid())?;
validate_payload(&payload).map_err(|_| invalid())?;
Ok(payload)
}
pub fn settings_claude_model_file_for_operation(
operation: &(impl AgentOperationRead + ?Sized),
intent: &ExternalEffectIntentV1,
) -> PortResult<ClaudeModelFilePayload> {
let payload = decode_settings_claude_model_file(intent)?;
let spec: AgentSettingsSpecV2 =
serde_json::from_value(operation.agent_input().spec.desired_state.clone())
.map_err(|_| invalid())?;
if operation.agent_input().spec.command_id != "agents.settings.apply"
|| spec.context_id != payload.context_id
|| !operation.agent_input().external.contains(intent)
{
return Err(invalid());
}
let state = &operation.agent_input().control["payload"]["state"];
if state["accept_digest"]
!= serde_json::to_value(operation.accepted_digest()).map_err(|_| invalid())?
{
return Err(invalid());
}
match (&spec.model, &payload.change) {
(
AgentFacetIntent::Configure { settings },
ClaudeModelFileAction::Configure {
previous_operation,
snapshot,
..
},
) => {
let grant: AgentModelGrantV2 =
serde_json::from_value(state["model_grant"].clone()).map_err(|_| invalid())?;
let [mutation] = operation.agent_input().grants else {
return Err(invalid());
};
let scope = mutation.desired_scope().ok_or_else(invalid)?;
if scope.model_grant() != &grant
|| previous_operation.as_ref() == Some(operation.operation_id())
|| grant
.claude_preset_values(settings, &snapshot.native_presets)
.map_err(|_| invalid())?
!= snapshot.presets
{
return Err(invalid());
}
}
(
AgentFacetIntent::Restore { restore_point_ref },
ClaudeModelFileAction::Restore { original_operation },
) if original_operation != operation.operation_id()
&& *restore_point_ref == super::codex_model_restore_point_ref(original_operation) => {}
_ => return Err(invalid()),
}
Ok(payload)
}
fn validate_payload(payload: &ClaudeModelFilePayload) -> Result<(), OperationValidationError> {
let invalid = || OperationValidationError::UnregisteredEffectPlan;
if payload.schema != SCHEMA || !super::settings::identity(&payload.context_id) {
return Err(invalid());
}
match &payload.change {
ClaudeModelFileAction::Configure {
previous_operation,
change,
snapshot,
gateway_base_url,
trusted_hiroute_executable,
} => {
if !local_gateway_base_url(gateway_base_url)
|| snapshot.context_window_tokens.is_some_and(|value| {
hiroute_domain::claude_context_window(value) != Some(value)
})
|| change.validate().is_err()
|| change.fields.iter().any(|field| {
!matches!(
field.path.as_str(),
"apiKeyHelper"
| "hiroute.auth_environment"
| "env.ANTHROPIC_BASE_URL"
| "env.ANTHROPIC_DEFAULT_OPUS_MODEL"
| "env.ANTHROPIC_DEFAULT_SONNET_MODEL"
| "env.ANTHROPIC_DEFAULT_HAIKU_MODEL"
| "env.CLAUDE_CODE_AUTO_COMPACT_WINDOW"
| "env.CLAUDE_CODE_MAX_CONTEXT_TOKENS"
)
})
|| !Path::new(trusted_hiroute_executable).is_absolute()
|| trusted_hiroute_executable.contains(['\0', '\r', '\n'])
|| previous_operation.as_ref().is_some_and(|previous| {
OperationId::parse(previous.as_str().to_owned()).is_err()
})
|| !Path::new(&snapshot.executable).is_absolute()
|| snapshot.executable.contains(['\0', '\r', '\n'])
|| CanonicalDigest::parse(snapshot.installation_digest.as_str()).is_err()
|| [&snapshot.native_presets, &snapshot.presets]
.into_iter()
.any(|presets| {
[&presets.opus, &presets.sonnet, &presets.haiku]
.into_iter()
.filter_map(|value| value.as_deref())
.any(|value| !hiroute_domain::valid_client_model_name(value))
})
{
return Err(invalid());
}
}
ClaudeModelFileAction::Restore { original_operation } => {
OperationId::parse(original_operation.as_str().to_owned()).map_err(|_| invalid())?;
}
}
Ok(())
}
fn local_gateway_base_url(value: &str) -> bool {
value
.strip_suffix("/v1")
.and_then(|origin| {
origin
.strip_prefix("http://127.0.0.1:")
.or_else(|| origin.strip_prefix("http://[::1]:"))
})
.is_some_and(|port| {
!port.is_empty()
&& port.bytes().all(|byte| byte.is_ascii_digit())
&& port.parse::<u16>().is_ok_and(|port| port != 0)
})
}
fn invalid() -> PortError {
PortError::new(PortErrorCode::InvalidData, "claude.settings.intent")
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture_path(value: &str) -> String {
if cfg!(windows) {
format!("C:{value}")
} else {
value.to_owned()
}
}
fn payload() -> ClaudeModelFilePayload {
ClaudeModelFilePayload {
schema: SCHEMA.into(),
context_id: "agent-context/claude/test".into(),
expected_content: CanonicalDigest::of_bytes(b""),
change: ClaudeModelFileAction::Configure {
previous_operation: None,
change: AgentConfigChangeV1::preview(
&hiroute_domain::AgentConfigDocumentV1::default(),
std::collections::BTreeMap::new(),
)
.unwrap(),
snapshot: Box::new(ClaudeLaunchSnapshotIntent {
context_window_tokens: None,
native_presets: AgentClaudePresetValuesV2 {
opus: Some("Vendor/Opus[1m]".into()),
sonnet: None,
haiku: None,
},
presets: AgentClaudePresetValuesV2 {
opus: Some("hr-plan-opus".into()),
sonnet: None,
haiku: None,
},
executable: fixture_path("/opt/claude/bin/claude"),
installation_digest: CanonicalDigest::of_bytes(b"installation"),
}),
gateway_base_url: "http://127.0.0.1:8080/v1".into(),
trusted_hiroute_executable: fixture_path("/opt/hiroute/bin/hiroute"),
},
}
}
#[test]
fn native_change_and_optional_launcher_facts_are_sealed_without_original_secret_bytes() {
let mut original = payload();
if let ClaudeModelFileAction::Configure { change, .. } = &mut original.change {
*change = AgentConfigChangeV1::preview(
&hiroute_domain::AgentConfigDocumentV1 {
fields: std::collections::BTreeMap::from([
(
"apiKeyHelper".into(),
serde_json::json!({"configured":true}),
),
(
"hiroute.auth_environment".into(),
serde_json::json!({"configured":true}),
),
]),
},
std::collections::BTreeMap::from([
("hiroute.auth_environment".into(), None),
(
"env.ANTHROPIC_BASE_URL".into(),
Some(serde_json::json!("http://127.0.0.1:8080")),
),
]),
)
.unwrap();
}
assert!(validate_payload(&original).is_ok());
let value = serde_json::to_value(&original).unwrap();
let snapshot = &value["change"]["snapshot"];
assert_eq!(snapshot["native_presets"]["opus"], "Vendor/Opus[1m]");
assert_eq!(snapshot["presets"]["opus"], "hr-plan-opus");
assert_eq!(
snapshot["executable"],
fixture_path("/opt/claude/bin/claude")
);
assert!(snapshot["native_presets"]["sonnet"].is_null());
assert_eq!(
value["change"]["change"]["fields"][0]["path"],
"env.ANTHROPIC_BASE_URL"
);
assert_eq!(
value["change"]["change"]["fields"][1]["path"],
"hiroute.auth_environment"
);
assert_eq!(
value["change"]["change"]["fields"][1]["before"],
serde_json::json!({"configured":true})
);
assert!(
!value.to_string().contains("user-owned-helper")
&& !value.to_string().contains("user-secret")
);
let decoded: ClaudeModelFilePayload = serde_json::from_value(value).unwrap();
assert!(validate_payload(&decoded).is_ok());
}
#[test]
fn snapshot_rejects_remote_gateway_and_unsafe_helper() {
for endpoint in [
"https://example.com/v1",
"http://127.0.0.1:0/v1",
"http://127.0.0.1:8080/other",
] {
let mut candidate = payload();
if let ClaudeModelFileAction::Configure {
gateway_base_url, ..
} = &mut candidate.change
{
*gateway_base_url = endpoint.into();
}
assert!(validate_payload(&candidate).is_err());
}
for executable in ["hiroute", "/opt/hiroute\nother", "/opt/hiroute\0other"] {
let mut candidate = payload();
if let ClaudeModelFileAction::Configure {
trusted_hiroute_executable,
..
} = &mut candidate.change
{
*trusted_hiroute_executable = executable.into();
}
assert!(validate_payload(&candidate).is_err());
}
}
#[test]
fn snapshot_rejects_unsafe_claude_executable() {
for executable in ["claude", "/opt/claude\nother", "/opt/claude\0other"] {
let mut candidate = payload();
if let ClaudeModelFileAction::Configure { snapshot, .. } = &mut candidate.change {
snapshot.executable = executable.into();
}
assert!(validate_payload(&candidate).is_err());
}
}
#[test]
fn native_change_rejects_invalid_semantic_file_changes() {
let mut value = serde_json::to_value(payload()).unwrap();
value["change"]["change"] = serde_json::json!({"fields": []});
assert!(serde_json::from_value::<ClaudeModelFilePayload>(value).is_err());
}
}