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
//! Explicit, admitted native consumption probe. Discovery/Preview never call this module.
//! The existing Operation owns all configuration writes and restoration; no temp-root cleanup
//! occurs here. A pending result becomes usable evidence only after a recorded restoration.
use super::{CodexFileConfiguration, CodexSelectionTarget, configure_codex_native};
use hiroute_domain::{
AgentAccessGrantMaterial, AgentCapability, CanonicalDigest, CapabilityState,
EffectReconciliation, ExternalEffectIntentV1, ModelAlias, NativeAgentArtifactPort, OperationId,
SupportedAgentInstallationV1,
};
use std::fs;
use std::net::TcpListener;
#[cfg(unix)]
use std::os::unix::fs::MetadataExt;
#[cfg(unix)]
use std::os::unix::process::CommandExt;
use std::path::Path;
use std::process::{Command, Stdio};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
#[path = "ephemeral_ingress_probe.rs"]
mod ephemeral;
#[path = "native_probe_http.rs"]
mod http;
const CONTRACT: &str = "hiroute.codex-native-responses/v1";
/// Preserve installation discovery's absolute executable search paths for npm wrappers.
/// Authentication and routing environment are still cleared, and relative project paths
/// never enter the isolated probe workspace.
pub(super) fn native_probe_path() -> std::ffi::OsString {
probe_path(std::env::var_os("PATH").as_deref())
}
fn probe_path(path: Option<&std::ffi::OsStr>) -> std::ffi::OsString {
let directories = path
.map(std::env::split_paths)
.into_iter()
.flatten()
.filter(|path| path.is_absolute())
.collect::<Vec<_>>();
#[cfg(unix)]
let mut directories = directories;
#[cfg(unix)]
for system in ["/usr/bin", "/bin"] {
let system = std::path::PathBuf::from(system);
if !directories.contains(&system) {
directories.push(system);
}
}
std::env::join_paths(directories).expect("split absolute paths remain joinable")
}
#[derive(Clone, Copy, Debug, thiserror::Error)]
#[error("native ingress probe could not establish {0}")]
pub struct NativeIngressProbeError(&'static str);
/// A fresh local challenge, not an upstream credential or a HiRoute authorization grant.
/// No Debug/serde: the local challenge must not enter public diagnostics.
pub struct CodexNativeIngressProbe {
listener: TcpListener,
endpoint: String,
grant: AgentAccessGrantMaterial,
model: ModelAlias,
empty: CanonicalDigest,
}
impl CodexNativeIngressProbe {
pub fn bind() -> Result<Self, NativeIngressProbeError> {
let listener = TcpListener::bind("127.0.0.1:0").map_err(|_| fail("loopback bind"))?;
listener
.set_nonblocking(true)
.map_err(|_| fail("loopback mode"))?;
let endpoint = format!(
"http://{}/v1",
listener.local_addr().map_err(|_| fail("address"))?
);
let mut entropy = [0; 32];
getrandom::fill(&mut entropy).map_err(|_| fail("randomness"))?;
Ok(Self {
listener,
endpoint,
grant: AgentAccessGrantMaterial::from_csprng_entropy(entropy),
model: ModelAlias::parse("hiroute/0011223344556677")
.map_err(|_| fail("probe model"))?,
empty: CanonicalDigest::of_bytes(b""),
})
}
/// Stage this configuration using the existing admitted Operation artifact effect.
/// The caller must allocate an isolated, originally absent home/.codex/config.toml target.
pub fn configuration(&self) -> CodexFileConfiguration<'_> {
CodexFileConfiguration {
expected_content: &self.empty,
selection: CodexSelectionTarget::Root,
provider_id: "hiroute",
endpoint: &self.endpoint,
model: Some(self.model.as_str()),
local_grant: &self.grant,
model_catalog: None,
managed_aliases: &[],
}
}
/// Only the trusted backend calls this after explicit verification admission. The supplied
/// home must contain exactly .codex/config.toml; cwd must be empty and private. No inherited
/// auth, shell environment, project settings, rules or copied session material is accepted.
/// The caller must restore the applied effect on both Ok and Err before cleaning its root.
pub fn run(
self,
executable: &Path,
home: &Path,
workspace: &Path,
port: &dyn NativeAgentArtifactPort,
operation: &OperationId,
intent: &ExternalEffectIntentV1,
) -> Result<PendingCodexIngressEvidence, NativeIngressProbeError> {
let binary = super::executable::resolve(executable)
.map_err(|_| fail("trusted executable"))?
.ok_or_else(|| fail("executable"))?;
private_directory(home)?;
private_directory(workspace)?;
let config_root = home.join(".codex");
private_directory(&config_root)?;
if entries(home)? != [".codex"]
|| entries(&config_root)? != ["config.toml"]
|| !entries(workspace)?.is_empty()
|| home == workspace
|| super::codex_profile::codex_has_system_configuration()
.map_err(|_| fail("organization configuration isolation"))?
{
return Err(fail("isolated native configuration"));
}
if intent.before_fingerprint().is_some()
|| !matches!(
port.observe_artifact(operation, intent),
Ok(EffectReconciliation::Applied(_))
)
{
return Err(fail("applied isolated effect"));
}
let expected = configure_codex_native(
"",
&self.empty,
CodexSelectionTarget::Root,
"hiroute",
&self.endpoint,
Some(self.model.as_str()),
&self.grant,
)
.map_err(|_| fail("native rendering"))?;
let config_path = config_root.join("config.toml");
let bytes = super::filesystem_config::read_validated_config_bytes(&config_path)
.map_err(|_| fail("native configuration read"))?
.ok_or_else(|| fail("native configuration"))?
.0;
let stored = port
.read_native_target(intent.target())
.map_err(|_| fail("artifact read"))?
.ok_or_else(|| fail("artifact target"))?;
if bytes.as_slice() != expected.rendered.as_bytes() || *stored != *bytes {
return Err(fail("native target binding"));
}
let mut command = Command::new(&binary);
command
.args([
"exec",
"--ephemeral",
"--skip-git-repo-check",
"--ignore-rules",
"--sandbox",
"read-only",
"--color",
"never",
"--json",
"Reply with OK only. Do not use tools.",
])
.env_clear()
.env("HOME", home)
.env("CODEX_HOME", &config_root)
.env("TMPDIR", workspace)
.env("PATH", native_probe_path())
.current_dir(workspace)
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null());
#[cfg(unix)]
let child = command
.process_group(0)
.spawn()
.map_err(|_| fail("native launch"))?;
#[cfg(windows)]
let child = super::windows_runtime::spawn(
&command,
false,
hiroute_platform::windows::job::Stream::Null,
hiroute_platform::windows::job::Stream::Null,
hiroute_platform::windows::job::Stream::Null,
)
.map_err(|_| fail("native launch"))?;
let mut child = super::NativeProbeProcess::new(child);
let started = Instant::now();
let mut requests = 0;
let result = (|| {
loop {
match self.listener.accept() {
Ok((mut stream, _)) => {
requests += 1;
if requests > 4 {
return Err(fail("request bound"));
}
http::serve(&mut stream, self.grant.expose(), self.model.as_str())
.map_err(fail)?;
}
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {}
Err(_) => return Err(fail("loopback accept")),
}
if let Some(success) = child.observe().map_err(|_| fail("native wait"))? {
return if success && requests > 0 {
Ok(())
} else {
Err(fail("authenticated native completion"))
};
}
if started.elapsed() > Duration::from_secs(25) {
return Err(fail("deadline"));
}
std::thread::sleep(Duration::from_millis(10));
}
})();
child.stop().map_err(|_| fail("native cleanup"))?;
result?;
Ok(PendingCodexIngressEvidence {
observed: Instant::now(),
observed_at: now(),
original_operation: operation.clone(),
target: intent.target().to_owned(),
})
}
}
/// Cannot be serialized or attached to discovery until the formal restore effect is observed.
pub struct PendingCodexIngressEvidence {
observed: Instant,
observed_at: u64,
original_operation: OperationId,
target: String,
}
impl PendingCodexIngressEvidence {
pub fn after_restoration(
self,
port: &dyn NativeAgentArtifactPort,
restore_operation: &OperationId,
restore_intent: &ExternalEffectIntentV1,
) -> Result<CodexIngressEvidence, NativeIngressProbeError> {
if restore_operation == &self.original_operation
|| restore_intent.target() != self.target
|| !matches!(
port.observe_artifact(restore_operation, restore_intent),
Ok(EffectReconciliation::Applied(_))
)
|| port
.read_native_target(&self.target)
.map_err(|_| fail("restored target read"))?
.is_some()
{
return Err(fail("recorded native restoration"));
}
Ok(CodexIngressEvidence {
observed: self.observed,
observed_at: self.observed_at,
collaboration: false,
})
}
}
/// Backend-only cache entry. Five-minute expiry requires a new explicit probe. The successful
/// challenge is intentionally not rebound to a Codex binary identity, version, or release.
#[derive(Clone)]
pub struct CodexIngressEvidence {
observed: Instant,
observed_at: u64,
collaboration: bool,
}
impl CodexIngressEvidence {
pub(super) fn attach_collaboration(&self, installation: &mut SupportedAgentInstallationV1) {
if self.collaboration {
self.attach(installation);
}
}
pub(super) fn attach(&self, installation: &mut SupportedAgentInstallationV1) {
if self.observed.elapsed() > Duration::from_secs(300) {
return;
}
let Some(index) = installation
.capability_evidence
.iter()
.position(|proof| proof.capability == AgentCapability::IngressAuthentication)
else {
return;
};
installation.observation_digest = CanonicalDigest::of(&(
CONTRACT,
&installation.observation_digest,
self.collaboration,
self.observed_at,
))
.expect("bounded native evidence");
for proof in &mut installation.capability_evidence {
proof.dependency_digest = installation.observation_digest.clone();
}
let proof = &mut installation.capability_evidence[index];
proof.state = CapabilityState::Proven;
proof.reason = None;
proof.adapter_contract = CONTRACT.into();
proof.observed_at_unix_ms = self.observed_at;
if self.collaboration {
for proof in &mut installation.capability_evidence {
if matches!(
proof.capability,
AgentCapability::SkillLoading | AgentCapability::TrustedCliExecution
) {
proof.state = CapabilityState::Proven;
proof.reason = None;
proof.adapter_contract = "hiroute.codex-collaboration/v1".into();
proof.observed_at_unix_ms = self.observed_at;
}
}
}
}
}
pub(super) fn fail(reason: &'static str) -> NativeIngressProbeError {
NativeIngressProbeError(reason)
}
pub(super) fn now() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|value| value.as_millis().min(u64::MAX as u128) as u64)
.unwrap_or(1)
.max(1)
}
pub(super) fn private_directory(path: &Path) -> Result<(), NativeIngressProbeError> {
let meta = fs::symlink_metadata(path).map_err(|_| fail("private directory"))?;
if !path.is_absolute() || !meta.is_dir() || meta.file_type().is_symlink() {
return Err(fail("private directory"));
}
Ok(())
}
fn entries(path: &Path) -> Result<Vec<String>, NativeIngressProbeError> {
let mut names = Vec::new();
for item in fs::read_dir(path)
.map_err(|_| fail("isolated directory"))?
.take(3)
{
names.push(
item.map_err(|_| fail("isolated entry"))?
.file_name()
.into_string()
.map_err(|_| fail("isolated entry name"))?,
);
}
names.sort();
Ok(names)
}
pub(super) fn binary_identity(
executable: &Path,
) -> Result<CanonicalDigest, NativeIngressProbeError> {
let path = super::executable::resolve(executable)
.map_err(|_| fail("trusted executable"))?
.ok_or_else(|| fail("executable"))?;
let meta = fs::metadata(&path).map_err(|_| fail("executable metadata"))?;
#[cfg(unix)]
return CanonicalDigest::of(&(
path,
meta.dev(),
meta.ino(),
meta.uid(),
meta.gid(),
meta.mode(),
meta.len(),
meta.mtime(),
meta.mtime_nsec(),
meta.ctime(),
meta.ctime_nsec(),
))
.map_err(|_| fail("executable identity"));
#[cfg(windows)]
{
use std::os::windows::fs::MetadataExt;
let file = hiroute_platform::windows::security::open_identity(&path, false)
.map_err(|_| fail("executable identity"))?;
let identity = hiroute_platform::windows::security::file_identity(&file)
.map_err(|_| fail("executable identity"))?;
CanonicalDigest::of(&(
path,
identity,
meta.file_size(),
meta.creation_time(),
meta.last_write_time(),
))
.map_err(|_| fail("executable identity"))
}
}
pub(super) fn cache_error() -> NativeIngressProbeError {
fail("native evidence cache")
}
#[cfg(all(test, unix))]
mod tests {
use super::*;
#[test]
fn isolated_native_probe_keeps_the_selected_npm_runtime_path() {
use std::os::unix::fs::PermissionsExt;
let root = tempfile::tempdir().unwrap();
let node = root.path().join("node");
fs::write(&node, "#!/bin/sh\necho selected-runtime\n").unwrap();
fs::set_permissions(&node, fs::Permissions::from_mode(0o700)).unwrap();
let wrapper = root.path().join("codex");
fs::write(&wrapper, "#!/usr/bin/env node\nfixture wrapper body\n").unwrap();
fs::set_permissions(&wrapper, fs::Permissions::from_mode(0o700)).unwrap();
let supplied = std::env::join_paths([
std::path::Path::new("."),
root.path(),
std::path::Path::new("relative/bin"),
])
.unwrap();
let selected_path = probe_path(Some(&supplied));
assert!(std::env::split_paths(&selected_path).all(|path| path.is_absolute()));
let output = Command::new(wrapper)
.env_clear()
.env("PATH", selected_path)
.current_dir(root.path())
.output()
.unwrap();
assert!(output.status.success());
assert!(
String::from_utf8(output.stdout)
.unwrap()
.starts_with("selected-runtime")
);
assert_eq!(probe_path(None), std::ffi::OsString::from("/usr/bin:/bin"));
}
use hiroute_domain::{ConnectorRegistryBundleV1, ReleaseModelDataBundleV2};
use std::os::unix::fs::PermissionsExt;
#[test]
fn native_evidence_expires_but_does_not_gate_on_codex_binary_identity() {
let root = tempfile::tempdir().unwrap();
fs::set_permissions(root.path(), fs::Permissions::from_mode(0o700)).unwrap();
let binary = root.path().join("codex");
fs::write(&binary, b"trusted fixture identity, never executed").unwrap();
fs::set_permissions(&binary, fs::Permissions::from_mode(0o700)).unwrap();
let proof = CodexIngressEvidence {
observed: Instant::now(),
observed_at: now(),
collaboration: false,
};
let sample = || {
let super::super::AgentDiscoveryOutcomeV1::Supported { mut installation } =
super::super::resolve_agent_observation(super::super::AgentScanObservationV1 {
schema: super::super::AGENT_SCAN_OBSERVATION_SCHEMA_V1.into(),
agent_id: "agent.codex".into(),
kind: hiroute_domain::AgentKindV1::Codex,
version: "future-build".into(),
config: vec![],
})
else {
panic!("fixture installation");
};
super::super::observed_capabilities::attach_target_file_capabilities(
&mut installation,
&root.path().join("config.toml"),
);
installation
};
let mut fresh = sample();
proof.attach(&mut fresh);
assert!(
fresh
.require_action(hiroute_domain::AgentAction::ConfigureModel)
.is_ok()
);
let mut expired = proof.clone();
expired.observed = Instant::now() - Duration::from_secs(301);
let mut without_fresh_proof = sample();
expired.attach(&mut without_fresh_proof);
assert!(
without_fresh_proof
.require_action(hiroute_domain::AgentAction::ConfigureModel)
.is_err()
);
fs::rename(&binary, root.path().join("old-codex")).unwrap();
fs::write(&binary, b"replacement fixture identity, never executed").unwrap();
fs::set_permissions(&binary, fs::Permissions::from_mode(0o700)).unwrap();
let mut replaced = sample();
proof.attach(&mut replaced);
assert!(
replaced
.require_action(hiroute_domain::AgentAction::ConfigureModel)
.is_ok()
);
}
#[test]
fn collaboration_settings_consume_only_an_explicit_collaboration_check() {
let root = tempfile::tempdir().unwrap();
fs::set_permissions(root.path(), fs::Permissions::from_mode(0o700)).unwrap();
let home = root.path().join("home");
let config_dir = home.join(".codex");
fs::create_dir_all(&config_dir).unwrap();
fs::set_permissions(&home, fs::Permissions::from_mode(0o700)).unwrap();
fs::set_permissions(&config_dir, fs::Permissions::from_mode(0o700)).unwrap();
let config = config_dir.join("config.toml");
fs::write(&config, b"# private fixture\n").unwrap();
fs::set_permissions(&config, fs::Permissions::from_mode(0o600)).unwrap();
let binary = root.path().join("codex");
fs::write(&binary, b"#!/bin/sh\nprintf 'codex-cli 99.99.99\\n'\n").unwrap();
fs::set_permissions(&binary, fs::Permissions::from_mode(0o700)).unwrap();
let mut layout = super::super::AgentFilesystemLayoutV1::from_process(&home, root.path());
layout.codex_user_config = config;
layout.codex_executable = binary;
layout.codex_desktop_executable = None;
let registry: ConnectorRegistryBundleV1 = serde_json::from_slice(include_bytes!(
"../../../../assets/connector-registry/current/registry-seed.json"
))
.unwrap();
let models: ReleaseModelDataBundleV2 = serde_json::from_slice(include_bytes!(
"../../../../assets/release-facts/current/bundle/model-data.json"
))
.unwrap();
let registry = super::super::ClaudeRegistrationIndexV1::from_verified_model_data(
®istry,
&models.data,
)
.unwrap();
let scanner = super::super::FilesystemAgentScannerV1::new(layout.clone(), registry.clone())
.with_codex_ingress_evidence(CodexIngressEvidence {
observed: Instant::now(),
observed_at: now(),
collaboration: true,
});
let supported = |discovery: super::super::FilesystemAgentDiscoveryV1| {
let super::super::AgentDiscoveryOutcomeV1::Supported { installation } =
discovery.outcome
else {
panic!("supported Codex fixture");
};
installation
};
let model_only = supported(scanner.codex_settings_discovery(false));
let collaboration = supported(scanner.codex_settings_discovery(true));
assert!(
model_only
.require_action(hiroute_domain::AgentAction::InstallCollaborationSkill)
.is_err()
);
assert!(
collaboration
.require_action(hiroute_domain::AgentAction::InstallCollaborationSkill)
.is_ok()
);
assert_ne!(
model_only.observation_digest,
collaboration.observation_digest
);
let auth_only = super::super::FilesystemAgentScannerV1::new(layout, registry)
.with_codex_ingress_evidence(CodexIngressEvidence {
observed: Instant::now(),
observed_at: now(),
collaboration: false,
});
assert!(
supported(auth_only.codex_settings_discovery(true))
.require_action(hiroute_domain::AgentAction::InstallCollaborationSkill)
.is_err()
);
}
}