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
#![forbid(unsafe_code)]
//! Shared transport and observation. All product decisions remain in the Application.
mod compute_management;
mod endpoint;
mod error;
#[cfg(any(unix, windows))]
mod frame;
mod model_catalog;
mod model_connections;
mod observation;
mod observation_queries;
mod subscriptions;
mod worker;
pub use endpoint::LocalEndpoint;
pub use error::{ClientFailure, FailureCode, SubmissionState};
pub use observation::ObservationCursor;
use hiroute_application_api::{
ClientHelloV1, ErrorCode, LOCAL_CONTROL_RELEASE_VERSION, LOCAL_CONTROL_SCHEMA_V2,
LocalControlWireRequestV2, MACHINE_ENVELOPE_SCHEMA_V2, MachineEnvelopeV2, PrincipalKind,
ServerHelloV1,
};
use hiroute_diagnostics::context::DiagnosticContext;
use hiroute_diagnostics::correlation::CorrelationDomain;
use hiroute_diagnostics::error::EventErrorCode;
use hiroute_diagnostics::event::{
ControlCallEnd, ControlClientName, ControlOperation, ControlStage, ControlStageKind,
DiagnosticEvent, SubmissionState as DiagnosticSubmissionState,
};
use serde::{Serialize, de::DeserializeOwned};
use serde_json::Value;
use std::time::Duration;
use zeroize::Zeroize;
pub trait ControlDispatch: Send + Sync {
fn dispatch(&self, request: LocalControlWireRequestV2) -> MachineEnvelopeV2<Value>;
}
#[derive(Clone)]
enum Transport {
LocalEndpoint(LocalEndpoint),
InProcess(std::sync::Arc<dyn ControlDispatch>),
}
impl std::fmt::Debug for Transport {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::LocalEndpoint(endpoint) => endpoint.fmt(f),
Self::InProcess(_) => f.write_str("InProcess"),
}
}
}
#[derive(Clone, Debug)]
pub struct Client {
transport: Transport,
name: String,
timeout: Duration,
diagnostics: Option<DiagnosticContext>,
}
// Even error/cancellation paths wipe the private wire copy. Never derive Debug for this guard.
struct PrivateRequest(LocalControlWireRequestV2);
impl Drop for PrivateRequest {
fn drop(&mut self) {
if let Some(grant) = &mut self.0.protected_grant {
grant.capability.zeroize();
}
}
}
impl Client {
pub fn new(name: impl Into<String>, endpoint: LocalEndpoint) -> Self {
Self {
transport: Transport::LocalEndpoint(endpoint),
name: name.into(),
timeout: Duration::from_secs(30),
diagnostics: None,
}
}
pub fn in_process(
name: impl Into<String>,
dispatcher: std::sync::Arc<dyn ControlDispatch>,
) -> Self {
Self {
transport: Transport::InProcess(dispatcher),
name: name.into(),
timeout: Duration::from_secs(30),
diagnostics: None,
}
}
pub fn local_endpoint(&self) -> Option<&LocalEndpoint> {
match &self.transport {
Transport::LocalEndpoint(endpoint) => Some(endpoint),
Transport::InProcess(_) => None,
}
}
pub fn with_timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
/// Attach the host's diagnostic context. The client only records bounded transport
/// stages and one call outcome per call; no wire payload ever reaches diagnostics.
pub fn with_diagnostics(mut self, context: DiagnosticContext) -> Self {
self.diagnostics = Some(context);
self
}
pub fn endpoint(&self) -> &LocalEndpoint {
self.local_endpoint()
.expect("endpoint is available only for LocalEndpoint clients")
}
pub async fn query<P: Serialize, R: DeserializeOwned>(
&self,
operation: &str,
request_id: &str,
payload: &P,
) -> Result<MachineEnvelopeV2<R>, ClientFailure> {
let request = LocalControlWireRequestV2 {
schema_version: LOCAL_CONTROL_SCHEMA_V2,
request_id: request_id.into(),
operation_id: operation.into(),
payload: serde_json::to_value(payload)
.map_err(|_| ClientFailure::before_send(FailureCode::FrameInvalid))?,
protected_grant: None,
};
self.call_typed(request).await
}
pub async fn call_typed<R: DeserializeOwned>(
&self,
request: LocalControlWireRequestV2,
) -> Result<MachineEnvelopeV2<R>, ClientFailure> {
let result = self.call_wire(request).await?;
let data = result
.data
.map(serde_json::from_value)
.transpose()
.map_err(|_| ClientFailure::at(FailureCode::FrameInvalid, true))?;
Ok(MachineEnvelopeV2 {
schema_version: result.schema_version,
request_id: result.request_id,
status: result.status,
data,
operation: result.operation,
warnings: result.warnings,
next_actions: result.next_actions,
error: result.error,
})
}
#[cfg(any(unix, windows))]
pub async fn call_wire(
&self,
request: LocalControlWireRequestV2,
) -> Result<MachineEnvelopeV2<Value>, ClientFailure> {
use tokio::io::{AsyncWriteExt, BufReader};
let started = std::time::Instant::now();
// One context per call: a busy call cannot spend another call's Debug budget.
let context = self.diagnostics.as_ref().map(|context| context.call_span());
let operation_kind = ControlOperation::from_wire(&request.operation_id);
let request_token = self.diagnostics.as_ref().and_then(|context| {
context.token(CorrelationDomain::ControlRequest, &request.request_id)
});
let stage = |kind: ControlStageKind, ok: bool, sent: bool, elapsed: std::time::Duration| {
if let Some(context) = &context {
context.emit(DiagnosticEvent::ControlStage(ControlStage {
stage: kind,
ok,
elapsed_ms: elapsed.as_millis() as u64,
sent: Some(sent),
}));
}
};
let request = PrivateRequest(request);
let mut sent = false;
let deadline = tokio::time::Instant::now()
.checked_add(self.timeout)
.ok_or_else(|| ClientFailure::before_send(FailureCode::Deadline))?;
let operation = async {
let endpoint = match &self.transport {
Transport::LocalEndpoint(endpoint) => endpoint,
Transport::InProcess(dispatcher) => {
let dispatcher = dispatcher.clone();
let request = PrivateRequest(request.0.clone());
sent = true;
return tokio::task::spawn_blocking(move || {
dispatcher.dispatch(request.0.clone())
})
.await
.map_err(|_| FailureCode::TransportUnavailable);
}
};
let step = std::time::Instant::now();
let validated = endpoint.validate_path();
stage(
ControlStageKind::EndpointValidate,
validated.is_ok(),
sent,
step.elapsed(),
);
validated?;
let step = std::time::Instant::now();
let peer = async {
if request
.0
.protected_grant
.as_ref()
.is_some_and(|g| g.principal_kind == PrincipalKind::Desktop)
&& endpoint.expected_pid.is_none()
{
return Err(FailureCode::PeerRejected);
}
let stream = endpoint.connect().await?;
endpoint.validate_peer(&stream)?;
Ok::<_, FailureCode>(stream)
};
let stream = peer.await;
stage(
ControlStageKind::PeerVerify,
stream.is_ok(),
sent,
step.elapsed(),
);
let stream = stream?;
let mut stream = BufReader::new(stream);
let step = std::time::Instant::now();
let hello = ClientHelloV1 {
api_version: LOCAL_CONTROL_SCHEMA_V2,
machine_schema_version: MACHINE_ENVELOPE_SCHEMA_V2,
client_name: self.name.clone(),
client_version: LOCAL_CONTROL_RELEASE_VERSION.into(),
};
let handshake = async {
stream
.get_mut()
.write_all(&frame::encode(&hello)?)
.await
.map_err(|_| FailureCode::TransportUnavailable)?;
let first = frame::read(&mut stream).await?;
match serde_json::from_slice::<ServerHelloV1>(&first) {
Ok(hello)
if hello.api_version == LOCAL_CONTROL_SCHEMA_V2
&& hello.machine_schema_version == MACHINE_ENVELOPE_SCHEMA_V2
&& hello.daemon_version == LOCAL_CONTROL_RELEASE_VERSION
&& hello.release_version == LOCAL_CONTROL_RELEASE_VERSION
&& hello.capabilities.iter().any(|c| c == "local-control-v2")
&& (!(request.0.operation_id == "ScanCompute"
&& request.0.payload.get("schema").and_then(Value::as_str)
== Some(
hiroute_application_api::COMPUTE_SCAN_REQUEST_SCHEMA_V2,
)
|| request.0.operation_id
== "PrepareDiscoveredModelConnection"
&& request.0.protected_grant.is_none())
|| hello
.capabilities
.iter()
.any(|c| c == "compute-discovery-points-v2"))
&& (!matches!(
request.0.operation_id.as_str(),
"GetClientServiceStatus"
| "ListAgentPlanCatalog"
| "GetAgentPlanStatus"
| "FindOperationByIdempotency"
) || hello
.capabilities
.iter()
.any(|c| c == "client-access-v1")) => {}
Ok(_) => return Err(FailureCode::SchemaIncompatible),
Err(_) => {
let rejection: MachineEnvelopeV2<Value> = serde_json::from_slice(&first)
.map_err(|_| FailureCode::FrameInvalid)?;
if rejection.schema_version != MACHINE_ENVELOPE_SCHEMA_V2
|| rejection.data.is_some()
|| rejection.operation.is_some()
|| rejection.error.as_ref().is_none_or(|e| {
!matches!(
e.code,
ErrorCode::SchemaIncompatible
| ErrorCode::MachineSchemaIncompatible
| ErrorCode::CapabilityDenied
| ErrorCode::InvalidArguments
)
})
|| rejection
.error
.as_ref()
.is_some_and(|e| rejection.status != e.code.status())
{
return Err(FailureCode::FrameInvalid);
}
#[cfg(windows)]
stream
.get_mut()
.write_all(hiroute_platform::local_record::CONTROL_ACK)
.await
.map_err(|_| FailureCode::TransportUnavailable)?;
return Ok(Some(rejection));
}
}
if !stream.buffer().is_empty() {
return Err(FailureCode::FrameInvalid);
}
Ok(None)
};
let handshake: Result<Option<MachineEnvelopeV2<Value>>, FailureCode> = handshake.await;
stage(
ControlStageKind::Hello,
handshake.is_ok(),
sent,
step.elapsed(),
);
if let Some(rejection) = handshake? {
return Ok(rejection);
}
let step = std::time::Instant::now();
let frame = match frame::encode(&request.0) {
Ok(frame) => frame,
Err(code) => {
stage(ControlStageKind::RequestWrite, false, sent, step.elapsed());
return Err(code);
}
};
sent = true; // Once a write starts, failure does not establish whether admission happened.
let written = stream.get_mut().write_all(&frame).await;
stage(
ControlStageKind::RequestWrite,
written.is_ok(),
sent,
step.elapsed(),
);
written.map_err(|_| FailureCode::TransportUnavailable)?;
let step = std::time::Instant::now();
let read = async {
let bytes = frame::read(&mut stream).await?;
if !stream.buffer().is_empty() {
return Err(FailureCode::FrameInvalid);
}
let result: MachineEnvelopeV2<Value> =
serde_json::from_slice(&bytes).map_err(|_| FailureCode::FrameInvalid)?;
if result.schema_version != MACHINE_ENVELOPE_SCHEMA_V2 {
return Err(FailureCode::SchemaIncompatible);
}
if result.request_id.as_deref() != Some(&request.0.request_id) {
return Err(FailureCode::ResponseMismatch);
}
#[cfg(windows)]
stream
.get_mut()
.write_all(hiroute_platform::local_record::CONTROL_ACK)
.await
.map_err(|_| FailureCode::TransportUnavailable)?;
Ok(result)
};
let result = read.await;
stage(
ControlStageKind::ResponseRead,
result.is_ok(),
sent,
step.elapsed(),
);
result
};
match tokio::time::timeout_at(deadline, operation).await {
Ok(Ok(result)) => {
emit_call_end(
&context,
matches!(&self.transport, Transport::InProcess(_))
.then_some(ControlClientName::Console),
operation_kind,
request_token,
DiagnosticSubmissionState::Sent,
result
.error
.as_ref()
.map(|error| category_error_code(error.category)),
started.elapsed(),
);
Ok(result)
}
Ok(Err(code)) => {
let failure = ClientFailure::at(code, sent);
emit_call_end(
&context,
matches!(&self.transport, Transport::InProcess(_))
.then_some(ControlClientName::Console),
operation_kind,
request_token,
submission_state(failure),
Some(event_error(code)),
started.elapsed(),
);
Err(failure)
}
Err(_) => {
let failure = ClientFailure::at(FailureCode::Deadline, sent);
emit_call_end(
&context,
matches!(&self.transport, Transport::InProcess(_))
.then_some(ControlClientName::Console),
operation_kind,
request_token,
submission_state(failure),
Some(EventErrorCode::Deadline),
started.elapsed(),
);
Err(failure)
}
}
}
#[cfg(not(any(unix, windows)))]
pub async fn call_wire(
&self,
request: LocalControlWireRequestV2,
) -> Result<MachineEnvelopeV2<Value>, ClientFailure> {
let _request = PrivateRequest(request);
Err(ClientFailure::before_send(FailureCode::UnsupportedPlatform))
}
}
/// Map a local client failure onto the closed event vocabulary.
impl From<FailureCode> for EventErrorCode {
fn from(code: FailureCode) -> Self {
event_error(code)
}
}
/// Map a product error category onto the closed event vocabulary. A free function because
/// both enums are foreign to this crate.
pub fn category_error_code(category: hiroute_application_api::ErrorCategory) -> EventErrorCode {
use hiroute_application_api::ErrorCategory as C;
match category {
C::Usage => EventErrorCode::Usage,
C::Conflict => EventErrorCode::Conflict,
C::Authorization => EventErrorCode::Authorization,
C::NotFound => EventErrorCode::NotFound,
C::Unavailable => EventErrorCode::Unavailable,
C::ActionRequired => EventErrorCode::ActionRequired,
C::Recovery => EventErrorCode::Recovery,
C::Internal => EventErrorCode::Internal,
}
}
fn event_error(code: FailureCode) -> EventErrorCode {
match code {
FailureCode::LocatorUnavailable => EventErrorCode::LocatorUnavailable,
FailureCode::TransportUnavailable => EventErrorCode::TransportUnavailable,
FailureCode::Deadline => EventErrorCode::Deadline,
FailureCode::PeerRejected => EventErrorCode::PeerRejected,
FailureCode::SchemaIncompatible => EventErrorCode::SchemaIncompatible,
FailureCode::FrameInvalid => EventErrorCode::FrameInvalid,
FailureCode::FrameTooLarge => EventErrorCode::FrameTooLarge,
FailureCode::ResponseMismatch => EventErrorCode::ResponseMismatch,
FailureCode::ProtectedInputUnavailable => EventErrorCode::ProtectedInputUnavailable,
FailureCode::ObservationStopped => EventErrorCode::ObservationStopped,
FailureCode::UnsupportedPlatform => EventErrorCode::UnsupportedPlatform,
}
}
/// A failure after a write started cannot establish whether admission happened, so it is
/// reported as unknown instead of claiming the request never reached the daemon.
fn submission_state(failure: ClientFailure) -> DiagnosticSubmissionState {
match failure.submission {
SubmissionState::NotSent => DiagnosticSubmissionState::NotSent,
SubmissionState::MayHaveReachedServer => DiagnosticSubmissionState::Unknown,
}
}
fn emit_call_end(
context: &Option<DiagnosticContext>,
client_name: Option<ControlClientName>,
operation: ControlOperation,
request_token: Option<hiroute_diagnostics::identity::CorrelationToken>,
submission: DiagnosticSubmissionState,
error: Option<EventErrorCode>,
elapsed: Duration,
) {
let Some(context) = context else {
return;
};
context.emit(DiagnosticEvent::ControlCallEnd(ControlCallEnd {
client_name,
operation,
request_token,
submission,
error,
elapsed_ms: elapsed.as_millis() as u64,
}));
}