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.

29.9 KB
Raw Blame
//! Settings facts transported from the real backend to the existing typed planner.
use super::*;
use hiroute_domain::{
    AgentAccessGrantMaterialActionV1, AgentAccessGrantMutationV1, AgentAccessGrantRefV1,
    AgentAccessGrantScopeV1, AgentAccessTokenIntentV1, AgentConnectionTransactionSubjectV1,
    AgentFacetIntent, AgentIngressProtocolV1, AgentModelSelectionV2, CanonicalDigest, OperationId,
    OperationValidationError, RevisionSetV1, SupportedAgentInstallationV1, TransactionPlanV1,
    WorkspaceId, settings_model_publication_intent,
};
use serde_json::json;
use std::path::Path;

pub struct AgentSettingsPlanningInput {
    pub collaboration_state: serde_json::Value,
    pub facts: AgentSettingsFacts,
    pub expected_revisions: RevisionSetV1,
    pub subject: AgentConnectionTransactionSubjectV1,
    pub model_file: Option<SettingsModelFileFacts>,
    pub skill_file: SettingsSkillFileFacts,
    /// The independent second resource. The primary slot retains accepted legacy semantics.
    pub additional_skill_file: Option<SettingsSkillFileFacts>,
}

/// Non-secret backend facts, all included in the accepted dependency digest.
pub struct SettingsModelFileFacts {
    pub expected_content: CanonicalDigest,
    pub before_fingerprint: Option<CanonicalDigest>,
    /// Collaboration-only settings remain valid before the first publication. Model changes
    /// still require and bind the exact active publication when their effect is sealed.
    pub publication_digest: Option<CanonicalDigest>,
    pub expected_grant_generation: u64,
    pub token_input_fingerprint: Option<CanonicalDigest>,
    /// The exact succeeded configuration that owns the currently active grant, if any.
    pub active_configuration: Option<OperationId>,
    pub restore: Option<(OperationId, AgentAccessGrantRefV1)>,
    pub target: SettingsModelTargetFacts,
}

/// Each main Agent keeps one registered managed-configuration target.  The current target is
/// selected only by the daemon's registered scanner/profile join, never by a public request.
#[allow(clippy::large_enum_variant)] // These short-lived planner facts stay typed and allocation-free.
pub enum SettingsModelTargetFacts {
    Hermes {
        provider_id: String,
        endpoint: String,
        model: hiroute_domain::AdditionalAgentModelV1,
        plugins: Vec<super::HermesPluginFileFacts>,
    },
    Codex {
        provider_id: String,
        endpoint: String,
    },
    Claude(SettingsClaudeModelFacts),
    Additional {
        kind: hiroute_domain::AgentKindV1,
        pi_settings_content: Option<CanonicalDigest>,
        additional_dependencies: Option<CanonicalDigest>,
        provider_id: String,
        endpoint: String,
        models: Vec<hiroute_domain::AdditionalAgentModelV1>,
    },
}

pub struct SettingsClaudeModelFacts {
    pub installation: SupportedAgentInstallationV1,
    pub executable: Option<String>,
    pub gateway_base_url: String,
    pub trusted_hiroute_executable: String,
    pub user_document: hiroute_domain::AgentConfigDocumentV1,
}

/// Shared-file facts for one registered Agent-owned Skill root.  The template is bundled product
/// content, not a scanner result or WebView payload.
pub struct SettingsSkillFileFacts {
    pub root_ref: String,
    pub target: String,
    pub before: Option<ManagedCollaborationSkill>,
    pub observed_file: Option<CanonicalDigest>,
    pub before_fingerprint: Option<CanonicalDigest>,
    pub template: CollaborationSkillTemplate,
}

impl AgentSettingsPlanningInput {
    pub fn seal_settings(
        &self,
        confirmed: &ConfirmedAgentSettings,
    ) -> Result<TransactionPlanV1, OperationValidationError> {
        let invalid = || OperationValidationError::UnregisteredEffectPlan;
        let preview = confirmed.preview();
        if preview.dependency_digest != self.facts.dependency_digest
            || preview.spec.context_id != self.facts.context_id
        {
            return Err(invalid());
        }
        if self.facts.model.is_none()
            && (!matches!(preview.spec.model, AgentFacetIntent::Keep)
                || !matches!(preview.spec.access_token, AgentAccessTokenIntentV1::Keep)
                || preview.model_grant.is_some())
        {
            return Err(invalid());
        }
        let (model_mutations, model_action, restore_grant) = match &preview.spec.model {
            AgentFacetIntent::Configure { settings } => {
                let file = self.model_file.as_ref().ok_or_else(invalid)?;
                let model = self.facts.model.as_ref().ok_or_else(invalid)?;
                let grant = preview.model_grant.as_ref().ok_or_else(invalid)?;
                let scope = AgentAccessGrantScopeV1::new(
                    format!("agent-connection/{}", self.facts.context_id),
                    grant.clone(),
                )?;
                let action = match &file.target {
                    SettingsModelTargetFacts::Hermes {
                        provider_id,
                        endpoint,
                        model,
                        ..
                    } => {
                        if !matches!(settings, AgentModelSelectionV2::HermesDefault { .. }) {
                            return Err(invalid());
                        }
                        SettingsModelAction::Hermes(super::HermesModelFileAction::Configure {
                            previous_operation: file.active_configuration.clone(),
                            provider_id: provider_id.clone(),
                            endpoint: endpoint.clone(),
                            model: model.clone(),
                        })
                    }
                    SettingsModelTargetFacts::Codex {
                        provider_id,
                        endpoint,
                    } => SettingsModelAction::Codex(CodexModelFileAction::Configure {
                        previous_operation: file.active_configuration.clone(),
                        provider_id: provider_id.clone(),
                        endpoint: endpoint.clone(),
                        model: grant
                            .codex_default_override(settings)
                            .map_err(|_| invalid())?,
                        model_catalog: model
                            .codex()
                            .and_then(|facts| facts.model_catalog.as_ref())
                            .map(|catalog| catalog.content_digest.clone()),
                    }),
                    SettingsModelTargetFacts::Additional {
                        kind,
                        pi_settings_content,
                        additional_dependencies,
                        provider_id,
                        endpoint,
                        models,
                    } => {
                        if !matches!(
                            settings,
                            AgentModelSelectionV2::QoderAdditional { .. }
                                | AgentModelSelectionV2::PiAdditional { .. }
                                | AgentModelSelectionV2::DshAdditional { .. }
                                | AgentModelSelectionV2::OpenCodeAdditional { .. }
                        ) || matches!(settings, AgentModelSelectionV2::PiAdditional { .. })
                            != (*kind == hiroute_domain::AgentKindV1::Pi)
                            || matches!(settings, AgentModelSelectionV2::DshAdditional { .. })
                                != (*kind == hiroute_domain::AgentKindV1::DeepseekHarness)
                            || matches!(settings, AgentModelSelectionV2::OpenCodeAdditional { .. })
                                != (*kind == hiroute_domain::AgentKindV1::OpenCode)
                        {
                            return Err(invalid());
                        }
                        SettingsModelAction::Additional(
                            pi_settings_content.clone(),
                            additional_dependencies.clone(),
                            super::AdditionalModelFileAction::Configure {
                                previous_operation: file.active_configuration.clone(),
                                provider_id: provider_id.clone(),
                                endpoint: endpoint.clone(),
                                models: models.clone(),
                            },
                        )
                    }
                    SettingsModelTargetFacts::Claude(claude) => {
                        let mut snapshot = claude_model_snapshot(
                            settings,
                            grant,
                            claude,
                            model
                                .claude()
                                .and_then(|facts| facts.presets.as_ref())
                                .ok_or_else(invalid)?,
                        )?;
                        snapshot.context_window_tokens = preview.claude_context_window;
                        SettingsModelAction::Claude(ClaudeModelFileAction::Configure {
                            previous_operation: file.active_configuration.clone(),
                            change: claude_native_change(
                                &snapshot,
                                claude,
                                &self.facts.context_id,
                                file.active_configuration.is_some(),
                            )?,
                            snapshot: Box::new(snapshot),
                            gateway_base_url: claude.gateway_base_url.clone(),
                            trusted_hiroute_executable: claude.trusted_hiroute_executable.clone(),
                        })
                    }
                };
                let material_action = match &preview.spec.access_token {
                    AgentAccessTokenIntentV1::Keep => AgentAccessGrantMaterialActionV1::Preserve,
                    AgentAccessTokenIntentV1::Regenerate => {
                        AgentAccessGrantMaterialActionV1::Regenerate
                    }
                    AgentAccessTokenIntentV1::Set { input_slot } => {
                        AgentAccessGrantMaterialActionV1::Set {
                            input_slot: input_slot.clone(),
                            fingerprint: file
                                .token_input_fingerprint
                                .clone()
                                .ok_or_else(invalid)?,
                        }
                    }
                };
                (
                    vec![
                        AgentAccessGrantMutationV1::ensure(
                            WorkspaceId::DEFAULT,
                            scope,
                            file.expected_grant_generation,
                        )?
                        .with_material_action(material_action)?,
                    ],
                    Some(action),
                    None,
                )
            }
            AgentFacetIntent::Restore { restore_point_ref } => {
                let file = self.model_file.as_ref().ok_or_else(invalid)?;
                self.facts.model.as_ref().ok_or_else(invalid)?;
                let (operation, reference) = file.restore.as_ref().ok_or_else(invalid)?;
                if *restore_point_ref != codex_model_restore_point_ref(operation)
                    || reference.generation() != file.expected_grant_generation
                {
                    return Err(invalid());
                }
                let action = match &file.target {
                    SettingsModelTargetFacts::Hermes { .. } => {
                        SettingsModelAction::Hermes(super::HermesModelFileAction::Restore {
                            original_operation: operation.clone(),
                        })
                    }
                    SettingsModelTargetFacts::Codex { .. } => {
                        SettingsModelAction::Codex(CodexModelFileAction::Restore {
                            original_operation: operation.clone(),
                            native_model: preview.spec.restore_native_model.clone(),
                        })
                    }
                    SettingsModelTargetFacts::Additional {
                        pi_settings_content,
                        additional_dependencies,
                        ..
                    } => SettingsModelAction::Additional(
                        pi_settings_content.clone(),
                        additional_dependencies.clone(),
                        super::AdditionalModelFileAction::Restore {
                            original_operation: operation.clone(),
                        },
                    ),
                    SettingsModelTargetFacts::Claude(_) => {
                        SettingsModelAction::Claude(ClaudeModelFileAction::Restore {
                            original_operation: operation.clone(),
                        })
                    }
                };
                (
                    vec![AgentAccessGrantMutationV1::revoke(
                        WorkspaceId::DEFAULT,
                        reference.connection_id(),
                        reference.generation(),
                    )?],
                    Some(action),
                    Some(reference.clone()),
                )
            }
            AgentFacetIntent::Keep => (Vec::new(), None, None),
        };
        let skill = self.skill_action(preview, preview.spec.skill_facet(), &self.skill_file)?;
        let additional_facet =
            if preview.spec.skill_facet() == hiroute_domain::AgentSettingsFacet::Collaboration {
                hiroute_domain::AgentSettingsFacet::ManagementSkill
            } else {
                hiroute_domain::AgentSettingsFacet::Collaboration
            };
        let additional = match &self.additional_skill_file {
            Some(file) => self.skill_action(preview, additional_facet, file)?,
            None if matches!(
                preview.spec.skill_intent_for(additional_facet),
                AgentFacetIntent::Keep
            ) =>
            {
                SettingsSkillAction::default()
            }
            None => return Err(invalid()),
        };
        // A permitted-plan selection can change without rewriting the shared Skill file: the
        // current root already carries the same template. Its desired collaboration state is
        // still durable in this confirmed settings operation, while Worker callability remains
        // outside this adapter until the directory/metadata owners publish a runtime binding.
        if model_action.is_none()
            && skill.intent.is_none()
            && !skill.record_change
            && additional.intent.is_none()
            && !additional.record_change
            && preview.spec.keeps_skills()
        {
            return Err(invalid());
        }
        let mut mutations = json!({
            "expected_revisions":self.expected_revisions,
            "skill_record_change":skill.record_change,
            "skill_reference_change":&skill.reference_change,
            "collaboration":self.collaboration_state,
        });
        if !matches!(
            preview.spec.skill_intent_for(additional_facet),
            AgentFacetIntent::Keep
        ) {
            mutations["additional_skill_record_change"] = json!(additional.record_change);
            mutations["additional_skill_reference_change"] = json!(&additional.reference_change);
        }
        confirmed.seal_effects_with_skills(
            self.subject.clone(),
            &mutations,
            skill.intent.is_some(),
            additional.intent.is_some(),
            model_mutations,
            |control| {
                let mut external = Vec::new();
                if self
                    .facts
                    .model
                    .as_ref()
                    .is_some_and(|model| model.common.login_item_removal_required)
                {
                    // The last managed connection's restore releases the login item this
                    // feature created in an older version. New connections never create one.
                    let declaration = confirmed.login_item().ok_or_else(invalid)?;
                    external.push(settings_login_item_intent(
                        control,
                        &self.facts.context_id,
                        declaration,
                    )?);
                }
                if let Some(action) = model_action {
                    let file = self.model_file.as_ref().ok_or_else(invalid)?;
                    let model = self.facts.model.as_ref().ok_or_else(invalid)?;
                    match action {
                        SettingsModelAction::Hermes(change) => {
                            let SettingsModelTargetFacts::Hermes { plugins, .. } = &file.target
                            else {
                                return Err(invalid());
                            };
                            if matches!(change, super::HermesModelFileAction::Configure { .. }) {
                                for facts in plugins {
                                    external.push(super::settings_hermes_plugin_file_intent(
                                        control,
                                        &self.facts.context_id,
                                        facts,
                                        &change,
                                    )?);
                                }
                            }
                            external.push(super::settings_hermes_model_file_intent(
                                control,
                                &self.facts.context_id,
                                file.expected_content.clone(),
                                file.before_fingerprint.clone(),
                                change.clone(),
                            )?);
                            if matches!(change, super::HermesModelFileAction::Restore { .. }) {
                                for facts in plugins {
                                    external.push(super::settings_hermes_plugin_file_intent(
                                        control,
                                        &self.facts.context_id,
                                        facts,
                                        &change,
                                    )?);
                                }
                            }
                        }
                        SettingsModelAction::Codex(change) => {
                            if let Some(catalog) =
                                model.codex().and_then(|facts| facts.model_catalog.as_ref())
                            {
                                // The immutable catalog artifact is staged before the managed
                                // configuration so the rendered pointer always has a target.
                                external.push(settings_codex_catalog_intent(
                                    control,
                                    &self.facts.context_id,
                                    catalog,
                                )?);
                            } else if matches!(
                                &preview.spec.model,
                                AgentFacetIntent::Configure { .. }
                            ) {
                                // Every Codex configuration publishes a filtered catalog.
                                return Err(invalid());
                            }
                            external.push(settings_codex_model_file_intent(
                                control,
                                &self.facts.context_id,
                                file.expected_content.clone(),
                                file.before_fingerprint.clone(),
                                change,
                            )?);
                        }
                        SettingsModelAction::Additional(
                            pi_settings_content,
                            additional_dependencies,
                            change,
                        ) => {
                            external.push(super::settings_additional_model_file_intent(
                                control,
                                &self.facts.context_id,
                                file.expected_content.clone(),
                                file.before_fingerprint.clone(),
                                change,
                                pi_settings_content,
                                additional_dependencies,
                            )?);
                        }
                        SettingsModelAction::Claude(change) => {
                            external.push(settings_claude_model_file_intent(
                                control,
                                &self.facts.context_id,
                                file.expected_content.clone(),
                                file.before_fingerprint.clone(),
                                change,
                            )?);
                        }
                    }
                    let publication_digest = file.publication_digest.clone().ok_or_else(invalid)?;
                    external.push(settings_model_publication_intent(
                        control,
                        &self.facts.context_id,
                        publication_digest,
                        restore_grant,
                    )?);
                }
                if let Some(intent) = skill.intent {
                    external.push(intent.render(
                        control,
                        &self.facts.context_id,
                        preview.spec.skill_facet(),
                        &self.skill_file,
                    )?);
                }
                if let Some(intent) = additional.intent {
                    external.push(intent.render(
                        control,
                        &self.facts.context_id,
                        additional_facet,
                        self.additional_skill_file.as_ref().ok_or_else(invalid)?,
                    )?);
                }
                Ok(external)
            },
        )
    }

    fn skill_action(
        &self,
        preview: &AgentSettingsPreview,
        facet: hiroute_domain::AgentSettingsFacet,
        file: &SettingsSkillFileFacts,
    ) -> Result<SettingsSkillAction, OperationValidationError> {
        let invalid = || OperationValidationError::UnregisteredEffectPlan;
        match &preview.spec.skill_intent_for(facet) {
            AgentFacetIntent::Keep => Ok(SettingsSkillAction::default()),
            AgentFacetIntent::Configure { .. } => {
                let plan = plan_skill_install(
                    &file.root_ref,
                    &self.facts.context_id,
                    &file.template,
                    file.before.as_ref(),
                    file.observed_file.as_ref(),
                )
                .map_err(|_| invalid())?;
                let record_change = file.before.as_ref() != Some(&plan.next);
                let (intent, reference_change) = match plan.file_action {
                    SkillFileAction::Install => (Some(SkillIntent::Install(plan)), None),
                    SkillFileAction::Keep if record_change => (
                        None,
                        Some(settings_skill_reference_change(
                            &self.facts.context_id,
                            &file.target,
                            file.before.as_ref(),
                            &plan,
                            file.before_fingerprint.clone(),
                            SkillReferenceAction::Add,
                        )?),
                    ),
                    SkillFileAction::Keep => (None, None),
                    SkillFileAction::Remove | SkillFileAction::Conflict => {
                        return Err(invalid());
                    }
                };
                Ok(SettingsSkillAction {
                    intent,
                    reference_change,
                    record_change,
                })
            }
            AgentFacetIntent::Restore { restore_point_ref } => {
                let current = file.before.as_ref().ok_or_else(invalid)?;
                if self.facts.restore_points.get(restore_point_ref) != Some(&facet) {
                    return Err(invalid());
                }
                let plan =
                    plan_skill_remove(&self.facts.context_id, current, file.observed_file.as_ref())
                        .map_err(|_| invalid())?;
                let record_change = &plan.next != current;
                let (intent, reference_change) = match plan.file_action {
                    SkillFileAction::Remove => (Some(SkillIntent::Remove(plan)), None),
                    SkillFileAction::Keep if record_change => (
                        None,
                        Some(settings_skill_reference_change(
                            &self.facts.context_id,
                            &file.target,
                            Some(current),
                            &plan,
                            file.before_fingerprint.clone(),
                            SkillReferenceAction::Remove,
                        )?),
                    ),
                    SkillFileAction::Keep => (None, None),
                    SkillFileAction::Install | SkillFileAction::Conflict => {
                        return Err(invalid());
                    }
                };
                Ok(SettingsSkillAction {
                    intent,
                    reference_change,
                    record_change,
                })
            }
        }
    }
}

enum SettingsModelAction {
    Hermes(super::HermesModelFileAction),
    Additional(
        Option<CanonicalDigest>,
        Option<CanonicalDigest>,
        super::AdditionalModelFileAction,
    ),
    Codex(CodexModelFileAction),
    Claude(ClaudeModelFileAction),
}

#[derive(Default)]
struct SettingsSkillAction {
    intent: Option<SkillIntent>,
    reference_change: Option<SettingsSkillReferenceChange>,
    record_change: bool,
}

enum SkillIntent {
    Install(SkillOwnershipPlan),
    Remove(SkillOwnershipPlan),
}

impl SkillIntent {
    fn render(
        &self,
        control: &hiroute_domain::AgentConnectionControlIntentV1,
        context_id: &str,
        facet: hiroute_domain::AgentSettingsFacet,
        file: &SettingsSkillFileFacts,
    ) -> Result<hiroute_domain::ExternalEffectIntentV1, OperationValidationError> {
        let (plan, template) = match self {
            Self::Install(plan) => (plan, Some(&file.template)),
            Self::Remove(plan) => (plan, None),
        };
        settings_skill_file_intent_for_facet(
            control,
            context_id,
            facet,
            file.before.as_ref(),
            plan,
            template,
            file.before_fingerprint.clone(),
        )
    }
}

fn claude_model_snapshot(
    settings: &hiroute_domain::AgentModelSelectionV2,
    grant: &hiroute_domain::AgentModelGrantV2,
    facts: &SettingsClaudeModelFacts,
    native_presets: &hiroute_domain::AgentClaudePresetValuesV2,
) -> Result<ClaudeLaunchSnapshotIntent, OperationValidationError> {
    let invalid = || OperationValidationError::UnregisteredEffectPlan;
    let installation = &facts.installation;
    let profile = &installation.profile;
    if installation.agent_id != "agent_claude_default"
        || profile.profile_id != "claude-messages-v1"
        || profile.integration_profile_ref != "builtin/claude-messages/v1"
        || profile.client_protocol() != Some(AgentIngressProtocolV1::Messages)
        || !Path::new(&facts.trusted_hiroute_executable).is_absolute()
    {
        return Err(invalid());
    }
    facts
        .gateway_base_url
        .strip_suffix("/v1")
        .filter(|value| local_gateway_origin(value))
        .ok_or_else(invalid)?;
    let presets = grant
        .claude_preset_values(settings, native_presets)
        .map_err(|_| invalid())?;
    Ok(ClaudeLaunchSnapshotIntent {
        context_window_tokens: None,
        native_presets: native_presets.clone(),
        presets,
        executable: facts.executable.clone().ok_or_else(invalid)?,
        installation_digest: installation.observation_digest.clone(),
    })
}

fn claude_native_change(
    snapshot: &ClaudeLaunchSnapshotIntent,
    facts: &SettingsClaudeModelFacts,
    context_id: &str,
    reconfigure: bool,
) -> Result<hiroute_domain::AgentConfigChangeV1, OperationValidationError> {
    let invalid = || OperationValidationError::UnregisteredEffectPlan;
    let endpoint = facts
        .gateway_base_url
        .strip_suffix("/v1")
        .ok_or_else(invalid)?;
    let connection_id = format!("agent-connection/{context_id}");
    let mut desired = std::collections::BTreeMap::from([
        (
            "apiKeyHelper".to_owned(),
            Some(json!({
                "executable": facts.trusted_hiroute_executable,
                "argv": [hiroute_domain::HIDDEN_AGENT_GRANT_HELPER_VERB_V1, connection_id]
            })),
        ),
        ("hiroute.auth_environment".to_owned(), None),
        ("env.ANTHROPIC_BASE_URL".to_owned(), Some(json!(endpoint))),
    ]);
    for (name, value) in [
        ("OPUS", &snapshot.presets.opus),
        ("SONNET", &snapshot.presets.sonnet),
        ("HAIKU", &snapshot.presets.haiku),
    ] {
        desired.insert(
            format!("env.ANTHROPIC_DEFAULT_{name}_MODEL"),
            value.as_ref().map(|value| json!(value)),
        );
    }
    for key in hiroute_domain::CLAUDE_CONTEXT_ENVIRONMENT {
        if snapshot.context_window_tokens.is_none() && !reconfigure {
            continue;
        }
        desired.insert(
            format!("env.{key}"),
            snapshot
                .context_window_tokens
                .map(|value| json!(value.to_string())),
        );
    }
    hiroute_domain::AgentConfigChangeV1::preview(&facts.user_document, desired)
        .map_err(|_| invalid())
}

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