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 run materials and task-owned metadata. Borrowed native roots are never owned here.
use super::*;
use hiroute_domain::delegation::{
DELEGATION_NATIVE_ROOT_MARKER_FILE_V1, DelegationNativeFilesystemIdentityV1,
DelegationNativeRootMarkerV1, DelegationNativeRootV1, valid_native_history_path,
};
use hiroute_domain::{CanonicalDigest, WorkspaceId};
use std::fs;
use std::path::Component;
#[path = "native_history.rs"]
mod history;
pub use history::BorrowedNativeContext;
/// Paths relative to a NEW private_root. The launcher creates/protects only this collection
/// and its root. It must reject existing roots, traversal, links and unknown ownership.
/// Do not derive additional directories or cleanup targets by inspecting env/session_meta.
pub struct RunMaterials {
pub directories: Vec<PathBuf>,
pub files: Vec<RunMaterialFile>,
}
/// Already rendered by 20; the launcher applies 0700 to executables and 0600 to other files.
/// No template substitutions or secret logs are allowed during materialization.
pub struct RunMaterialFile {
pub relative_path: PathBuf,
pub contents: Zeroizing<Vec<u8>>,
pub executable: bool,
}
/// Prepared by 20, never created or removed by 18. No run token is stored by this helper.
/// Re-derive using the persisted task/workspace/Harness identity, never Plan or run identity.
pub struct TaskSessionRoot {
path: PathBuf,
harness: WorkerHarnessV1,
workspace_root_identity: String,
newly_created: bool,
}
pub enum SessionRootUse<'a> {
New,
/// The existing native-cache/body inventory supplies exact required relative files.
/// This existence check does not replace current content authorization/retention checks.
Continue {
required_history: &'a [PathBuf],
},
}
impl TaskSessionRoot {
pub fn prepare(
session_base: &Path,
workspace: &WorkspaceId,
workspace_root_identity: &str,
task_id: &str,
harness: WorkerHarnessV1,
usage: SessionRootUse<'_>,
) -> Result<Self, DelegationErrorV1> {
use hiroute_domain::delegation::valid_delegation_id;
if WorkspaceId::parse(workspace.as_str()).is_err()
|| !valid_delegation_id(task_id)
|| !valid_delegation_id(workspace_root_identity)
{
return Err(DelegationErrorV1::InvalidArguments);
}
let base = checked_directory(session_base)?;
let digest = CanonicalDigest::of(&json!([
"delegation-native-root-v1",
workspace,
workspace_root_identity,
task_id,
harness
]))
.map_err(|_| DelegationErrorV1::InvalidArguments)?;
let path = base.join(digest.as_str().trim_start_matches("sha256:"));
let newly_created = matches!(usage, SessionRootUse::New);
match usage {
SessionRootUse::New => {
// Never reuse or change permissions on an unknown task directory.
hiroute_platform::private_fs::create_directory(&path)
.map_err(|_| DelegationErrorV1::Conflict)?;
}
SessionRootUse::Continue { required_history } => {
checked_directory(&path).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if required_history.is_empty() || required_history.len() > 256 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
for relative in required_history {
check_history(&path, relative)?;
}
history::verify_continuation_materials(&path, harness, required_history)?;
}
}
let actual = checked_directory(&path)?;
if actual.parent() != Some(base.as_path()) {
return Err(DelegationErrorV1::PermissionDenied);
}
Ok(Self {
path: actual,
harness,
workspace_root_identity: workspace_root_identity.to_owned(),
newly_created,
})
}
pub(super) fn check_binding(
&self,
harness: WorkerHarnessV1,
root: &str,
) -> Result<(), DelegationErrorV1> {
if self.harness != harness || self.workspace_root_identity != root {
return Err(DelegationErrorV1::InvalidArguments);
}
Ok(())
}
pub fn path(&self) -> &Path {
&self.path
}
/// Publish a root marker before the runtime store records this generation as ready. The
/// marker is evidence for the already-derived task root only; it never authorizes adoption of
/// an existing directory.
pub(crate) fn create_ownership_marker(
&self,
session_base: &Path,
root: &DelegationNativeRootV1,
) -> Result<DelegationNativeFilesystemIdentityV1, DelegationErrorV1> {
self.check_root_record(session_base, root, false)?;
let marker = serde_json::to_vec(&root.ownership_marker())
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
let path = self.path.join(DELEGATION_NATIVE_ROOT_MARKER_FILE_V1);
hiroute_platform::durable::write_private_new(&path, &marker)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
#[cfg(unix)]
hiroute_platform::durable::directory_barrier(&self.path)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
let file = open_marker(&path)?;
filesystem_identity(session_base, &self.path, &file)
}
pub(crate) fn verify_ownership(
&self,
session_base: &Path,
root: &DelegationNativeRootV1,
) -> Result<DelegationNativeFilesystemIdentityV1, DelegationErrorV1> {
self.check_root_record(session_base, root, true)?;
let marker_path = self.path.join(DELEGATION_NATIVE_ROOT_MARKER_FILE_V1);
let path_metadata =
fs::symlink_metadata(&marker_path).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if linked(&path_metadata) || !path_metadata.is_file() || path_metadata.len() > 4096 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let file = open_marker(&marker_path)?;
#[cfg(windows)]
{
use hiroute_platform::windows::security::{file_link_count, verify_owner_only_handle};
verify_owner_only_handle(&file, false)
.map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if file_link_count(&file).map_err(|_| DelegationErrorV1::ResumeUnavailable)? != 1 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
}
let metadata = file
.metadata()
.map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if linked(&metadata) || !metadata.is_file() || metadata.len() > 4096 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
use std::io::Read;
let mut bytes = Vec::with_capacity(metadata.len() as usize);
(&file)
.take(4097)
.read_to_end(&mut bytes)
.map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if bytes.len() > 4096 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let actual: DelegationNativeRootMarkerV1 =
serde_json::from_slice(&bytes).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if actual != root.ownership_marker() {
return Err(DelegationErrorV1::ResumeUnavailable);
}
filesystem_identity(session_base, &self.path, &file)
.map_err(|_| DelegationErrorV1::ResumeUnavailable)
}
fn check_root_record(
&self,
session_base: &Path,
root: &DelegationNativeRootV1,
continuing: bool,
) -> Result<(), DelegationErrorV1> {
root.validate()?;
self.check_binding(root.harness, &root.workspace_root_identity)?;
let base = checked_directory(session_base)?;
let same_managed_base = if continuing {
#[cfg(windows)]
{
root.managed_base_path.as_deref().is_some_and(|recorded| {
super::native_context::same_windows_directory(Path::new(recorded), &base)
.unwrap_or(false)
})
}
#[cfg(not(windows))]
{
root.managed_base_path.as_deref() == Some(base.to_string_lossy().as_ref())
}
} else {
true
};
if self.path.parent() != Some(base.as_path())
|| self.path.file_name().and_then(|name| name.to_str())
!= Some(root.relative_root.as_str())
|| !same_managed_base
{
return Err(if continuing {
DelegationErrorV1::ResumeUnavailable
} else {
DelegationErrorV1::Conflict
});
}
Ok(())
}
/// The adapter checks account/read before applying its per-session CODEX_CONFIG.
/// Bootstrap the same private provider at app-server startup, without persisting a token.
pub(super) fn prepare_codex_provider(
&self,
gateway: std::net::SocketAddr,
catalog_path: Option<&Path>,
) -> Result<(), DelegationErrorV1> {
use std::io::Read;
checked_directory(&self.path)?;
let catalog_setting = catalog_path.map_or(Ok(String::new()), |path| {
let path = path
.to_str()
.filter(|value| !value.contains(['\n', '\r', '\0']))
.ok_or(DelegationErrorV1::InvalidArguments)?;
Ok::<_, DelegationErrorV1>(format!(
"model_catalog_json = {}\n",
serde_json::to_string(path).map_err(|_| DelegationErrorV1::InvalidArguments)?
))
})?;
let contents = format!(
"model_provider = \"hiroute\"\n{catalog_setting}[model_providers.hiroute]\nname = \"HiRoute managed run\"\nbase_url = \"http://{gateway}/v1\"\nwire_api = \"responses\"\nsupports_websockets = false\nenv_key = \"HIROUTE_RUN_TOKEN\"\nrequires_openai_auth = false\n"
);
let path = self.path.join("config.toml");
match hiroute_platform::durable::write_private_new(&path, contents.as_bytes()) {
Ok(()) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
let metadata = fs::symlink_metadata(&path)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
if linked(&metadata) || !metadata.is_file() {
return Err(DelegationErrorV1::PermissionDenied);
}
let mut actual = String::new();
fs::File::open(path)
.and_then(|file| file.take(4097).read_to_string(&mut actual))
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
if actual == contents {
Ok(())
} else {
Err(DelegationErrorV1::Conflict)
}
}
Err(_) => Err(DelegationErrorV1::StorageUnavailable),
}
}
/// The task root is a private Codex target. Its catalog contains only the frozen Plan alias;
/// no user's native catalog or cache is copied into it. A Continue must see identical bytes.
pub(super) fn prepare_codex_catalog(
&self,
alias: &str,
contents: &[u8],
) -> Result<PathBuf, DelegationErrorV1> {
use std::io::Read;
checked_directory(&self.path)?;
if contents.is_empty() || contents.len() > 1024 * 1024 {
return Err(DelegationErrorV1::CapabilityUnavailable);
}
let value: Value = serde_json::from_slice(contents)
.map_err(|_| DelegationErrorV1::CapabilityUnavailable)?;
hiroute_integrations::agents::CodexCatalogSelection::for_current_adapter(value.clone())
.map_err(|_| DelegationErrorV1::CapabilityUnavailable)?;
if value["models"]
.as_array()
.is_none_or(|models| models.len() != 1 || models[0]["slug"].as_str() != Some(alias))
{
return Err(DelegationErrorV1::Conflict);
}
let path = self.path.join("worker-model-catalog.json");
match hiroute_platform::durable::write_private_new(&path, contents) {
Ok(()) => {
#[cfg(unix)]
hiroute_platform::durable::directory_barrier(&self.path)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
}
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
let metadata = fs::symlink_metadata(&path)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
if linked(&metadata) || !metadata.is_file() || metadata.len() > 1024 * 1024 {
return Err(DelegationErrorV1::PermissionDenied);
}
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
if metadata.nlink() != 1 {
return Err(DelegationErrorV1::PermissionDenied);
}
}
let mut actual = Vec::new();
let file = open_marker(&path)?;
#[cfg(windows)]
{
use hiroute_platform::windows::security::{
file_link_count, verify_owner_only_handle,
};
verify_owner_only_handle(&file, false)
.map_err(|_| DelegationErrorV1::PermissionDenied)?;
if file_link_count(&file).map_err(|_| DelegationErrorV1::PermissionDenied)? != 1
{
return Err(DelegationErrorV1::PermissionDenied);
}
}
file.take(1024 * 1024 + 1)
.read_to_end(&mut actual)
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
if actual != contents {
return Err(DelegationErrorV1::Conflict);
}
}
Err(_) => return Err(DelegationErrorV1::StorageUnavailable),
}
Ok(path)
}
}
/// Retain exact continuation evidence beneath the task-owned root. Borrowed clients retain an
/// immutable session binding, not a claim that their external history is HiRoute-owned. Claude
/// additionally requires its precise transcript; Codex session/load checks native availability.
pub(crate) fn native_history(
root: &Path,
harness: WorkerHarnessV1,
native_session_id: &str,
) -> Result<Vec<String>, DelegationErrorV1> {
if history::read_context(root, harness)?.is_some() {
return history::retain_borrowed_session(root, harness, native_session_id);
}
legacy_native_history(root, harness, native_session_id)
}
/// Registered recovery reader for pre-native-context tasks with private native storage.
fn legacy_native_history(
root: &Path,
harness: WorkerHarnessV1,
native_session_id: &str,
) -> Result<Vec<String>, DelegationErrorV1> {
// Qoder has only the borrowed-context contract, never a private legacy reader.
if matches!(
harness,
WorkerHarnessV1::QoderCli
| WorkerHarnessV1::Pi
| WorkerHarnessV1::DeepseekHarness
| WorkerHarnessV1::OpenCode
) {
return Err(DelegationErrorV1::ResumeUnavailable);
}
if native_session_id.is_empty()
|| native_session_id.len() > 256
|| native_session_id
.chars()
.any(|character| character.is_control() || matches!(character, '/' | '\\' | ':'))
{
return Err(DelegationErrorV1::ResumeUnavailable);
}
let root = fs::canonicalize(root).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
let metadata = fs::symlink_metadata(&root).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if !metadata.is_dir() || metadata.file_type().is_symlink() {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let durable_root = root.join(match harness {
WorkerHarnessV1::CodexCli => "sessions",
WorkerHarnessV1::ClaudeCode => "projects",
WorkerHarnessV1::QoderCli
| WorkerHarnessV1::Pi
| WorkerHarnessV1::DeepseekHarness
| WorkerHarnessV1::OpenCode => {
return Err(DelegationErrorV1::ResumeUnavailable);
}
});
let metadata =
fs::symlink_metadata(&durable_root).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if !metadata.is_dir() || metadata.file_type().is_symlink() {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let codex_suffix = format!("-{native_session_id}.jsonl");
let claude_name = format!("{native_session_id}.jsonl");
let mut pending = vec![durable_root];
let mut paths = Vec::new();
let mut visited = 0_usize;
while let Some(directory) = pending.pop() {
for entry in fs::read_dir(&directory).map_err(|_| DelegationErrorV1::ResumeUnavailable)? {
let entry = entry.map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
visited = visited
.checked_add(1)
.ok_or(DelegationErrorV1::ResumeUnavailable)?;
if visited > 512 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let path = entry.path();
let metadata =
fs::symlink_metadata(&path).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if metadata.file_type().is_symlink() {
return Err(DelegationErrorV1::ResumeUnavailable);
}
if metadata.is_dir() {
pending.push(path);
continue;
}
if !metadata.is_file() {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let file_name = path
.file_name()
.and_then(|value| value.to_str())
.ok_or(DelegationErrorV1::ResumeUnavailable)?;
let matches_session = match harness {
WorkerHarnessV1::CodexCli => file_name.ends_with(&codex_suffix),
WorkerHarnessV1::ClaudeCode => file_name == claude_name,
WorkerHarnessV1::QoderCli
| WorkerHarnessV1::Pi
| WorkerHarnessV1::DeepseekHarness
| WorkerHarnessV1::OpenCode => {
return Err(DelegationErrorV1::ResumeUnavailable);
}
};
if !matches_session {
continue;
}
let relative = path
.strip_prefix(&root)
.ok()
.and_then(|relative| {
relative
.components()
.map(|component| match component {
Component::Normal(value) => value.to_str(),
_ => None,
})
.collect::<Option<Vec<_>>>()
.map(|components| components.join("/"))
})
.filter(|value| valid_native_history_path(value))
.ok_or(DelegationErrorV1::ResumeUnavailable)?;
// Native separators are an OS detail; retained history uses the existing
// portable relative-path contract, including on Windows.
paths.push(relative);
}
}
paths.sort();
paths.dedup();
if paths.len() != 1 {
return Err(DelegationErrorV1::ResumeUnavailable);
}
Ok(paths)
}
pub(super) fn checked_run_root(
private_root: &Path,
session_root: &TaskSessionRoot,
) -> Result<PathBuf, DelegationErrorV1> {
let name = private_root
.file_name()
.ok_or(DelegationErrorV1::InvalidArguments)?;
if !private_root.is_absolute() || !portable_relative(Path::new(name)) {
return Err(DelegationErrorV1::InvalidArguments);
}
let parent = checked_directory(
private_root
.parent()
.ok_or(DelegationErrorV1::InvalidArguments)?,
)?;
let session = checked_directory(session_root.path())?;
// Actual filesystem-resolved component ancestry, not textual prefix comparisons. A new
// root cannot be an ancestor of an existing session directory without itself existing.
let path = parent.join(name);
if parent.starts_with(&session) || session.starts_with(&path) {
return Err(DelegationErrorV1::InvalidArguments);
}
match fs::symlink_metadata(&path) {
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(path),
_ => Err(DelegationErrorV1::Conflict),
}
}
fn check_history(root: &Path, relative: &Path) -> Result<(), DelegationErrorV1> {
if !portable_relative(relative) {
return Err(DelegationErrorV1::ResumeUnavailable);
}
let mut path = root.to_path_buf();
let components: Vec<_> = relative.components().collect();
for (index, component) in components.iter().enumerate() {
path.push(component.as_os_str());
let metadata =
fs::symlink_metadata(&path).map_err(|_| DelegationErrorV1::ResumeUnavailable)?;
if linked(&metadata)
|| (index + 1 < components.len() && !metadata.is_dir())
|| (index + 1 == components.len() && !metadata.is_file())
{
return Err(DelegationErrorV1::ResumeUnavailable);
}
}
// Existing body/native-cache ownership and deletion gates remain authoritative. Do not
// import/read history here or infer a missing session from an arbitrary newest file.
Ok(())
}
fn portable_relative(path: &Path) -> bool {
!path.as_os_str().is_empty()
&& path.components().all(|c| match c {
Component::Normal(s) => s
.to_str()
.is_some_and(|s| !s.contains(['\\', ':', '\0', '\r', '\n'])),
_ => false,
})
}
fn checked_directory(path: &Path) -> Result<PathBuf, DelegationErrorV1> {
if !path.is_absolute() {
return Err(DelegationErrorV1::InvalidArguments);
}
let metadata =
fs::symlink_metadata(path).map_err(|_| DelegationErrorV1::CapabilityUnavailable)?;
if linked(&metadata) || !metadata.is_dir() {
return Err(DelegationErrorV1::PermissionDenied);
}
#[cfg(windows)]
hiroute_platform::windows::security::verify_owner_only(path, true)
.map_err(|_| DelegationErrorV1::PermissionDenied)?;
fs::canonicalize(path)
.map(|path| super::native_context::native_path(&path))
.map_err(|_| DelegationErrorV1::CapabilityUnavailable)
}
fn linked(metadata: &fs::Metadata) -> bool {
#[cfg(windows)]
{
use std::os::windows::fs::MetadataExt;
if metadata.file_attributes() & 0x400 != 0 {
return true;
} // reparse point
}
metadata.file_type().is_symlink()
}
fn open_marker(path: &Path) -> Result<fs::File, DelegationErrorV1> {
hiroute_platform::private_fs::open_regular_file(path)
.map_err(|_| DelegationErrorV1::ResumeUnavailable)
}
fn filesystem_identity(
base: &Path,
root: &Path,
marker: &fs::File,
) -> Result<DelegationNativeFilesystemIdentityV1, DelegationErrorV1> {
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
let base = fs::metadata(base).map_err(|_| DelegationErrorV1::StorageUnavailable)?;
let root = fs::metadata(root).map_err(|_| DelegationErrorV1::StorageUnavailable)?;
let marker = marker
.metadata()
.map_err(|_| DelegationErrorV1::StorageUnavailable)?;
return Ok(DelegationNativeFilesystemIdentityV1 {
scheme: "unix-dev-inode-v1".into(),
base_device: base.dev(),
base_inode: base.ino(),
root_device: root.dev(),
root_inode: root.ino(),
marker_device: marker.dev(),
marker_inode: marker.ino(),
});
}
#[cfg(windows)]
{
use hiroute_platform::windows::security::{file_identity, open_identity};
let identity = |path| {
open_identity(path, true)
.and_then(|file| file_identity(&file))
.map_err(|_| DelegationErrorV1::StorageUnavailable)
};
let (base_device, base_inode) = identity(base)?;
let (root_device, root_inode) = identity(root)?;
let (marker_device, marker_inode) =
file_identity(marker).map_err(|_| DelegationErrorV1::StorageUnavailable)?;
return Ok(DelegationNativeFilesystemIdentityV1 {
scheme: "windows-volume-file-index-v1".into(),
base_device: u64::from(base_device),
base_inode,
root_device: u64::from(root_device),
root_inode,
marker_device: u64::from(marker_device),
marker_inode,
});
}
#[allow(unreachable_code)]
Err(DelegationErrorV1::CapabilityUnavailable)
}