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.

24.7 KB
Raw Blame
//! Native Codex settings effects in the production Operation composition.
use super::LocalControlAdapter;
use hiroute_application::agent_connection::{
    CodexCatalogProducerKindV1, CodexModelFileAction, decode_settings_codex_catalog,
    settings_codex_model_file_for_operation,
};
use hiroute_domain::{
    AgentAccessGrantRefV1, AgentIngressProtocolV1, AgentModelDefaultSelectionV2, AgentModelRouteV2,
    AgentModelSelectionV2, CanonicalDigest, CodexNativeModelModeV2, ControlRepositoryPort,
    EffectReconciliation, ExternalEffectIntentV1, GatewayPublicationV1, NativeAgentArtifactPort,
    OperationId, OperationState, OperationStepKind, OwnedEffectV1, PortError, PortErrorCode,
    PortResult, SecretStorePort, WorkspaceId, is_agent_access_grant_effect,
};
use hiroute_integrations::{
    CodexCatalogBaseline, CodexCatalogError, CodexDefaultPolicy, CodexFileConfiguration,
    CodexSelectionTarget, codex_catalog_baseline as decode_catalog_baseline, restage_codex_catalog,
    sample_codex_catalog_plan, sample_codex_hiroute_only_catalog_plan, stage_codex_catalog,
    stage_codex_configuration, stage_codex_reconfiguration, stage_codex_restoration,
};

pub(super) fn is_settings_codex_model(intent: &ExternalEffectIntentV1) -> bool {
    intent.effect_id() == "agent-connection-managed-configuration"
        && intent.desired()["transaction"] == "settings"
        && intent.desired()["subject"]["agent_id"] == "agent_codex_default"
}

pub(super) fn is_settings_codex_catalog(intent: &ExternalEffectIntentV1) -> bool {
    intent.effect_id() == "agent-connection-model-catalog"
        && intent.desired()["transaction"] == "settings"
        && intent.desired()["subject"]["agent_id"] == "agent_codex_default"
}

/// The catalog baseline of the active managed edit: the user's pre-management pointer, so a
/// reconfiguration never appends plans onto a previous HiRoute catalog artifact.
pub(super) fn codex_catalog_baseline(
    control: &dyn ControlRepositoryPort,
    artifacts: &dyn NativeAgentArtifactPort,
    previous: Option<&OperationId>,
    model_target: &str,
) -> PortResult<CodexCatalogBaseline> {
    let Some(previous) = previous else {
        return Ok(CodexCatalogBaseline::Scope);
    };
    let operation = control
        .load_operation(previous)?
        .ok_or_else(|| conflict("codex.catalog.previous.operation"))?;
    let intent = operation
        .plan
        .external()
        .iter()
        .find(|candidate| is_settings_codex_model(candidate) && candidate.target() == model_target)
        .ok_or_else(|| conflict("codex.catalog.previous.intent"))?;
    let record = artifacts
        .load_native_restore(previous, intent)?
        .ok_or_else(|| conflict("codex.catalog.previous.record"))?;
    decode_catalog_baseline(&record).map_err(|_| conflict("codex.catalog.previous.baseline"))
}

/// Deterministic derivation of the merged catalog from a plan-carrying selection: the same
/// publication, plan order and default policy seal, stage and recovery all share.
pub(super) fn codex_catalog_plan_for(
    user_config: &std::path::Path,
    settings: &AgentModelSelectionV2,
    publication: &GatewayPublicationV1,
    baseline: &CodexCatalogBaseline,
) -> Result<hiroute_integrations::CodexCatalogPlan, CodexCatalogError> {
    let AgentModelSelectionV2::CodexDefault {
        default_selection,
        native_model_mode,
        fixed_models,
        ..
    } = settings
    else {
        return Err(CodexCatalogError::InvalidCatalog);
    };
    let allowed = settings.allowed_plan_ids();
    let plans: Vec<_> = allowed
        .iter()
        .filter_map(|plan_id| {
            publication
                .plans
                .iter()
                .find(|plan| plan.agent_plan_id() == plan_id)
                .cloned()
        })
        .collect();
    if plans.len() != allowed.len() {
        return Err(CodexCatalogError::InvalidCatalog);
    }
    let published = publication
        .published_agent_plans()
        .map_err(|_| CodexCatalogError::InvalidCatalog)?;
    let explicit_model = match default_selection {
        AgentModelDefaultSelectionV2::PreserveNative => None,
        AgentModelDefaultSelectionV2::FixedModel { client_model_id } => {
            Some(client_model_id.clone())
        }
        AgentModelDefaultSelectionV2::Plan { plan_id } => published
            .iter()
            .find(|plan| &plan.agent_plan_id == plan_id)
            .map(|plan| plan.model_alias.as_str().to_owned()),
    };
    let policy = CodexDefaultPolicy {
        explicit_model: explicit_model.as_deref(),
        // The client keeps its native subscription auth; subscription-only entries stay eligible.
        uses_codex_backend: true,
        allow_provider_model_fallback: false,
    };
    let scope = hiroute_integrations::CodexConfigurationScope::user_file(user_config.to_owned());
    if *native_model_mode == CodexNativeModelModeV2::HirouteOnly && fixed_models.is_empty() {
        return sample_codex_hiroute_only_catalog_plan(
            &scope,
            &plans,
            explicit_model
                .as_deref()
                .ok_or(CodexCatalogError::MissingDefault)?,
        );
    }
    let retained = settings
        .fixed_models()
        .iter()
        .map(|model| model.client_model_id.clone())
        .collect();
    sample_codex_catalog_plan(&scope, &plans, policy, baseline, Some(&retained))
}

impl LocalControlAdapter {
    pub(super) fn acknowledge_clean_codex_restoration(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<()> {
        if !is_settings_codex_model(intent)
            || operation
                .step(OperationStepKind::Activate)
                .terminal_result
                .as_deref()
                .and_then(hiroute_domain::SettingsServiceCompletionV1::parse)
                .is_none()
        {
            return Ok(());
        }
        let state = self
            .artifacts
            .observe_artifact(&operation.operation_id, intent)?;
        if !matches!(
            state,
            EffectReconciliation::Missing | EffectReconciliation::OwnershipLost(_)
        ) {
            return Ok(());
        }
        self.require_current_operation(operation)?;
        let payload = settings_codex_model_file_for_operation(operation, intent)?;
        let CodexModelFileAction::Restore {
            original_operation,
            native_model,
        } = payload.change
        else {
            return Ok(());
        };
        let stores = self.stores_lock()?;
        let original = stores
            .control()
            .load_operation(&original_operation)?
            .ok_or_else(|| conflict("codex.restore.ack.original"))?;
        if original.workspace_id != operation.workspace_id
            || original.state != OperationState::Succeeded
        {
            return Err(conflict("codex.restore.ack.owner"));
        }
        let original_intent = original
            .plan
            .external()
            .iter()
            .find(|i| is_settings_codex_model(i) && i.target() == intent.target())
            .ok_or_else(|| conflict("codex.restore.ack.intent"))?;
        let before = settings_codex_model_file_for_operation(&original, original_intent)?;
        if before.context_id != payload.context_id
            || !matches!(before.change, CodexModelFileAction::Configure { .. })
        {
            return Err(conflict("codex.restore.ack.context"));
        }
        drop(stores);
        let record = self
            .artifacts
            .load_native_restore(&original_operation, original_intent)?
            .ok_or_else(|| conflict("codex.restore.ack.record"))?;
        if record.len() < 3 || record[0] != 1 || record[1] > 1 {
            return Err(conflict("codex.restore.ack.schema"));
        }
        let restore = hiroute_integrations::CodexNativeRestore::decode_protected(&record[2..])
            .map_err(|_| conflict("codex.restore.ack.decode"))?;
        let current = self.artifacts.read_native_target(intent.target())?;
        let text = std::str::from_utf8(current.as_deref().map_or(&[], |b| b.as_slice()))
            .map_err(|_| conflict("codex.restore.ack.encoding"))?;
        let restored = hiroute_integrations::restore_codex_native_with_model(
            text,
            &restore,
            native_model.as_deref(),
        )
        .map_err(|_| conflict("codex.restore.ack.fields"))?;
        // Only acknowledge complete cleanup. Remaining owned fields require user repair;
        // neither comments nor unrelated edits are overwritten or rebased by this path.
        if restored.as_str() != text {
            // A first deferred preparation still needs to render and stage restoration.
            if matches!(state, EffectReconciliation::Missing) {
                return Ok(());
            }
            return Err(conflict("codex.restore.ack.incomplete"));
        }
        self.artifacts.acknowledge_native_restoration(
            &operation.operation_id,
            intent,
            current.as_deref().map(|b| b.as_slice()),
        )?;
        Ok(())
    }

    pub(super) fn stage_settings_codex_catalog(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<OwnedEffectV1> {
        let payload = decode_settings_codex_catalog(intent)?;
        let stores = self.stores_lock()?;
        let operation_id = &operation.operation_id;
        if operation.state != OperationState::ApplyingAgentArtifacts {
            return Err(conflict("codex.catalog.phase"));
        }
        let spec: hiroute_application_api::AgentSettingsSpecV2 =
            serde_json::from_value(operation.plan.spec().desired_state.clone())
                .map_err(|_| conflict("codex.catalog.spec"))?;
        let settings = match &spec.model {
            hiroute_application_api::AgentFacetIntent::Configure { settings } => settings,
            _ => return Err(conflict("codex.catalog.spec.model")),
        };
        if !matches!(settings, AgentModelSelectionV2::CodexDefault { .. }) {
            return Err(conflict("codex.catalog.spec.model"));
        }
        if operation.plan.spec().command_id != "agents.settings.apply"
            || spec.context_id != payload.context_id
            || !operation.plan.external().contains(intent)
        {
            return Err(conflict("codex.catalog.binding"));
        }
        let model_intent = operation
            .plan
            .external()
            .iter()
            .find(|candidate| is_settings_codex_model(candidate))
            .ok_or_else(|| conflict("codex.catalog.model.intent"))?;
        let model_payload = settings_codex_model_file_for_operation(operation, model_intent)?;
        let CodexModelFileAction::Configure {
            previous_operation,
            model_catalog: Some(expected),
            ..
        } = &model_payload.change
        else {
            return Err(conflict("codex.catalog.model.binding"));
        };
        if &payload.content_digest != expected {
            return Err(conflict("codex.catalog.digest.binding"));
        }
        let publication_intent = operation
            .plan
            .external()
            .iter()
            .find(|candidate| candidate.kind() == hiroute_domain::OwnedEffectKind::Publication)
            .ok_or_else(|| conflict("codex.catalog.publication.intent"))?
            .clone();
        let mut baseline = codex_catalog_baseline(
            stores.control(),
            &self.artifacts,
            previous_operation.as_ref(),
            model_intent.target(),
        )?;
        if self.settings_agent_for_context(&payload.context_id)
            == Some(super::settings_facts::SettingsAgentClass::CodexProfile)
        {
            baseline = CodexCatalogBaseline::Scope;
        }
        drop(stores);
        let publication = self
            .publication_record_from_operation(operation, &publication_intent)?
            .verify()
            .map_err(|_| conflict("codex.catalog.publication.verify"))?;
        // Recovery first: a staged artifact or protected restore bytes never re-derives the
        // catalog, so a changed user baseline cannot invalidate an already staged artifact.
        match restage_codex_catalog(&self.artifacts, operation_id, intent) {
            Ok(effect) => return Ok(effect),
            Err(error) if error.code != PortErrorCode::InvalidData => return Err(error),
            Err(_) => {}
        }
        let derived = codex_catalog_plan_for(
            &self.scanner.codex_user_config_target(),
            settings,
            &publication,
            &baseline,
        )
        .map_err(|_| conflict("codex.catalog.context_drift"))?;
        let producer_kind = match derived.producer.metadata_source {
            hiroute_integrations::CodexCatalogMetadataSourceV1::UserConfigured => {
                CodexCatalogProducerKindV1::UserConfigured
            }
            hiroute_integrations::CodexCatalogMetadataSourceV1::TargetCache => {
                CodexCatalogProducerKindV1::TargetCache
            }
            hiroute_integrations::CodexCatalogMetadataSourceV1::TargetBundled => {
                CodexCatalogProducerKindV1::TargetBundled
            }
            hiroute_integrations::CodexCatalogMetadataSourceV1::HirouteGenerated => {
                CodexCatalogProducerKindV1::HirouteGenerated
            }
        };
        if payload.source_revision != hiroute_integrations::CODEX_CATALOG_SOURCE_REVISION
            || payload.content_digest != derived.content_digest
            || payload.producer_kind != producer_kind
            || derived.producer.path.to_str() != Some(payload.producer_path.as_str())
            || payload.producer_content_digest != derived.producer.content_digest
            || payload.producer_context_digest != derived.producer.context_digest
            || payload.producer_dependency_digest != derived.producer.dependency_digest
        {
            return Err(conflict("codex.catalog.context_drift"));
        }
        stage_codex_catalog(&self.artifacts, operation_id, intent, &derived.selection)
    }

    pub(super) fn stage_settings_codex_model(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<OwnedEffectV1> {
        let stores = self.stores_lock()?;
        let operation_id = &operation.operation_id;
        let payload = settings_codex_model_file_for_operation(operation, intent)?;
        let restoration_tail = operation.state == OperationState::Activating
            && matches!(&payload.change, CodexModelFileAction::Restore { .. })
            && operation
                .step(OperationStepKind::Activate)
                .terminal_result
                .as_deref()
                .and_then(hiroute_domain::SettingsServiceCompletionV1::parse)
                .is_some();
        if operation.state != OperationState::ApplyingAgentArtifacts && !restoration_tail {
            return Err(conflict("codex.settings.phase"));
        }
        match &payload.change {
            CodexModelFileAction::Configure {
                previous_operation,
                provider_id,
                endpoint,
                model,
                model_catalog,
            } => {
                let mutation = operation
                    .plan
                    .agent_access_grants()
                    .first()
                    .filter(|_| operation.plan.agent_access_grants().len() == 1)
                    .ok_or_else(|| conflict("codex.settings.grant"))?;
                let scope = mutation
                    .desired_scope()
                    .ok_or_else(|| conflict("codex.settings.scope"))?;
                if mutation.owner_scope() != operation.workspace_id.as_str()
                    || scope.connection_id() != format!("agent-connection/{}", payload.context_id)
                    || scope.protocol() != AgentIngressProtocolV1::Responses
                    || model
                        .as_deref()
                        .is_some_and(|name| !scope.model_grant().permits_name(name))
                {
                    return Err(conflict("codex.settings.grant.binding"));
                }
                let runtime = self
                    .managed_agent_runtime
                    .lock()
                    .map_err(|_| conflict("codex.settings.runtime.lock"))?;
                if runtime
                    .as_ref()
                    .is_none_or(|runtime| runtime.gateway_base_url != *endpoint)
                {
                    return Err(conflict("codex.settings.endpoint.changed"));
                }
                drop(runtime);
                let active = stores
                    .secrets()
                    .inspect_agent_access_grant(WorkspaceId::DEFAULT, scope.connection_id())?;
                let previous = if let Some(previous_operation) = previous_operation {
                    let previous = stores
                        .control()
                        .load_operation(previous_operation)?
                        .ok_or_else(|| conflict("codex.settings.previous.operation"))?;
                    if previous.workspace_id != operation.workspace_id
                        || previous.state != OperationState::Succeeded
                    {
                        return Err(conflict("codex.settings.previous.owner"));
                    }
                    let previous_intent = previous
                        .plan
                        .external()
                        .iter()
                        .find(|candidate| {
                            candidate.target() == intent.target()
                                && is_settings_codex_model(candidate)
                        })
                        .ok_or_else(|| conflict("codex.settings.previous.effect"))?
                        .clone();
                    let previous_payload =
                        settings_codex_model_file_for_operation(&previous, &previous_intent)?;
                    let CodexModelFileAction::Configure {
                        provider_id: previous_provider,
                        ..
                    } = previous_payload.change
                    else {
                        return Err(conflict("codex.settings.previous.action"));
                    };
                    let [previous_mutation] = previous.plan.agent_access_grants() else {
                        return Err(conflict("codex.settings.previous.grant"));
                    };
                    let previous_effect = previous
                        .step(OperationStepKind::ApplySecrets)
                        .effects
                        .iter()
                        .find(|effect| is_agent_access_grant_effect(effect))
                        .ok_or_else(|| conflict("codex.settings.previous.grant.effect"))?;
                    let previous_reference = AgentAccessGrantRefV1::from_ensure_effect(
                        previous_effect,
                        previous_mutation,
                    )
                    .map_err(|_| conflict("codex.settings.previous.grant.reference"))?;
                    if previous_provider != *provider_id
                        || active.as_ref() != Some(&previous_reference)
                        || previous_reference.generation() != mutation.expected_generation()
                    {
                        return Err(conflict("codex.settings.previous.binding"));
                    }
                    Some((previous, previous_intent))
                } else {
                    if active.is_some() {
                        return Err(conflict("codex.settings.previous.missing"));
                    }
                    None
                };
                let material = stores
                    .secrets()
                    .resolve_prepared_agent_access_grant(operation_id, mutation)?;
                drop(stores);
                let managed_aliases = scope
                    .model_grant()
                    .routes
                    .iter()
                    .filter(|(_, route)| matches!(route, AgentModelRouteV2::Plan { .. }))
                    .map(|(alias, _)| alias.clone())
                    .collect::<Vec<_>>();
                // The immutable catalog artifact this configuration points at; its absolute
                // path is resolved only through the trusted artifact port during rendering.
                let model_catalog_target = match model_catalog.as_ref() {
                    Some(digest) => Some(
                        operation
                            .plan
                            .external()
                            .iter()
                            .find(|candidate| {
                                decode_settings_codex_catalog(candidate)
                                    .is_ok_and(|catalog| &catalog.content_digest == digest)
                            })
                            .ok_or_else(|| conflict("codex.settings.catalog.binding"))?
                            .target()
                            .to_owned(),
                    ),
                    None => None,
                };
                let configuration = CodexFileConfiguration {
                    expected_content: &payload.expected_content,
                    selection: CodexSelectionTarget::Root,
                    provider_id,
                    endpoint,
                    model: model.as_deref(),
                    local_grant: &material,
                    model_catalog: model_catalog_target.as_deref(),
                    managed_aliases: &managed_aliases,
                };
                match &previous {
                    Some((previous, previous_intent)) => stage_codex_reconfiguration(
                        &self.artifacts,
                        operation_id,
                        intent,
                        &previous.operation_id,
                        previous_intent,
                        configuration,
                    ),
                    None => stage_codex_configuration(
                        &self.artifacts,
                        operation_id,
                        intent,
                        configuration,
                    ),
                }
            }
            CodexModelFileAction::Restore {
                original_operation,
                native_model,
            } => {
                let original = stores
                    .control()
                    .load_operation(original_operation)?
                    .ok_or_else(|| conflict("codex.settings.restore.original"))?;
                if original.workspace_id != operation.workspace_id
                    || original.state != OperationState::Succeeded
                {
                    return Err(conflict("codex.settings.restore.owner"));
                }
                let original_intent = original
                    .plan
                    .external()
                    .iter()
                    .find(|original| {
                        original.target() == intent.target() && is_settings_codex_model(original)
                    })
                    .ok_or_else(|| conflict("codex.settings.restore.effect"))?;
                let before = settings_codex_model_file_for_operation(&original, original_intent)?;
                if before.context_id != payload.context_id
                    || !matches!(before.change, CodexModelFileAction::Configure { .. })
                {
                    return Err(conflict("codex.settings.restore.context"));
                }
                drop(stores);
                match self.artifacts.observe_artifact(operation_id, intent)? {
                    EffectReconciliation::Staged(effect)
                    | EffectReconciliation::Applied(effect) => return Ok(effect),
                    EffectReconciliation::OwnershipLost(_) => {
                        return Err(conflict("codex.settings.restore.ownership"));
                    }
                    EffectReconciliation::Missing => {}
                }
                // Enforce the confirmed whole-file snapshot before field restoration. The store
                // checks ownership again at activation; unrelated later edits need a new Preview.
                let bytes = self.artifacts.read_native_target(intent.target())?;
                if CanonicalDigest::of_bytes(bytes.as_deref().map_or(&[], |bytes| bytes.as_slice()))
                    != payload.expected_content
                {
                    return Err(conflict("codex.settings.restore.changed"));
                }
                stage_codex_restoration(
                    &self.artifacts,
                    operation_id,
                    intent,
                    original_operation,
                    original_intent,
                    native_model.as_deref(),
                )
            }
        }
    }
}
fn conflict(context: &'static str) -> PortError {
    PortError::new(PortErrorCode::Conflict, context)
}

#[cfg(all(test, unix))]
#[path = "native_model_tests.rs"]
mod tests;