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
//! Staged, pre-promotion CLI codecs for the Gateway-unbound Compute/Routing slice.
//!
//! This module owns no discovery, persistence, or routing behavior. It accepts only the exact
//! typed Local Control request DTOs and leaves the public generated command manifest unchanged.
#[cfg(test)]
use std::io::Read;
use hiroute_application_api::{
AgentConnectionApplyRequestV1, AgentConnectionPreviewRequestV1, ApplyPriceOverrideChangeV2,
ApplyRequestV1, COMPUTE_MANAGEMENT_CHANGE_SCHEMA_V2, ComputeConnectionApplyRequestV1,
ComputeConnectionAuthorizationRequestV1, ComputeConnectionOptionsRequestV1,
ComputeConnectionPreviewRequestV1, ComputeConnectionTestRequestV1, ComputeManagementQueryV2,
ComputeSavePreviewRequestV2, ComputeScanRequestV1, ComputeSubscriptionCheckPreviewRequestV2,
ErrorCode, GetEffectivePricesV2, PreviewPriceOverrideChangeV2, PreviewRequestV1,
};
#[cfg(test)]
use hiroute_application_api::{CommandDescriptorV1, command_by_id};
use serde::{Serialize, de::DeserializeOwned};
use serde_json::Value;
#[cfg(test)]
const TYPED_CONTROL_IDS: [&str; 16] = [
"models.show",
"prices.effective",
"prices.override.preview",
"prices.override.apply",
"compute.scan",
"compute.connection.options",
"compute.connection.preview",
"compute.connection.apply",
"compute.credential.add",
"routing.preview",
"routing.apply",
"agents.connect.preview",
"agents.connect.apply",
"agents.connect.status",
"agents.restore.preview",
"agents.restore.apply",
];
use crate::request_input::{self, MAX_REQUEST_BYTES};
#[cfg(test)]
pub(crate) fn typed_control_commands() -> impl Iterator<Item = CommandDescriptorV1> {
TYPED_CONTROL_IDS
.into_iter()
.map(|id| command_by_id(id).expect("staged control-plane descriptor exists"))
}
pub(crate) fn accepts_capability(command_id: &str) -> bool {
matches!(
command_id,
"sessions.list"
| "sessions.show"
| "sessions.receipt"
| "sessions.status"
| "value.show"
| "observation.plan-quality.samples"
| "observation.plan-trust"
| "observation.plan-trust.replay"
| "observation.plan-trust.suggestions"
)
}
pub(crate) fn command_payload(
command_id: &str,
options: &[String],
) -> Option<Result<Value, ErrorCode>> {
match command_id {
"decision.services.list" => Some(empty::<hiroute_application_api::ClientEmptyRequestV1>(
options,
)),
"decision.services.apply" => Some(preview_or_apply(options)),
"decision.services.test" => Some(classifier_request(options)),
"models.feed.status" | "models.feed.refresh" | "models.availability" => {
Some(empty::<hiroute_application_api::ClientEmptyRequestV1>(
options,
))
}
"models.feed.remove.preview" => Some(if options.is_empty() {
empty::<hiroute_application_api::ModelFeedRemovalQueryV2>(options)
} else {
request::<hiroute_application_api::ModelFeedRemovalQueryV2>(options)
}),
"models.feed.settings.apply" => Some(feed_settings(options)),
"models.feed.remove.apply" => {
Some(request::<hiroute_application_api::ModelFeedRemoveRequestV1>(options))
}
"agents.previous-routing.preview" => Some(request::<
hiroute_application_api::AgentPreviousRoutingQueryV1,
>(options)),
"compute.defaults.get" => Some(request::<hiroute_application_api::ComputeDefaultsQueryV1>(
options,
)),
"compute.defaults.preview" => Some(request::<
hiroute_application_api::ComputeSavePreviewRequestV3,
>(options)),
"models.metadata.list" => Some(if options.is_empty() {
empty::<hiroute_application_api::ListModelMetadataV1>(options)
} else {
request::<hiroute_application_api::ListModelMetadataV1>(options)
}),
"models.metadata.get" => Some(request::<hiroute_application_api::GetModelMetadataV1>(
options,
)),
"models.show" => Some(request::<hiroute_application_api::ModelCatalogQueryV1>(
options,
)),
"prices.effective" => Some(request::<GetEffectivePricesV2>(options)),
"prices.override.preview" => Some(request::<PreviewPriceOverrideChangeV2>(options)),
"prices.override.apply" => Some(request::<ApplyPriceOverrideChangeV2>(options)),
"compute.scan" => Some(if options.is_empty() {
empty::<ComputeScanRequestV1>(options)
} else {
compute_scan(options)
}),
"compute.list" => Some(empty::<ComputeManagementQueryV2>(options)),
"compute.show" => Some(positional(options, |source_id| ComputeManagementQueryV2 {
source_id: Some(source_id),
})),
"compute.connection.prepare" => Some(request::<
hiroute_application_api::PrepareDiscoveredModelConnectionRequestV1,
>(options)),
"compute.connection.options" => Some(if options.is_empty() {
empty::<ComputeConnectionOptionsRequestV1>(options)
} else {
request::<ComputeConnectionOptionsRequestV1>(options)
}),
"compute.connection.preview" => Some(compute_preview(options)),
"compute.connection.apply" => Some(request::<ComputeConnectionApplyRequestV1>(options)),
"compute.connection.authorize" => {
Some(request::<ComputeConnectionAuthorizationRequestV1>(options))
}
"compute.connection.login" => Some(request::<
hiroute_application_api::ComputeSubscriptionLoginRequestV1,
>(options)),
"compute.connection.test" => Some(request::<ComputeConnectionTestRequestV1>(options)),
"compute.credential.add" => Some(preview_or_apply(options)),
"routing.list" if !options.is_empty() => Some(request::<
hiroute_application_api::AgentPlanCatalogQueryV2,
>(options)),
"routing.preview" => Some(routing_request(options, false)),
"routing.apply" => Some(routing_request(options, true)),
"agents.connect.preview" => Some(agent_request(options, false)),
"routing.options" => {
Some(request::<hiroute_application_api::PlanEditorOptionsRequestV1>(options))
}
"agents.connect.apply" => Some(agent_request(options, true)),
"agents.restore.preview" => Some(agent_restore_request(options, false)),
"agents.restore.apply" => Some(agent_restore_request(options, true)),
"agents.connect.status" => Some(crate::effective_status::payload(options)),
_ => None,
}
}
fn compute_preview(options: &[String]) -> Result<Value, ErrorCode> {
let value = request_input::read(options, MAX_REQUEST_BYTES)?;
if value
.get("change")
.and_then(|change| change.get("schema"))
.and_then(Value::as_str)
== Some(COMPUTE_MANAGEMENT_CHANGE_SCHEMA_V2)
{
return typed_value::<ComputeSavePreviewRequestV2>(value);
}
if value.get("candidate").is_some() {
return typed_value::<ComputeSubscriptionCheckPreviewRequestV2>(value);
}
typed_value::<ComputeConnectionPreviewRequestV1>(value)
}
fn typed_value<T: DeserializeOwned + Serialize>(value: Value) -> Result<Value, ErrorCode> {
let request: T = request_input::deserialize(value)?;
serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
}
fn classifier_request(options: &[String]) -> Result<Value, ErrorCode> {
classifier_value(request_input::read(options, MAX_REQUEST_BYTES)?)
}
fn classifier_value(value: Value) -> Result<Value, ErrorCode> {
match value.get("schema").and_then(Value::as_str) {
Some(hiroute_application_api::HISTORICAL_APPLICABILITY_TEST_SCHEMA_V1) => {
typed_value::<hiroute_application_api::HistoricalApplicabilityTestRequestV1>(value)
}
_ => typed_value::<hiroute_application_api::ClassifierDecisionTestRequestV1>(value),
}
}
fn compute_scan(options: &[String]) -> Result<Value, ErrorCode> {
let value = request_input::read(options, MAX_REQUEST_BYTES)?;
if value.get("schema").is_some() {
let parsed: hiroute_application_api::ComputeScanRequestV2 =
request_input::deserialize(value)?;
if !parsed.valid() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(parsed).map_err(|_| ErrorCode::Internal)
} else {
typed_value::<ComputeScanRequestV1>(value)
}
}
fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
let value = request_input::read(options, MAX_REQUEST_BYTES)?;
if value.get("change").is_none() {
request_input::diagnostics::record(
"missing_field",
"$.change",
"a change object inside the Preview/Apply request wrapper",
);
return Err(ErrorCode::InvalidArguments);
}
if value
.get("change")
.and_then(|c| c.get("schema"))
.and_then(Value::as_str)
== Some(hiroute_application_api::PUBLICATION_CHECKPOINT_CHANGE_SCHEMA_V1)
{
return if apply {
typed_value::<hiroute_application_api::PublicationCheckpointApplyRequestV1>(value)
} else {
typed_value::<hiroute_application_api::PublicationCheckpointPreviewRequestV1>(value)
};
}
if value
.get("change")
.and_then(|c| c.get("schema"))
.and_then(Value::as_str)
== Some(hiroute_application_api::PLAN_LIFECYCLE_CHANGE_SCHEMA_V1)
{
return if apply {
typed_value::<hiroute_application_api::PlanLifecycleApplyRequestV1>(value)
} else {
typed_value::<hiroute_application_api::PlanLifecyclePreviewRequestV1>(value)
};
}
if value
.get("change")
.and_then(|c| c.get("schema"))
.and_then(Value::as_str)
== Some(hiroute_application_api::PLAN_DRAFT_CHANGE_SCHEMA_V1)
{
return if apply {
typed_value::<hiroute_application_api::PlanDraftApplyRequestV1>(value)
} else {
typed_value::<hiroute_application_api::PlanDraftPreviewRequestV1>(value)
};
}
if value
.get("change")
.and_then(|change| change.get("schema"))
.and_then(Value::as_str)
!= Some(hiroute_application_api::PLAN_CONTENT_CHANGE_SCHEMA_V2)
{
return Err(ErrorCode::InvalidArguments);
}
if apply {
typed_value::<hiroute_application_api::PlanContentApplyRequestV2>(value)
} else {
typed_value::<hiroute_application_api::PlanContentPreviewRequestV2>(value)
}
}
fn agent_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
validate_agent_request(request_input::read(options, MAX_REQUEST_BYTES)?, apply)
}
fn agent_restore_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
validate_restore_request(request_input::read(options, MAX_REQUEST_BYTES)?, apply)
}
fn validate_restore_request(value: Value, apply: bool) -> Result<Value, ErrorCode> {
let value = validate_agent_request(value, apply)?;
let spec: hiroute_application_api::AgentSettingsSpecV2 =
request_input::deserialize(value["spec"].clone())?;
if spec.schema_version != hiroute_application_api::AGENT_SETTINGS_SCHEMA_V2
|| !spec.is_restore_only()
{
return Err(ErrorCode::InvalidArguments);
}
Ok(value)
}
fn validate_agent_request(value: Value, apply: bool) -> Result<Value, ErrorCode> {
let v2 = value["spec"]["schema_version"]["major"] == 2;
let valid =
match (v2, apply) {
(true, true) => request_input::deserialize::<
hiroute_application_api::AgentSettingsApplyV2,
>(value.clone())
.is_ok(),
(true, false) => request_input::deserialize::<
hiroute_application_api::AgentSettingsPreviewRequestV2,
>(value.clone())
.is_ok(),
(false, true) => {
request_input::deserialize::<AgentConnectionApplyRequestV1>(value.clone()).is_ok()
}
(false, false) => {
request_input::deserialize::<AgentConnectionPreviewRequestV1>(value.clone()).is_ok()
}
};
if valid {
Ok(value)
} else {
Err(ErrorCode::InvalidArguments)
}
}
fn preview_or_apply(options: &[String]) -> Result<Value, ErrorCode> {
let value = request_input::read(options, MAX_REQUEST_BYTES)?;
let keys = value
.as_object()
.ok_or(ErrorCode::InvalidArguments)?
.keys()
.map(String::as_str)
.collect::<std::collections::BTreeSet<_>>();
let preview_keys = ["schema_version", "spec"].into_iter().collect();
let apply_keys = [
"schema_version",
"spec",
"accept_digest",
"expected_revisions",
"idempotency_key",
]
.into_iter()
.collect();
if keys == preview_keys {
request_input::deserialize::<PreviewRequestV1>(value.clone())?;
} else if keys == apply_keys {
let apply = request_input::deserialize::<ApplyRequestV1>(value.clone())?;
if apply.apply_capability.is_some() || apply.idempotency_key.is_empty() {
return Err(ErrorCode::InvalidArguments);
}
} else {
return Err(ErrorCode::InvalidArguments);
}
Ok(value)
}
fn positional<T>(options: &[String], build: impl FnOnce(String) -> T) -> Result<Value, ErrorCode>
where
T: Serialize,
{
let [value] = options else {
return Err(ErrorCode::InvalidArguments);
};
if !request_input::valid_positional(value) {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(build(value.clone())).map_err(|_| ErrorCode::Internal)
}
fn feed_settings(options: &[String]) -> Result<Value, ErrorCode> {
if options.len() == 2 && options[0] == "--retrieval" {
let enabled = match options[1].as_str() {
"on" => true,
"off" => false,
_ => return Err(ErrorCode::InvalidArguments),
};
return serde_json::to_value(hiroute_application_api::ModelFeedSettingsRequestV1 {
retrieval_enabled: Some(enabled),
acknowledge_disclosure: None,
})
.map_err(|_| ErrorCode::Internal);
}
request::<hiroute_application_api::ModelFeedSettingsRequestV1>(options)
}
fn empty<T>(options: &[String]) -> Result<Value, ErrorCode>
where
T: Default + Serialize,
{
if !options.is_empty() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(T::default()).map_err(|_| ErrorCode::Internal)
}
fn request<T>(options: &[String]) -> Result<Value, ErrorCode>
where
T: DeserializeOwned + Serialize,
{
request_input::typed::<T>(options, MAX_REQUEST_BYTES)
}
#[cfg(test)]
fn typed_request<T>(reader: impl Read) -> Result<Value, ErrorCode>
where
T: DeserializeOwned + Serialize,
{
typed_value::<T>(request_input::read_json(reader, MAX_REQUEST_BYTES)?)
}
#[cfg(test)]
mod tests {
use hiroute_application_api::{
COMPUTE_CONNECTION_CHANGE_SCHEMA_V1, ComputeConnectionChangeV1,
ComputeConnectionPreviewRequestV1,
};
use super::*;
#[test]
fn control_plane_owns_the_sixteen_exact_typed_descriptors() {
let commands = typed_control_commands().collect::<Vec<_>>();
assert_eq!(commands.len(), 16);
assert_eq!(
commands
.iter()
.map(|command| command.command_id.as_str())
.collect::<Vec<_>>(),
TYPED_CONTROL_IDS
);
}
#[test]
fn control_plane_typed_codec_rejects_unknown_fields() {
let request = ComputeConnectionPreviewRequestV1 {
change: ComputeConnectionChangeV1 {
schema: COMPUTE_CONNECTION_CHANGE_SCHEMA_V1.into(),
discovered_source_ref: "discovered.fixture".into(),
connection_option_id: "option.fixture".into(),
model_configuration_id: "model.fixture".into(),
expected_source_revision: 0,
expected_binding_revision: 0,
expected_inventory_revision: 0,
explicit_materialization: true,
},
};
let bytes = serde_json::to_vec(&request).unwrap();
assert_eq!(
typed_request::<ComputeConnectionPreviewRequestV1>(bytes.as_slice()).unwrap(),
serde_json::to_value(request).unwrap()
);
assert_eq!(
typed_request::<ComputeConnectionPreviewRequestV1>(
br#"{"change":{"schema":"hiroute.compute-connection-change/v1","discovered_source_ref":"x","connection_option_id":"y","model_configuration_id":"z","expected_source_revision":0,"expected_binding_revision":0,"expected_inventory_revision":0,"explicit_materialization":true},"secret":"forbidden"}"#.as_slice(),
)
.unwrap_err(),
ErrorCode::InvalidArguments
);
}
#[test]
fn local_configuration_apply_needs_no_capability_channel() {
assert!(!accepts_capability("compute.connection.login"));
assert!(!accepts_capability("compute.connection.apply"));
assert!(!accepts_capability("compute.credential.add"));
assert!(!accepts_capability("routing.apply"));
assert!(!accepts_capability("agents.connect.apply"));
assert!(!accepts_capability("agents.restore.apply"));
assert!(!accepts_capability("agents.restore.preview"));
assert!(!accepts_capability("compute.connection.preview"));
assert!(!accepts_capability("routing.preview"));
assert!(!accepts_capability("prices.override.apply"));
assert!(!accepts_capability("prices.override.preview"));
assert!(!accepts_capability("prices.effective"));
assert!(!accepts_capability("models.show"));
assert!(accepts_capability("sessions.list"));
}
#[test]
fn subscription_login_codec_rejects_callback_secrets_but_preserves_protected_references() {
use hiroute_application_api::ComputeSubscriptionLoginRequestV1;
let value = serde_json::json!({"action":"callback","login_ref":"login/one",
"input_candidate":{"candidate_ref":"candidate/subscription-login/one","candidate_revision":1}});
let encoded = serde_json::to_vec(&value).unwrap();
assert_eq!(
typed_request::<ComputeSubscriptionLoginRequestV1>(encoded.as_slice()).unwrap(),
value
);
let mut with_secret = value;
with_secret["callback_url"] = serde_json::json!("callback-secret-must-not-be-forwarded");
let encoded = serde_json::to_vec(&with_secret).unwrap();
assert_eq!(
typed_request::<ComputeSubscriptionLoginRequestV1>(encoded.as_slice()).unwrap_err(),
ErrorCode::InvalidArguments
);
assert_eq!(
command_payload(
"compute.connection.login",
&["--code".into(), "forbidden".into()]
)
.unwrap()
.unwrap_err(),
ErrorCode::InvalidArguments
);
}
}
#[cfg(test)]
mod agent_settings_codec_tests {
use super::*;
use serde_json::json;
#[test]
fn v2_settings_codec_preserves_schema_and_rejects_untyped_authority() {
let spec = json!({"schema_version":{"major":2,"minor":0},"context_id":"agent-context/codex/test",
"model":{"intent":"restore","restore_point_ref":"model-restore/original"}});
let preview = json!({"spec":spec});
assert_eq!(
validate_agent_request(preview.clone(), false).unwrap(),
preview
);
assert_eq!(
validate_restore_request(preview.clone(), false).unwrap(),
preview
);
let mut no_restore = preview.clone();
no_restore["spec"]["model"] = json!({"intent":"keep"});
assert!(validate_restore_request(no_restore, false).is_err());
let digest = hiroute_application_api::CanonicalDigest::of_bytes(b"codec");
let apply = json!({"spec":spec,"accept_digest":digest,"dependency_digest":digest,
"expected_revisions":{"target":0,"dependencies":{}},"idempotency_key":"settings-codec"});
assert_eq!(validate_agent_request(apply.clone(), true).unwrap(), apply);
let mut injected = apply.clone();
injected["apply_capability"] = json!("forbidden-in-ordinary-stdin");
assert!(validate_agent_request(injected, true).is_err());
let mut missing = apply;
missing
.as_object_mut()
.unwrap()
.remove("expected_revisions");
assert!(validate_agent_request(missing, true).is_err());
let mut unknown = preview;
unknown["spec"]["schema_version"]["major"] = json!(3);
assert!(validate_agent_request(unknown, false).is_err());
}
}
#[cfg(test)]
mod classifier_codec_tests {
use super::*;
use hiroute_domain::*;
use serde_json::json;
#[test]
fn explicit_c_request_reaches_control_while_v1_stays_unchanged() {
let legacy = json!({"schema":"hiroute.classifier-decision-test/v1","classifier":{"kind":"local_rules"}});
assert_eq!(classifier_value(legacy.clone()).unwrap(), legacy);
let protocol = NativeProtocolV1::default();
let mut judgment = JudgmentSettingsV1::default();
protocol.stock_assessment(&mut judgment);
let frozen = FrozenNativeProtocolV1::freeze(
&protocol,
judgment.degree.definition().into(),
[(SMART_SAVING_SCOPE_ID.into(), judgment)],
)
.unwrap();
let request = json!({"schema":"hiroute.historical-applicability-test/v1","service_id":"saved-fixture","service_revision":7,"shape":"standard","protocol":frozen});
assert_eq!(classifier_value(request.clone()).unwrap(), request);
let mut injected = request.clone();
injected["state"] = json!("verified");
assert_eq!(classifier_value(injected), Err(ErrorCode::InvalidArguments));
let mut unknown = request;
unknown["schema"] = json!("unknown");
assert_eq!(classifier_value(unknown), Err(ErrorCode::InvalidArguments));
}
#[test]
fn maximum_c_shape_preserves_all_nested_degree_definitions() {
let protocol = NativeProtocolV1::default();
let mut judgment = JudgmentSettingsV1::default();
protocol.stock_assessment(&mut judgment);
let options = (0..16)
.map(|i| CategoryOptionV1 {
id: format!("category-{i}"),
criterion: format!("Synthetic category {i}"),
refinement: Some(judgment.degree.definition()),
})
.collect::<Vec<_>>();
let frozen = FrozenNativeProtocolV1::freeze(
&protocol,
DecisionDefinitionV1::Categorical {
instructions: "Select the current task category".into(),
options: options.clone(),
},
options.into_iter().map(|o| (o.id, judgment.clone())),
)
.unwrap();
let request = json!({"schema":"hiroute.historical-applicability-test/v1","service_id":"saved-fixture","service_revision":7,"shape":"max_branches","protocol":frozen});
let decoded: hiroute_application_api::HistoricalApplicabilityTestRequestV1 =
serde_json::from_value(request.clone()).unwrap();
assert!(decoded.validate());
assert_eq!(classifier_value(request.clone()).unwrap(), request);
}
}