Skip to content

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.

9.8 KB
Raw Blame
use std::collections::BTreeSet;

use serde::{Deserialize, Serialize};
use thiserror::Error;

use crate::{AgentClaudePresetValuesV2, CanonicalDigest, valid_client_model_name};

pub const MANAGED_CLAUDE_LAUNCH_DESCRIPTOR_SCHEMA_V2: &str =
    "hiroute.managed-claude-launch-descriptor/v2";
pub const HIDDEN_AGENT_GRANT_HELPER_VERB_V1: &str = "__internal-agent-grant-v1";
pub const MANAGED_CLAUDE_SETTINGS_ARGUMENT_V1: &str = "--settings";
pub const MANAGED_CLAUDE_SETTING_SOURCES_ARGUMENT_V1: &str = "--setting-sources";

pub const MANAGED_CLAUDE_ENVIRONMENT_REMOVALS_V1: [&str; 8] = [
    "ANTHROPIC_API_KEY",
    "ANTHROPIC_AUTH_TOKEN",
    "ANTHROPIC_BASE_URL",
    "ANTHROPIC_CUSTOM_HEADERS",
    "ANTHROPIC_MODEL",
    "CLAUDE_CODE_USE_BEDROCK",
    "CLAUDE_CODE_USE_FOUNDRY",
    "CLAUDE_CODE_USE_VERTEX",
];

/// Only arguments that would override the managed gateway, authentication, or cloud provider
/// routing are refused outright. Model selection, `--settings`, `--setting-sources`, and
/// `--fallback-model` reach the launcher and are directed against the published snapshot:
/// the child resolves them under the managed grant exactly like any other request name.
pub const MANAGED_CLAUDE_CALLER_FORBIDDEN_OPTIONS_V1: [&str; 14] = [
    "--anthropic-api-key",
    "--anthropic-auth-token",
    "--api-key",
    "--api-key-helper",
    "--auth-token",
    "--base-url",
    "--bedrock",
    "--custom-headers",
    "--foundry",
    "--provider",
    "--use-bedrock",
    "--use-foundry",
    "--use-vertex",
    "--vertex",
];

#[derive(schemars::JsonSchema, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AgentActivationModeV1 {
    ManagedConfiguration,
    ManagedLaunch,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ManagedLaunchProfileV1 {
    /// Recovery-only historical label, excluded from capability validation.
    #[serde(
        default,
        rename = "exact_version",
        skip_serializing_if = "String::is_empty"
    )]
    pub legacy_exact_version: String,
    pub settings_argument: String,
    pub environment_removals: BTreeSet<String>,
    pub caller_forbidden_options: BTreeSet<String>,
}

impl ManagedLaunchProfileV1 {
    pub fn claude_code() -> Self {
        Self {
            legacy_exact_version: String::new(),
            settings_argument: MANAGED_CLAUDE_SETTINGS_ARGUMENT_V1.to_owned(),
            environment_removals: MANAGED_CLAUDE_ENVIRONMENT_REMOVALS_V1
                .into_iter()
                .map(str::to_owned)
                .collect(),
            caller_forbidden_options: MANAGED_CLAUDE_CALLER_FORBIDDEN_OPTIONS_V1
                .into_iter()
                .map(str::to_owned)
                .collect(),
        }
    }

    pub fn validate(&self) -> Result<(), ManagedLaunchError> {
        let trusted = Self::claude_code();
        if self.settings_argument != trusted.settings_argument
            || self.environment_removals != trusted.environment_removals
            || self.caller_forbidden_options != trusted.caller_forbidden_options
        {
            return Err(ManagedLaunchError::UntrustedProfile);
        }
        Ok(())
    }

    pub fn forbids_caller_option(&self, argument: &str) -> bool {
        self.caller_forbidden_options.iter().any(|option| {
            argument == option
                || argument
                    .strip_prefix(option)
                    .is_some_and(|suffix| suffix.starts_with('='))
        })
    }
}

/// The launcher's routing facts for one managed Claude connection. Every field comes from the
/// succeeded settings Operation, its grant, and the current trusted installation choice; nothing
/// here re-derives routing from user configuration at launch time.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ManagedClaudeLaunchDescriptorV2 {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub context_window_tokens: Option<u64>,
    pub schema: String,
    pub connection_id: String,
    pub profile_id: String,
    pub executable: String,
    /// Digest of the settings Operation's immutable three-slot snapshot facts.
    pub snapshot_digest: CanonicalDigest,
    pub grant_generation: u64,
    pub publication_digest: CanonicalDigest,
    pub gateway_base_url: String,
    /// The three native slot values the managed overlay carries: mapped slots hold the plan
    /// alias, preserved slots hold the snapshot's original value or stay absent.
    pub presets: AgentClaudePresetValuesV2,
    pub helper_executable: String,
    pub helper_argv: Vec<String>,
    pub environment_removals: BTreeSet<String>,
}

impl ManagedClaudeLaunchDescriptorV2 {
    #[allow(clippy::too_many_arguments)]
    pub fn trusted(
        connection_id: impl Into<String>,
        profile_id: impl Into<String>,
        executable: impl Into<String>,
        snapshot_digest: CanonicalDigest,
        grant_generation: u64,
        publication_digest: CanonicalDigest,
        gateway_base_url: impl Into<String>,
        presets: AgentClaudePresetValuesV2,
        trusted_hiroute_executable: impl Into<String>,
    ) -> Result<Self, ManagedLaunchError> {
        let connection_id = connection_id.into();
        let helper_executable = trusted_hiroute_executable.into();
        let value = Self {
            context_window_tokens: None,
            schema: MANAGED_CLAUDE_LAUNCH_DESCRIPTOR_SCHEMA_V2.to_owned(),
            connection_id: connection_id.clone(),
            profile_id: profile_id.into(),
            executable: executable.into(),
            snapshot_digest,
            grant_generation,
            publication_digest,
            gateway_base_url: gateway_base_url.into(),
            presets,
            helper_executable,
            helper_argv: vec![HIDDEN_AGENT_GRANT_HELPER_VERB_V1.to_owned(), connection_id],
            environment_removals: MANAGED_CLAUDE_ENVIRONMENT_REMOVALS_V1
                .into_iter()
                .map(str::to_owned)
                .collect(),
        };
        value.validate()?;
        Ok(value)
    }

    pub fn validate(&self) -> Result<(), ManagedLaunchError> {
        if self
            .context_window_tokens
            .is_some_and(|value| crate::claude_context_window(value) != Some(value))
            || self.schema != MANAGED_CLAUDE_LAUNCH_DESCRIPTOR_SCHEMA_V2
            || self.grant_generation == 0
            || !valid_connection_id(&self.connection_id)
            || !valid_identifier(&self.profile_id)
            || !is_absolute_path(&self.executable)
            || !is_absolute_path(&self.helper_executable)
            || !is_numeric_loopback_origin(&self.gateway_base_url)
            || self.helper_argv
                != [
                    HIDDEN_AGENT_GRANT_HELPER_VERB_V1.to_owned(),
                    self.connection_id.clone(),
                ]
            || self.environment_removals
                != MANAGED_CLAUDE_ENVIRONMENT_REMOVALS_V1
                    .into_iter()
                    .map(str::to_owned)
                    .collect()
        {
            return Err(ManagedLaunchError::InvalidDescriptor);
        }
        CanonicalDigest::parse(self.snapshot_digest.as_str().to_owned())
            .map_err(|_| ManagedLaunchError::InvalidDescriptor)?;
        CanonicalDigest::parse(self.publication_digest.as_str().to_owned())
            .map_err(|_| ManagedLaunchError::InvalidDescriptor)?;
        [
            &self.presets.opus,
            &self.presets.sonnet,
            &self.presets.haiku,
        ]
        .into_iter()
        .flatten()
        .all(|value| valid_client_model_name(value))
        .then_some(())
        .ok_or(ManagedLaunchError::InvalidDescriptor)?;
        Ok(())
    }

    pub fn validate_trusted_helper(
        &self,
        trusted_hiroute_executable: &str,
    ) -> Result<(), ManagedLaunchError> {
        self.validate()?;
        if self.helper_executable != trusted_hiroute_executable {
            return Err(ManagedLaunchError::UntrustedHelper);
        }
        Ok(())
    }
}

fn valid_identifier(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 256
        && !value.contains("..")
        && !value.contains("//")
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b'/'))
}

fn valid_connection_id(value: &str) -> bool {
    value
        .strip_prefix("agent-connection/")
        .is_some_and(|suffix| !suffix.is_empty())
        && value.len() <= 256
        && !value.contains("..")
        && !value.contains("//")
        && value.bytes().all(|byte| {
            byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b'/' | b':')
        })
}

fn is_absolute_path(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 4096
        && !value.contains('\0')
        && (value.starts_with('/')
            || (value.len() >= 3
                && value.as_bytes()[1] == b':'
                && matches!(value.as_bytes()[2], b'/' | b'\\')))
}

fn is_numeric_loopback_origin(value: &str) -> bool {
    let Some(authority) = value.strip_prefix("http://") else {
        return false;
    };
    let port = authority
        .strip_prefix("127.0.0.1:")
        .or_else(|| authority.strip_prefix("[::1]:"));
    port.is_some_and(|port| {
        !port.is_empty()
            && port.bytes().all(|byte| byte.is_ascii_digit())
            && port.parse::<u16>().is_ok_and(|port| port != 0)
    })
}

#[derive(Clone, Copy, Debug, Error, Eq, PartialEq)]
pub enum ManagedLaunchError {
    #[error("managed-launch profile is not the compiled trusted capability")]
    UntrustedProfile,
    #[error("managed-launch descriptor is invalid")]
    InvalidDescriptor,
    #[error("managed-launch helper executable is not the current trusted hiroute executable")]
    UntrustedHelper,
}