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)]
//! Production `hiroute` presentation/client layer.
//!
//! Released product commands cross owner-only Local Control. This crate owns only parameter
//! parsing, output, and exit codes and depends on no Application implementation or adapter.
mod args;
mod client;
mod collaboration;
mod control_plane;
mod effective_status;
mod help;
mod host_commands;
mod managed_launch;
mod observation;
mod protected_prompt;
mod quickstart;
mod request_input;
mod routing_timeline;
mod service;
mod trust;
mod worker;
use std::ffi::OsString;
use std::io::Write;
use std::sync::atomic::{AtomicU64, Ordering};
use args::{Globals, split_globals};
pub use client::{LocalControlClient, LocalControlClientError};
use hiroute_application_api::{
AgentCheckRequestV1, AgentCheckScopeV1, AgentCheckSuiteV1, AgentLaunchDescriptorRequestV1,
CanonicalDigest, CommandDescriptorV1, CommandLifecycle, ErrorCode, ErrorV1, FallbackPolicyV1,
FreePoolModeV1, HIDDEN_AGENT_GRANT_HELPER_VERB_V1, LOCAL_CONTROL_SCHEMA_V2,
LocalControlWireRequestV2, MachineEnvelopeV2, ManagedClaudeLaunchDescriptorV2,
OperationCancelRequestV1, OperationLookupV1, PrincipalKind, ProtectedClientGrantV2,
RoutingModeV1, SetupApplyRequestV1, SetupRequestV1, SetupSelectionV1, command_by_id,
descriptor_digest, released_commands,
};
use serde::Serialize;
use serde_json::{Value, json};
static REQUEST_SEQUENCE: AtomicU64 = AtomicU64::new(1);
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct CliExecution {
pub exit_code: u8,
pub stdout: String,
pub stderr: String,
}
pub fn execute<I, S>(arguments: I) -> CliExecution
where
I: IntoIterator<Item = S>,
S: Into<OsString>,
{
let arguments = arguments
.into_iter()
.map(Into::into)
.collect::<Vec<OsString>>();
if arguments
.first()
.is_some_and(|argument| argument == "agent")
&& arguments
.get(1)
.is_some_and(|argument| argument == "launch")
{
if arguments.len() == 3
&& arguments
.get(2)
.is_some_and(|argument| argument == "--help" || argument == "-h")
{
let descriptor = command_by_id("agent.launch")
.expect("released managed-launch descriptor is registered");
return CliExecution {
exit_code: 0,
stdout: native_help_document(&descriptor),
stderr: String::new(),
};
}
return execute_managed_launch(&arguments[2..]);
}
let arguments = arguments
.into_iter()
.map(|argument| {
argument
.into_string()
.map_err(|_| ErrorCode::InvalidArguments)
})
.collect::<Result<Vec<_>, _>>();
let Ok(arguments) = arguments else {
return failure(ErrorCode::InvalidArguments, None);
};
let (path_and_options, globals) = match split_globals(arguments) {
Ok(split) => split,
Err(error) if error.worker => {
return worker::input_failure(error.code, error.globals);
}
Err(error) => return failure(error.code, error.globals.request_id),
};
if path_and_options.is_empty() {
return if globals.help {
CliExecution {
exit_code: 0,
stdout: root_help(),
stderr: String::new(),
}
} else {
failure(ErrorCode::InvalidArguments, globals.request_id)
};
}
if let Some(execution) = host_commands::execute(&path_and_options, &globals) {
return execution;
}
if let Some(execution) = collaboration::execute(&path_and_options, &globals) {
return execution;
}
if let Some(execution) = quickstart::execute(&path_and_options, &globals) {
return execution;
}
if globals.help
&& let Some(document) = help::family(&path_and_options)
{
return CliExecution {
exit_code: 0,
stdout: document,
stderr: String::new(),
};
}
let Some((descriptor, option_start)) = resolve_callable(&path_and_options) else {
return failure(ErrorCode::UnknownCommand, globals.request_id);
};
if globals.help {
return CliExecution {
exit_code: 0,
stdout: native_help_document(&descriptor),
stderr: String::new(),
};
}
let options = &path_and_options[option_start..];
if descriptor.command_id.starts_with("worker.") {
return worker::execute(&descriptor.command_id, options, globals);
}
if globals.output != args::OutputMode::Json {
return failure(ErrorCode::InvalidArguments, globals.request_id);
}
if let Some(execution) = quickstart::preview_command(&descriptor.command_id, options, &globals)
{
return execution;
}
if descriptor.command_id == "sessions.timeline" && options.iter().any(|o| o == "--follow") {
return routing_timeline::follow(options, globals);
}
match descriptor.command_id.as_str() {
"schema.list" => execute_schema_list(options, globals.request_id),
"schema.show" => execute_schema_show(options, globals.request_id),
_ => execute_control(descriptor, options, globals),
}
}
fn execute_managed_launch(arguments: &[OsString]) -> CliExecution {
let invocation = match managed_launch::parse_invocation(arguments) {
Ok(invocation) => invocation,
Err(managed_launch::ManagedLaunchFailure::AuthPrecedenceConflict) => {
return failure(ErrorCode::AgentAuthPrecedenceConflict, None);
}
Err(_) => return failure(ErrorCode::InvalidArguments, None),
};
let request_id = next_request_id();
let payload = serde_json::to_value(AgentLaunchDescriptorRequestV1 {
connection_id: invocation.connection_id.clone(),
})
.expect("managed-launch request is serializable");
let request = LocalControlWireRequestV2 {
schema_version: LOCAL_CONTROL_SCHEMA_V2,
request_id: request_id.clone(),
operation_id: "GetManagedAgentLaunchDescriptor".to_owned(),
payload,
protected_grant: None,
};
let response =
match LocalControlClient::cli_from_environment().and_then(|client| client.call(request)) {
Ok(response) => response,
Err(_) => return failure(ErrorCode::DaemonUnavailable, Some(request_id)),
};
if response.status != hiroute_application_api::MachineStatus::Succeeded {
return render(response);
}
let Some(data) = response.data.as_ref() else {
return failure(ErrorCode::DaemonUnavailable, Some(request_id));
};
let Ok(descriptor) = serde_json::from_value::<ManagedClaudeLaunchDescriptorV2>(data.clone())
else {
return failure(ErrorCode::DaemonUnavailable, Some(request_id));
};
if descriptor.connection_id != invocation.connection_id {
return failure(ErrorCode::DaemonUnavailable, Some(request_id));
}
let trusted_hiroute_executable = match current_executable() {
Ok(executable) => executable,
Err(()) => return failure(ErrorCode::DaemonUnavailable, Some(request_id)),
};
let exit_code =
match managed_launch::launch(&descriptor, &invocation, &trusted_hiroute_executable) {
Ok(exit_code) => exit_code,
Err(managed_launch::ManagedLaunchFailure::AuthPrecedenceConflict) => {
return failure(ErrorCode::AgentAuthPrecedenceConflict, Some(request_id));
}
Err(_) => return failure(ErrorCode::DaemonUnavailable, Some(request_id)),
};
let warned = response
.warnings
.iter()
.any(|warning| warning.code == "MANAGED_LAUNCH_ENV_SANITIZED")
|| descriptor
.environment_removals
.iter()
.any(|name| std::env::var_os(name).is_some());
CliExecution {
exit_code,
stdout: String::new(),
stderr: if warned {
"MANAGED_LAUNCH_ENV_SANITIZED\n".to_owned()
} else {
String::new()
},
}
}
fn current_executable() -> Result<String, ()> {
std::fs::canonicalize(std::env::current_exe().map_err(|_| ())?)
.map_err(|_| ())?
.into_os_string()
.into_string()
.map_err(|_| ())
}
fn execute_control(
descriptor: CommandDescriptorV1,
options: &[String],
globals: Globals,
) -> CliExecution {
let _diagnostics =
request_input::diagnostics::Scope::enter(&descriptor.command_id, globals.error_details);
let request_id = globals.request_id.clone().unwrap_or_else(next_request_id);
if globals.agent.is_some()
&& descriptor.command_id != "work-plans.list"
&& !descriptor.command_id.starts_with("tasks.")
{
return failure(ErrorCode::InvalidArguments, Some(request_id));
}
if globals.has_capability()
&& !descriptor
.stdin_channels
.iter()
.any(|channel| channel == "capability_fd")
&& !control_plane::accepts_capability(&descriptor.command_id)
{
return failure(ErrorCode::InvalidArguments, Some(request_id));
}
let payload = match command_payload(&descriptor.command_id, options) {
Ok(payload) => payload,
Err(code) => return request_input::diagnostics::failure(code, Some(request_id)),
};
let client = match LocalControlClient::cli_from_environment().map(|client| {
client.with_timeout(
globals
.timeout
.unwrap_or_else(|| std::time::Duration::from_secs(30)),
)
}) {
Ok(client) => client,
Err(_) => return failure(ErrorCode::DaemonUnavailable, Some(request_id)),
};
#[cfg(windows)]
let native_capability = match globals.capability_handle {
Some(handle) => match if descriptor.command_id == "work-plans.list"
|| descriptor.command_id.starts_with("tasks.")
{
work_plans::credential_handle(handle)
} else {
client::read_protected_handle(handle, 512)
} {
Ok(value) => Some(value),
Err(_) => return failure(ErrorCode::CapabilityDenied, Some(request_id)),
},
None => None,
};
#[cfg(not(windows))]
let native_capability: Option<String> = None;
let mutation_capability = match globals.capability_fd {
Some(fd) => match if descriptor.command_id == "work-plans.list"
|| descriptor.command_id.starts_with("tasks.")
{
work_plans::credential(fd)
} else {
client::read_protected_fd(fd)
} {
Ok(value) => Some(value),
Err(_) => return failure(ErrorCode::CapabilityDenied, Some(request_id)),
},
None => {
if native_capability.is_some() {
native_capability
} else {
if let Some(agent) = globals.agent.as_deref() {
#[cfg(not(windows))]
let home = std::env::var_os("HOME").map(std::path::PathBuf::from);
#[cfg(windows)]
let home = hiroute_platform::windows::background::profile().ok();
match home.and_then(|home| {
hiroute_integrations::collaboration_artifact::read_sealed_collaboration(
&home, agent,
)
.ok()
}) {
Some(mut material) => Some(std::mem::take(&mut *material)),
None => return failure(ErrorCode::CapabilityDenied, Some(request_id)),
}
} else {
None
}
}
}
};
let principal_kind = if globals.agent.is_some() {
PrincipalKind::SealedCollaboration
} else if descriptor.command_id == "work-plans.list"
|| descriptor.command_id.starts_with("tasks.")
{
PrincipalKind::Skill
} else {
PrincipalKind::InteractiveUser
};
let hermes_chat = matches!(
descriptor.command_id.as_str(),
"agents.connect.preview" | "agents.connect.apply"
) && payload["spec"]["model"]["settings"]["mode"] == "hermes_default"
&& payload["spec"]["model"]["settings"]["protocol"] == "chat_completions";
let request = LocalControlWireRequestV2 {
schema_version: LOCAL_CONTROL_SCHEMA_V2,
request_id: request_id.clone(),
operation_id: descriptor.operation_id,
payload,
protected_grant: mutation_capability.map(|capability| ProtectedClientGrantV2 {
principal_kind,
capability,
}),
};
let response = client.call(request).unwrap_or_else(|_| {
MachineEnvelopeV2::failed(ErrorV1::new(ErrorCode::DaemonUnavailable), Some(request_id))
});
let mut output = render(response);
if hermes_chat && output.exit_code == 0 {
output.stderr.push_str("建议使用 Hermes >= v0.21.7,以保留工具续接中的推理内容。旧版本仍可连接;仅在插件或接入接口不兼容时阻断。 / Hermes >= v0.21.7 is recommended for reasoning replay across tool calls. Compatible older versions can connect.\n");
}
output
}
fn command_payload(command_id: &str, options: &[String]) -> Result<Value, ErrorCode> {
match command_id {
"system.status" | "system.client-status" | "agents.list" | "sessions.status" => {
empty(options)
}
"agents.scan" => {
if options.is_empty() {
empty(options)
} else {
request_input::typed::<hiroute_application_api::AgentScanRequestV1>(
options,
request_input::MAX_REQUEST_BYTES,
)
}
}
"routing.list" if options.is_empty() => empty(options),
"routing.show" => match options {
[id] if request_input::valid_positional(id) => Ok(json!({"agent_plan_id": id})),
_ => Err(ErrorCode::InvalidArguments),
},
"work-plans.list" => work_plans::payload(options),
task if task.starts_with("tasks.") => tasks::payload(command_id, options),
"operations.find" => client_lookup(options),
"setup.preview" => setup_preview(options),
"setup.apply" => setup_apply(options),
"setup.status" | "operations.get" => operation(options, false),
"operations.watch" => operation(options, true),
"operations.cancel" => operation_cancel(options),
"agents.check" => agent_check(options),
"sessions.list" => observation::sessions_list(options),
"sessions.show" => observation::session_show(options),
"sessions.timeline" => routing_timeline::payload(options),
"sessions.receipt" => observation::session_receipt(options),
"value.show" => observation::value_show(options),
"observation.plan-quality.samples" => observation::plan_quality_samples(options),
"observation.plan-trust"
| "observation.plan-trust.replay"
| "observation.plan-trust.suggestions" => trust::payload(command_id, options),
"observation.storage.show" => observation::capacity_get(options),
"observation.storage.set" => observation::capacity_set(options),
_ => control_plane::command_payload(command_id, options)
.unwrap_or(Err(ErrorCode::UnknownCommand)),
}
}
fn client_lookup(options: &[String]) -> Result<Value, ErrorCode> {
request_input::typed::<hiroute_application_api::OperationIdempotencyLookupV1>(options, 65_536)
}
fn empty(options: &[String]) -> Result<Value, ErrorCode> {
options
.is_empty()
.then(|| json!({}))
.ok_or(ErrorCode::InvalidArguments)
}
fn setup_preview(options: &[String]) -> Result<Value, ErrorCode> {
if options == ["--spec-stdin"] {
return read_json(std::io::stdin());
}
let mut spec = SetupRequestV1::default();
let mut index = 0;
while index < options.len() {
match options[index].as_str() {
"--agent" => spec.agent_ids.push(next(options, &mut index)?),
"--routing-mode" => {
spec.routing_mode = match next(options, &mut index)?.as_str() {
"smart-saving" => RoutingModeV1::SmartSaving,
"free-first" => RoutingModeV1::FreeFirst,
"custom" => RoutingModeV1::Custom,
_ => return Err(ErrorCode::InvalidArguments),
}
}
"--routing-purpose" => spec.routing_purpose = Some(next(options, &mut index)?),
"--free-pool-mode" => {
spec.free_pool_mode = match next(options, &mut index)?.as_str() {
"automatic_all_available" => FreePoolModeV1::AutomaticAllAvailable,
"manual" => FreePoolModeV1::Manual,
_ => return Err(ErrorCode::InvalidArguments),
}
}
"--fallback-policy" => {
spec.fallback_policy = match next(options, &mut index)?.as_str() {
"free_only" => FallbackPolicyV1::FreeOnly,
"primary_fallback" => FallbackPolicyV1::PrimaryFallback,
_ => return Err(ErrorCode::InvalidArguments),
}
}
"--native-subagent-routing" => {
spec.native_subagent_routing = selection(&next(options, &mut index)?)?
}
"--codex-catalog" => spec.codex_catalog = selection(&next(options, &mut index)?)?,
_ => return Err(ErrorCode::InvalidArguments),
}
index += 1;
}
serde_json::to_value(spec).map_err(|_| ErrorCode::Internal)
}
fn setup_apply(options: &[String]) -> Result<Value, ErrorCode> {
let mut spec = None;
let mut digest = None;
let mut revision = None;
let mut idempotency_key = None;
let mut index = 0;
while index < options.len() {
match options[index].as_str() {
#[cfg(unix)]
"--spec-fd" => {
if spec.is_some() {
return Err(ErrorCode::InvalidArguments);
}
let fd = next(options, &mut index)?
.parse::<u32>()
.map_err(|_| ErrorCode::InvalidArguments)?;
spec = Some(read_json(
std::fs::File::open(format!("/dev/fd/{fd}"))
.map_err(|_| ErrorCode::InvalidArguments)?,
)?);
}
#[cfg(windows)]
"--spec-handle" => {
if spec.is_some() {
return Err(ErrorCode::InvalidArguments);
}
let handle = next(options, &mut index)?
.parse::<u64>()
.map_err(|_| ErrorCode::InvalidArguments)?;
let bytes = hiroute_platform::windows::job::read_inherited_credential(
handle,
1024 * 1024,
std::time::Duration::from_secs(2),
)
.map_err(|_| ErrorCode::InvalidArguments)?;
spec = Some(read_json(bytes.as_slice())?);
}
"--accept-digest" => {
digest = Some(
CanonicalDigest::parse(next(options, &mut index)?)
.map_err(|_| ErrorCode::InvalidArguments)?,
)
}
"--expected-revision" => {
revision = Some(
next(options, &mut index)?
.parse::<u64>()
.map_err(|_| ErrorCode::InvalidArguments)?,
)
}
"--idempotency-key" => idempotency_key = Some(next(options, &mut index)?),
_ => return Err(ErrorCode::InvalidArguments),
}
index += 1;
}
serde_json::to_value(SetupApplyRequestV1 {
spec: crate::request_input::deserialize(spec.ok_or(ErrorCode::InvalidArguments)?)?,
accept_digest: digest.ok_or(ErrorCode::InvalidArguments)?,
expected_revision: revision.ok_or(ErrorCode::InvalidArguments)?,
idempotency_key: idempotency_key
.filter(|value| !value.is_empty())
.ok_or(ErrorCode::InvalidArguments)?,
})
.map_err(|_| ErrorCode::Internal)
}
fn operation(options: &[String], watch: bool) -> Result<Value, ErrorCode> {
let Some(operation_id) = options
.first()
.filter(|value| request_input::valid_positional(value))
else {
return Err(ErrorCode::InvalidArguments);
};
let mut after_sequence = 0;
if options.len() > 1 {
if !watch || options.len() != 3 || options[1] != "--after-sequence" {
return Err(ErrorCode::InvalidArguments);
}
after_sequence = options[2]
.parse()
.map_err(|_| ErrorCode::InvalidArguments)?;
}
serde_json::to_value(OperationLookupV1 {
operation_id: operation_id.clone(),
after_sequence,
})
.map_err(|_| ErrorCode::Internal)
}
fn operation_cancel(options: &[String]) -> Result<Value, ErrorCode> {
let Some(operation_id) = options
.first()
.filter(|value| request_input::valid_positional(value))
else {
return Err(ErrorCode::InvalidArguments);
};
if options.len() != 3 || options[1] != "--idempotency-key" || options[2].is_empty() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(OperationCancelRequestV1 {
operation_id: operation_id.clone(),
idempotency_key: options[2].clone(),
})
.map_err(|_| ErrorCode::Internal)
}
fn agent_check(options: &[String]) -> Result<Value, ErrorCode> {
let Some(agent_id) = options
.first()
.filter(|value| request_input::valid_positional(value))
else {
return Err(ErrorCode::InvalidArguments);
};
let mut request = AgentCheckRequestV1 {
agent_id: agent_id.clone(),
scope: AgentCheckScopeV1::Configuration,
suite: AgentCheckSuiteV1::Quick,
allow_model_call: false,
target: None,
};
let mut index = 1;
while index < options.len() {
match options[index].as_str() {
"--scope" => {
request.scope = match next(options, &mut index)?.as_str() {
"configuration" => AgentCheckScopeV1::Configuration,
"live" => AgentCheckScopeV1::Live,
"native-authentication" => AgentCheckScopeV1::NativeAuthentication,
"collaboration" => AgentCheckScopeV1::Collaboration,
_ => return Err(ErrorCode::InvalidArguments),
}
}
"--suite" => {
request.suite = match next(options, &mut index)?.as_str() {
"quick" => AgentCheckSuiteV1::Quick,
"tool" => AgentCheckSuiteV1::Tool,
"conformance" => AgentCheckSuiteV1::Conformance,
_ => return Err(ErrorCode::InvalidArguments),
}
}
"--allow-model-call" => request.allow_model_call = true,
"--target" => {
if request.target.is_some() {
return Err(ErrorCode::InvalidArguments);
}
request.target = Some(
serde_json::from_str(&next(options, &mut index)?)
.map_err(|_| ErrorCode::InvalidArguments)?,
);
}
_ => return Err(ErrorCode::InvalidArguments),
}
index += 1;
}
if !request.valid_target() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
}
fn selection(value: &str) -> Result<SetupSelectionV1, ErrorCode> {
match value {
"auto" => Ok(SetupSelectionV1::Automatic),
"on" => Ok(SetupSelectionV1::Enabled),
"off" => Ok(SetupSelectionV1::Disabled),
_ => Err(ErrorCode::InvalidArguments),
}
}
fn next(options: &[String], index: &mut usize) -> Result<String, ErrorCode> {
*index += 1;
options
.get(*index)
.filter(|value| !value.is_empty())
.cloned()
.ok_or(ErrorCode::InvalidArguments)
}
fn read_json(reader: impl std::io::Read) -> Result<Value, ErrorCode> {
request_input::read_json(reader, request_input::MAX_REQUEST_BYTES)
}
fn resolve_callable(arguments: &[String]) -> Option<(CommandDescriptorV1, usize)> {
released_commands()
.into_iter()
.filter_map(|descriptor| {
let matches = arguments.len() >= descriptor.path.len()
&& arguments
.iter()
.zip(&descriptor.path)
.all(|(actual, expected)| actual == expected);
matches.then_some((descriptor.clone(), descriptor.path.len()))
})
.max_by_key(|(_, length)| *length)
}
fn execute_schema_list(options: &[String], request_id: Option<String>) -> CliExecution {
if !options.is_empty() {
return failure(ErrorCode::InvalidArguments, request_id);
}
success(
json!({
"descriptor_digest": descriptor_digest(),
"commands": released_commands().into_iter().map(|command| json!({
"command_id": command.command_id,
"path": command.path,
"operation_id": command.operation_id,
})).collect::<Vec<_>>(),
}),
request_id,
)
}
fn execute_schema_show(options: &[String], request_id: Option<String>) -> CliExecution {
let (command_id, include_schema) = match options {
[flag, id] if flag == "--command-id" => (id, false),
[flag, id, include] if flag == "--command-id" && include == "--include-schema" => {
(id, true)
}
[include, flag, id] if include == "--include-schema" && flag == "--command-id" => {
(id, true)
}
_ => return failure(ErrorCode::InvalidArguments, request_id),
};
let Some(descriptor) = command_by_id(command_id)
.filter(|descriptor| descriptor.lifecycle == CommandLifecycle::Released)
else {
return failure(ErrorCode::ResourceNotFound, request_id);
};
if include_schema {
let Some(schemas) = hiroute_application_api::command_schemas(command_id) else {
let mut result = failure(ErrorCode::ResourceNotFound, request_id);
result.stderr = "Full installed schemas are not yet available for this command. Omit --include-schema to read its descriptor.\n".into();
return result;
};
return success(
json!({"descriptor":descriptor,"schemas":schemas}),
request_id,
);
}
success(descriptor, request_id)
}
fn success<T: Serialize>(data: T, request_id: Option<String>) -> CliExecution {
render(MachineEnvelopeV2::succeeded(
serde_json::to_value(data).expect("CLI data is serializable"),
request_id,
))
}
fn failure(code: ErrorCode, request_id: Option<String>) -> CliExecution {
render(MachineEnvelopeV2::failed(ErrorV1::new(code), request_id))
}
const DAEMON_UNAVAILABLE_HINT: &str = "HiRoute 服务不可用。Standalone 请运行 `hiroute service status`,并在需要时运行 `hiroute service start`;Desktop 请启动或恢复应用。隔离实例请检查运行目录。不会自动启动或重放请求。\n";
fn render(envelope: MachineEnvelopeV2<Value>) -> CliExecution {
let stderr = if envelope
.error
.as_ref()
.is_some_and(|error| error.message_key == "error.agent_collaboration_root_context_required")
{
"Codex 协作配置属于原始 HOME 的 root context;请使用 agents scan 中的 codex_access.root_context_id,或运行 hiroute agents collaboration configure <AGENT_ID> --trigger explicit。模型 profile context 不支持协作配置。\n".to_owned()
} else if envelope
.error
.as_ref()
.is_some_and(|error| error.code == ErrorCode::DaemonUnavailable)
{
DAEMON_UNAVAILABLE_HINT.to_owned()
} else {
String::new()
};
let mut stdout = serde_json::to_string(&envelope).expect("machine envelope is serializable");
stdout.push('\n');
CliExecution {
exit_code: envelope.status.exit_code(),
stdout,
stderr,
}
}
fn next_request_id() -> String {
format!(
"req_{}_{}",
std::process::id(),
REQUEST_SEQUENCE.fetch_add(1, Ordering::Relaxed)
)
}
pub fn root_help() -> String {
let mut families = released_commands()
.into_iter()
.map(|descriptor| descriptor.path[0].clone())
.collect::<Vec<_>>();
families.extend([
"gateway".into(),
"protected-input".into(),
"service".into(),
"subscription-proxy".into(),
"quickstart".into(),
]);
families.sort();
families.dedup();
let commands = families
.into_iter()
.map(|family| format!(" {family}"))
.collect::<Vec<_>>()
.join("\n");
format!(
"HiRoute headless product CLI\n\nUsage\n hiroute <command> [options]\n\nPublic command families\n{commands}\n\nStart or resume: run 'hiroute quickstart --help'.\nDecision connections: run 'hiroute decision services options --help' for installed presets and reusable saved connections.\nHost management: run 'hiroute service --help', 'hiroute gateway --help', 'hiroute protected-input --help', 'hiroute subscription-proxy --help', or 'hiroute console --help'.\nAgent collaboration workflow: run 'hiroute agents collaboration --help' to enable, edit, disable or inspect collaboration independently of model settings.\nApplication/Local Control: run 'hiroute schema list --output json' and 'hiroute schema show --command-id <ID> --output json', then append '--help' to a complete command path, for example 'hiroute worker dependencies discover --help'.\n"
)
}
fn native_help_document(descriptor: &CommandDescriptorV1) -> String {
let document = descriptor.help_document();
#[cfg(windows)]
{
// Presentation adapts carriers; the shared registry and its digest retain their bytes.
document
.replace("--capability-fd", "--capability-handle")
.replace("--spec-fd", "--spec-handle")
.replace("--secret-fd", "--secret-handle")
.replace("<FD>", "<HANDLE>")
.replace("capability FD", "capability handle")
.replace("same-UID", "same-account")
}
#[cfg(not(windows))]
document
}
pub fn main_entry() -> u8 {
let arguments = std::env::args_os().skip(1).collect::<Vec<_>>();
#[cfg(windows)]
if let Some(verb) = arguments
.first()
.and_then(|v| v.to_str())
.filter(|v| matches!(*v, "__windows-install" | "__windows-uninstall"))
{
return service::windows_install_hidden(verb, &arguments[1..]);
}
#[cfg(windows)]
if arguments
.first()
.is_some_and(|argument| argument == service::windows_background_finalize_verb())
{
return service::windows_background_finalize(&arguments[1..]);
}
#[cfg(windows)]
if arguments
.first()
.is_some_and(|argument| argument == service::windows_scm_owner_helper_verb())
{
return service::windows_scm_owner_helper(&arguments[1..]);
}
if arguments.as_slice() == [OsString::from("service"), OsString::from("run")] {
return service::foreground_run();
}
if arguments
.first()
.is_some_and(|argument| argument == HIDDEN_AGENT_GRANT_HELPER_VERB_V1)
{
return hidden_agent_grant_helper(&arguments[1..]);
}
let execution = execute(arguments);
let _ = std::io::stdout().write_all(execution.stdout.as_bytes());
let _ = std::io::stderr().write_all(execution.stderr.as_bytes());
execution.exit_code
}
fn hidden_agent_grant_helper(arguments: &[OsString]) -> u8 {
let [connection_id] = arguments else {
let _ = std::io::stderr().write_all(b"hiroute agent grant request invalid\n");
return 2;
};
let Some(connection_id) = connection_id.to_str() else {
let _ = std::io::stderr().write_all(b"hiroute agent grant request invalid\n");
return 2;
};
let material = LocalControlClient::cli_from_environment()
.and_then(|client| client.read_agent_grant(connection_id));
match material {
Ok(material) => {
if material.write_to(&mut std::io::stdout()).is_ok() {
return 0;
}
let _ = std::io::stderr().write_all(b"hiroute agent grant unavailable\n");
6
}
Err(_) => {
let _ = std::io::stderr().write_all(b"hiroute agent grant unavailable\n");
6
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn root_help_projects_public_application_and_host_families() {
let help = root_help();
assert!(help.contains(" agent"));
assert!(help.contains(" schema"));
assert!(help.contains(" worker"));
assert!(!help.contains("setup"));
assert!(help.contains(" gateway"));
assert!(help.contains(" service"));
assert!(help.contains(" subscription-proxy"));
assert!(!help.contains(HIDDEN_AGENT_GRANT_HELPER_VERB_V1));
assert!(help.contains("Host management"));
assert!(help.contains("hiroute service --help"));
assert!(help.contains("hiroute gateway --help"));
assert!(help.contains("hiroute protected-input --help"));
assert!(help.contains("hiroute subscription-proxy --help"));
assert!(help.contains("Application/Local Control"));
assert!(help.contains("complete command path"));
assert!(help.contains("hiroute worker dependencies discover --help"));
assert!(!help.contains("Run a command family with '--help'"));
}
#[test]
fn root_help_reaches_family_navigation_and_precise_leaf_help() {
let family = execute(["worker", "--help"]);
assert_eq!(family.exit_code, 0);
assert!(family.stdout.contains("dependencies select"));
assert!(family.stdout.contains("--include-schema"));
let leaf = execute(["worker", "dependencies", "select", "--help"]);
assert_eq!(leaf.exit_code, 0);
assert!(leaf.stderr.is_empty());
assert!(leaf.stdout.contains("expected_selection_revision"));
assert!(leaf.stdout.contains("replay that same document unchanged"));
}
#[test]
fn schema_list_remains_a_single_public_machine_envelope() {
let execution = execute(["schema", "list", "--output", "json", "--non-interactive"]);
assert_eq!(execution.exit_code, 0);
assert_eq!(execution.stdout.lines().count(), 1);
let value: Value = serde_json::from_str(&execution.stdout).unwrap();
assert_eq!(value["data"]["commands"].as_array().unwrap().len(), 76);
assert!(!execution.stdout.contains(HIDDEN_AGENT_GRANT_HELPER_VERB_V1));
}
#[test]
fn plan_quality_is_discoverable_through_public_schema_and_leaf_help() {
let help = execute(["observation", "plan-quality", "samples", "--help"]);
assert_eq!(help.exit_code, 0, "{}", help.stdout);
assert!(help.stdout.contains("--session-id"));
assert!(help.stdout.contains("--competence"));
let list = execute(["schema", "list", "--output", "json"]);
let list: Value = serde_json::from_str(&list.stdout).unwrap();
assert!(
list["data"]["commands"]
.as_array()
.unwrap()
.iter()
.any(|entry| {
entry["command_id"] == "observation.plan-quality.samples"
&& entry["operation_id"] == "GetPlanQualitySamples"
})
);
let descriptor = execute([
"schema",
"show",
"--command-id",
"observation.plan-quality.samples",
]);
assert_eq!(descriptor.exit_code, 0, "{}", descriptor.stdout);
let descriptor: Value = serde_json::from_str(&descriptor.stdout).unwrap();
assert_eq!(descriptor["data"]["kind"], "query");
}
#[test]
fn managed_launch_rejects_auth_routing_arguments_before_daemon_access() {
let execution = execute([
"agent",
"launch",
"--agent",
"claude-code",
"--context",
"agent-context/claude/default",
"--",
"--use-bedrock",
]);
assert_eq!(execution.exit_code, 3);
let value: Value = serde_json::from_str(&execution.stdout).unwrap();
assert_eq!(value["error"]["code"], "AGENT_AUTH_PRECEDENCE_CONFLICT");
// Model selection, setting sources, and fallback stay caller-directed: the parse
// succeeds and the command proceeds to (and fails at) Local Control, never at the
// argument gate.
let missing_delimiter = execute([
"agent",
"launch",
"--agent",
"claude-code",
"--context",
"agent-context/claude/default",
"--print",
]);
assert_eq!(missing_delimiter.exit_code, 2);
let unknown_agent = execute([
"agent",
"launch",
"--agent",
"codex",
"--context",
"agent-context/claude/default",
"--",
"--print",
]);
assert_eq!(unknown_agent.exit_code, 2);
}
#[test]
fn hidden_helper_is_not_a_public_cli_command() {
let execution = execute([HIDDEN_AGENT_GRANT_HELPER_VERB_V1, "agent-connection/claude"]);
assert_eq!(execution.exit_code, 2);
let value: Value = serde_json::from_str(&execution.stdout).unwrap();
assert_eq!(value["error"]["code"], "UNKNOWN_COMMAND");
assert!(!root_help().contains(HIDDEN_AGENT_GRANT_HELPER_VERB_V1));
}
#[test]
fn unstaged_planned_command_is_not_callable() {
let execution = execute(["settings", "show", "--output", "json"]);
assert_eq!(execution.exit_code, 2);
}
#[test]
fn released_leaf_help_is_publicly_callable() {
let execution = execute(["compute", "connection", "preview", "--help"]);
assert_eq!(execution.exit_code, 0);
assert!(execution.stdout.contains("--request-stdin"));
}
#[test]
fn capability_value_has_no_argv_or_environment_fallback() {
let (_, globals) = split_globals(vec![
"setup".into(),
"apply".into(),
"--capability-fd".into(),
"9".into(),
])
.unwrap();
assert_eq!(globals.capability_fd, Some(9));
}
}
mod tasks;
mod work_plans;