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
//! External-effect composition for production Local Control.
//!
//! The filesystem scanner owns the one mode-only remediation. Product publications are staged
//! and activated in `control.db`; all remaining Agent artifacts use the managed-artifact store.

use hiroute_domain::{
    AgentConfigChangeV1, CanonicalDigest, CompensationOutcome, ControlRepositoryPort,
    EffectReconciliation, ExternalEffectIntentV1, ExternalEffectPort, NativeAgentArtifactPort,
    OperationId, OperationStepKind, OperationStepStatus, OwnedEffectKind, OwnedEffectV1, PortError,
    PortErrorCode, PortResult,
};
use hiroute_integrations::{PermissionHardeningOutcomeV1, PermissionHardeningRequiredV1};
use serde::{Deserialize, Serialize};

use super::LocalControlAdapter;
use super::publication::PUBLICATION_TARGET;

const EFFECT_SCHEMA: &str = "hiroute.agent-config-permission-effect/v1";
const EFFECT_ID: &str = "agent-config-permission-hardening";
const TARGET_PREFIX: &str = "scanner-source/";
const SOURCE_PREFIX: &str = "claude/settings/";
const REQUIRED_MODE: u32 = 0o600;
const AGENT_MANAGED_CONFIGURATION_EFFECT_ID: &str = "agent-connection-managed-configuration";

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct AgentConfigurationEnvelopeV1 {
    schema: String,
    transaction: String,
    subject: AgentConfigurationSubjectV1,
    change_spec_digest: CanonicalDigest,
    role: String,
    payload_digest: CanonicalDigest,
    payload: serde_json::Value,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct AgentConfigurationSubjectV1 {
    agent_id: String,
    profile_id: String,
    integration_profile_ref: String,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ApplyAgentConfigurationPayloadV1 {
    profile_id: String,
    change: AgentConfigChangeV1,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct PermissionEnvelopeV1 {
    schema: String,
    transaction: String,
    intent: PermissionIntentV1,
    change_spec_digest: CanonicalDigest,
}

#[derive(Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct PermissionIntentV1 {
    scanner_id: String,
    scanner_version: String,
    source_ref: String,
    observed_identity: CanonicalDigest,
    observed_revision: u64,
    required_mode: u32,
}

#[derive(Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct PermissionEffectMarkerV1 {
    schema: String,
    operation_id: String,
    intent: PermissionIntentV1,
}

impl PermissionIntentV1 {
    fn finding(&self) -> PermissionHardeningRequiredV1 {
        PermissionHardeningRequiredV1 {
            scanner_id: self.scanner_id.clone(),
            scanner_version: self.scanner_version.clone(),
            discovered_source_ref: self.source_ref.clone(),
            observed_identity: self.observed_identity.clone(),
            observed_revision: self.observed_revision,
            // Scanner resolution is exclusively by the opaque source ref. This label never
            // becomes a filesystem locator.
            display_path: "Claude settings".to_owned(),
            required_mode: self.required_mode,
        }
    }
}

impl LocalControlAdapter {
    pub(super) fn native_claude_change(
        &self,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<Option<AgentConfigChangeV1>> {
        if intent.effect_id() != AGENT_MANAGED_CONFIGURATION_EFFECT_ID {
            return Ok(None);
        }
        if super::native_model::is_settings_codex_model(intent) {
            hiroute_application::agent_connection::decode_settings_codex_model_file(intent)?;
            return Ok(None);
        }
        if super::native_claude_model::is_settings_claude_model(intent) {
            hiroute_application::agent_connection::decode_settings_claude_model_file(intent)?;
            return Ok(None);
        }
        if super::native_additional_model::is_settings_additional_model(intent) {
            hiroute_application::agent_connection::decode_settings_additional_model_file(intent)?;
            return Ok(None);
        }
        if hiroute_application::agent_connection::is_settings_hermes_model(intent) {
            hiroute_application::agent_connection::decode_settings_hermes_model_file(intent)?;
            return Ok(None);
        }
        let envelope: AgentConfigurationEnvelopeV1 =
            serde_json::from_value(intent.desired().clone())
                .map_err(|_| invalid("agent-config.intent.decode"))?;
        let expected_payload_digest = CanonicalDigest::of(&envelope.payload)
            .map_err(|_| invalid("agent-config.intent.digest"))?;
        if envelope.schema != "hiroute.agent-connection-effect/v1"
            || envelope.role != "managed_configuration"
            || envelope.transaction != "apply"
            || envelope.subject.agent_id != "agent_claude_default"
            || envelope.subject.profile_id != "claude-messages-v1"
            || envelope.subject.integration_profile_ref != "builtin/claude-messages/v1"
            || envelope.payload_digest != expected_payload_digest
            || CanonicalDigest::parse(envelope.change_spec_digest.as_str().to_owned()).is_err()
            || intent.desired_mode() != 0o600
        {
            return Err(invalid("agent-config.intent.shape"));
        }
        let payload: ApplyAgentConfigurationPayloadV1 = serde_json::from_value(envelope.payload)
            .map_err(|_| invalid("agent-config.payload.decode"))?;
        if payload.profile_id != envelope.subject.profile_id {
            return Err(invalid("agent-config.payload.profile"));
        }
        payload
            .change
            .validate()
            .map_err(|_| invalid("agent-config.payload.change"))?;
        Ok(Some(payload.change))
    }

    fn permission_intent(
        &self,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<Option<PermissionIntentV1>> {
        if intent.effect_id() != EFFECT_ID {
            return Ok(None);
        }
        let envelope: PermissionEnvelopeV1 = serde_json::from_value(intent.desired().clone())
            .map_err(|_| invalid("permission.intent.decode"))?;
        let suffix = envelope
            .intent
            .source_ref
            .strip_prefix(SOURCE_PREFIX)
            .ok_or_else(|| invalid("permission.intent.source"))?;
        if envelope.schema != EFFECT_SCHEMA
            || envelope.transaction != "harden"
            || envelope.intent.scanner_id != "builtin.agent-filesystem"
            || envelope.intent.scanner_version != "1"
            || envelope.intent.observed_revision == 0
            || envelope.intent.required_mode != REQUIRED_MODE
            || suffix.len() != 32
            || !suffix.bytes().all(|byte| byte.is_ascii_hexdigit())
            || intent.kind() != OwnedEffectKind::AgentArtifact
            || intent.target() != format!("{TARGET_PREFIX}{}", envelope.intent.source_ref)
            || intent.before_fingerprint() != Some(&envelope.intent.observed_identity)
            || intent.desired_mode() != REQUIRED_MODE
            || intent.sensitive()
        {
            return Err(invalid("permission.intent.shape"));
        }
        // Deserializing the digest is intentional validation even though the adapter does not
        // interpret it; the typed domain planner has already bound it to the ChangeSpec.
        let _ = envelope.change_spec_digest;
        Ok(Some(envelope.intent))
    }

    fn permission_effect(
        operation_id: &OperationId,
        intent: &PermissionIntentV1,
    ) -> PortResult<OwnedEffectV1> {
        Ok(OwnedEffectV1 {
            effect_id: EFFECT_ID.to_owned(),
            kind: OwnedEffectKind::AgentArtifact,
            target: format!("{TARGET_PREFIX}{}", intent.source_ref),
            before_fingerprint: Some(intent.observed_identity.clone()),
            // Mode-only remediation preserves file identity.
            after_fingerprint: Some(intent.observed_identity.clone()),
            compensation: serde_json::to_value(PermissionEffectMarkerV1 {
                schema: "hiroute.agent-config-permission-marker/v1".to_owned(),
                operation_id: operation_id.to_string(),
                intent: intent.clone(),
            })
            .map_err(|_| invalid("permission.effect.encode"))?
            .into(),
        })
    }

    fn permission_marker(
        &self,
        effect: &OwnedEffectV1,
    ) -> PortResult<(OperationId, PermissionIntentV1)> {
        let marker: PermissionEffectMarkerV1 =
            serde::Deserialize::deserialize(effect.compensation.as_ref())
                .map_err(|_| invalid("permission.effect.decode"))?;
        let operation_id = OperationId::parse(marker.operation_id)
            .map_err(|_| invalid("permission.effect.operation"))?;
        if marker.schema != "hiroute.agent-config-permission-marker/v1"
            || effect.effect_id != EFFECT_ID
            || effect.kind != OwnedEffectKind::AgentArtifact
            || effect.target != format!("{TARGET_PREFIX}{}", marker.intent.source_ref)
            || effect.before_fingerprint.as_ref() != Some(&marker.intent.observed_identity)
            || effect.after_fingerprint.as_ref() != Some(&marker.intent.observed_identity)
        {
            return Err(invalid("permission.effect.shape"));
        }
        Ok((operation_id, marker.intent))
    }

    fn verify_or_harden(
        &self,
        intent: &PermissionIntentV1,
    ) -> PortResult<PermissionHardeningOutcomeV1> {
        self.scanner
            .harden_discovered_permissions(&intent.finding())
            .map_err(|_| PortError::new(PortErrorCode::Conflict, "permission.identity.changed"))
    }
}

impl ExternalEffectPort for LocalControlAdapter {
    fn install_source_price_snapshot(
        &self,
        operation: &hiroute_domain::OperationV1,
    ) -> PortResult<hiroute_domain::PriceGenerationRefV1> {
        self.install_committed_price_snapshot(operation)
    }

    fn prepare_agent_artifact_activation(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<()> {
        self.acknowledge_clean_codex_restoration(operation, intent)?;
        if super::native_additional_model::is_settings_additional_model(intent) {
            self.validate_additional_model_dependencies(operation, intent)?;
        }
        if hiroute_application::agent_connection::is_settings_hermes_model(intent) {
            self.validate_hermes_model_dependencies(operation, intent)?;
        }
        if hiroute_application::agent_connection::is_settings_skill_file(intent)
            && intent.desired()["transaction"] == "settings"
        {
            let stores = self.stores_lock()?;
            if !stores.control().operation_is_current(operation)? {
                return Err(invalid("skill.activation.binding"));
            }
            hiroute_application::agent_connection::persist_settings_skill_file_record(
                stores.control(),
                &self.artifacts,
                operation,
                intent,
            )?;
        }
        Ok(())
    }
    fn validate_external_admission(&self, intent: &ExternalEffectIntentV1) -> PortResult<()> {
        if self.validate_subscription_effect(intent)? {
            return Ok(());
        }
        if intent
            .desired()
            .get("transaction")
            .and_then(serde_json::Value::as_str)
            == Some("settings")
            && hiroute_application::agent_connection::is_settings_skill_file(intent)
        {
            hiroute_application::agent_connection::validate_settings_skill_file_intent(intent)?;
        }
        // Resolve known native adapters before a capability is consumed or an Operation exists.
        self.native_claude_change(intent)?;
        if hiroute_application::agent_connection::is_settings_hermes_plugin(intent) {
            hiroute_application::agent_connection::decode_settings_hermes_plugin_file(intent)?;
        }
        self.permission_intent(intent)?;
        self.validate_publication_admission(intent)
    }
    fn begin_publication_activation(
        &self,
        operation: &hiroute_domain::OperationV1,
    ) -> PortResult<()> {
        self.begin_product_activation(operation)
    }
    fn prepare_publication_activation(
        &self,
        operation: &hiroute_domain::OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1> {
        self.publication_install_checkpoint(operation, effect)
    }
    fn prepare_publication_rollback(
        &self,
        operation: &hiroute_domain::OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1> {
        self.publication_abort_checkpoint(operation, effect)
    }
    fn finish_publication_activation(
        &self,
        operation: &hiroute_domain::OperationV1,
    ) -> PortResult<()> {
        self.finish_product_activation(operation)?;
        if operation.state != hiroute_domain::OperationState::Succeeded {
            return Ok(());
        }
        for intent in operation.plan.external() {
            if hiroute_application::agent_connection::is_settings_hermes_plugin(intent)
                && matches!(hiroute_application::agent_connection::settings_hermes_plugin_file_for_operation(operation, intent)?.change, hiroute_application::agent_connection::HermesPluginFileAction::Restore { .. })
                && self.artifacts.read_native_target(intent.target())?.is_none() {
                self.artifacts.cleanup_native_parents(&operation.operation_id, intent)?;
            }
            if hiroute_application::agent_connection::is_settings_skill_file(intent)
                && intent.desired()["transaction"] == "settings"
                && intent.desired()["payload"]["action"] == "remove"
            {
                let (_, record) =
                    hiroute_application::agent_connection::settings_skill_file_record(
                        &operation.operation_id,
                        intent,
                    )?;
                let actual = self
                    .stores_lock()?
                    .control()
                    .skill_installation(&operation.workspace_id, &record.root_ref)?;
                if actual.as_ref() != Some(&record) {
                    return Err(invalid("skill.cleanup.record.binding"));
                }
                hiroute_application::agent_connection::finish_collaboration_skill_removal(
                    &self.artifacts,
                    &operation.operation_id,
                    intent,
                    &record,
                )?;
            }
        }
        Ok(())
    }
    fn current_external_fingerprint(&self, target: &str) -> PortResult<Option<CanonicalDigest>> {
        if target.starts_with("compute-subscription/") {
            return self.current_subscription_fingerprint(target);
        }
        if target == PUBLICATION_TARGET {
            return self.current_publication_fingerprint();
        }
        if let Some(source_ref) = target.strip_prefix(TARGET_PREFIX) {
            return Ok(self
                .permission_findings
                .lock()
                .map_err(|_| PortError::new(PortErrorCode::Unavailable, "permission.cache.lock"))?
                .get(source_ref)
                .map(|finding| finding.observed_identity.clone()));
        }
        self.artifacts.current_external_fingerprint(target)
    }

    fn apply_external(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<OwnedEffectV1> {
        self.require_current_operation(operation)?;
        let operation_id = &operation.operation_id;
        if !operation.plan.external().contains(intent) {
            return Err(invalid("effect.intent-binding"));
        }
        if let Some(effect) = self.apply_subscription_effect(operation_id, intent)? {
            return Ok(effect);
        }
        if intent
            .desired()
            .get("transaction")
            .and_then(serde_json::Value::as_str)
            == Some("settings")
            && hiroute_application::agent_connection::is_settings_skill_file(intent)
        {
            return hiroute_application::agent_connection::stage_settings_skill_file(
                &self.artifacts,
                operation_id,
                intent,
            );
        }
        if intent.kind() == OwnedEffectKind::Publication {
            return self.apply_publication(operation, intent);
        }
        if super::native_model::is_settings_codex_catalog(intent) {
            return self.stage_settings_codex_catalog(operation, intent);
        }
        if hiroute_application::agent_connection::is_settings_login_item(intent) {
            // The host executed this action under the native confirmation before the Operation
            // was admitted; the daemon only journals the observed before/after evidence.
            return hiroute_application::agent_connection::settings_login_item_effect(intent);
        }
        if super::native_model::is_settings_codex_model(intent) {
            return self.stage_settings_codex_model(operation, intent);
        }
        if super::native_claude_model::is_settings_claude_model(intent) {
            return self.stage_settings_claude_model(operation, intent);
        }
        if super::native_additional_model::is_settings_additional_model(intent) {
            return self.stage_settings_additional_model(operation, intent);
        }
        if hiroute_application::agent_connection::is_settings_hermes_model(intent) {
            return self.stage_settings_hermes_model(operation, intent);
        }
        if hiroute_application::agent_connection::is_settings_hermes_plugin(intent) {
            return self.stage_settings_hermes_plugin(operation, intent);
        }
        let Some(permission) = self.permission_intent(intent)? else {
            if let Some(change) = self.native_claude_change(intent)? {
                let rendered = self
                    .scanner
                    .render_claude_user_config_change(&change)
                    .map_err(|_| {
                        PortError::new(PortErrorCode::Conflict, "agent-config.source.changed")
                    })?;
                return self
                    .artifacts
                    .apply_rendered_external(operation_id, intent, &rendered);
            }
            return self.artifacts.apply_artifact(operation_id, intent);
        };
        let outcome = self.verify_or_harden(&permission)?;
        // Apply is the first point allowed to make content readable. Re-scan now both removes
        // the one-shot mode finding and registers the exact Secret descriptor for the following
        // journal step; bytes still remain inside the protected-input adapter.
        self.refresh_discovery()
            .map_err(|_| PortError::new(PortErrorCode::Unavailable, "permission.rescan"))?;
        match outcome {
            PermissionHardeningOutcomeV1::Hardened
            | PermissionHardeningOutcomeV1::AlreadyHardened => {
                Self::permission_effect(operation_id, &permission)
            }
        }
    }

    fn observe_external(
        &self,
        operation: &hiroute_domain::OperationV1,
        intent: &ExternalEffectIntentV1,
    ) -> PortResult<EffectReconciliation> {
        self.require_current_operation(operation)?;
        let operation_id = &operation.operation_id;
        if !operation.plan.external().contains(intent) {
            return Err(invalid("effect.intent-binding"));
        }
        if let Some(reconciliation) = self.observe_subscription_effect(operation_id, intent)? {
            return Ok(reconciliation);
        }
        if intent.kind() == OwnedEffectKind::Publication {
            return self.observe_publication(operation, intent);
        }
        if hiroute_application::agent_connection::is_settings_login_item(intent) {
            // The host executed the action before admission; the observation is the evidence
            // itself, so recovery reconstructs the recorded state instead of re-running it.
            return Ok(EffectReconciliation::Applied(
                hiroute_application::agent_connection::settings_login_item_effect(intent)?,
            ));
        }
        let Some(permission) = self.permission_intent(intent)? else {
            return self.artifacts.observe_artifact(operation_id, intent);
        };
        let effect = Self::permission_effect(operation_id, &permission)?;
        if operation
            .step(OperationStepKind::ApplyAgentArtifacts)
            .status
            == OperationStepStatus::Compensated
        {
            return Ok(EffectReconciliation::Missing);
        }

        if let Some(finding) = self
            .permission_findings
            .lock()
            .map_err(|_| PortError::new(PortErrorCode::Unavailable, "permission.cache.lock"))?
            .get(&permission.source_ref)
            .cloned()
        {
            return if finding.observed_identity == permission.observed_identity
                && finding.observed_revision == permission.observed_revision
            {
                Ok(EffectReconciliation::Missing)
            } else {
                Ok(EffectReconciliation::OwnershipLost(effect))
            };
        }

        if self.verify_or_harden(&permission).is_err() {
            return Ok(EffectReconciliation::OwnershipLost(effect));
        }
        if operation.step(OperationStepKind::Activate).status == OperationStepStatus::Applied {
            Ok(EffectReconciliation::Applied(effect))
        } else {
            Ok(EffectReconciliation::Staged(effect))
        }
    }

    fn activate_external(
        &self,
        operation: &hiroute_domain::OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<OwnedEffectV1> {
        self.require_current_operation(operation)?;
        if !operation
            .steps
            .iter()
            .any(|step| step.effects.contains(effect))
        {
            return Err(invalid("effect.uncommitted"));
        }
        if let Some(effect) = self.activate_subscription_effect(effect)? {
            return Ok(effect);
        }
        if effect.kind == OwnedEffectKind::Publication {
            return self.activate_publication(operation, effect);
        }
        if effect.effect_id != EFFECT_ID {
            for intent in operation.plan.external().iter().filter(|intent| {
                intent.target() == effect.target
                    && super::native_additional_model::is_settings_additional_model(intent)
            }) {
                self.validate_additional_model_dependencies(operation, intent)?;
            }
            return self.artifacts.activate_artifact(effect);
        }
        let (operation_id, intent) = self.permission_marker(effect)?;
        if operation_id != operation.operation_id {
            return Err(invalid("permission.effect.operation-binding"));
        }
        self.verify_or_harden(&intent)?;
        Ok(effect.clone())
    }

    fn compensate_external(
        &self,
        operation: &hiroute_domain::OperationV1,
        effect: &OwnedEffectV1,
    ) -> PortResult<CompensationOutcome> {
        self.require_current_operation(operation)?;
        if !operation
            .steps
            .iter()
            .any(|step| step.effects.contains(effect))
        {
            return Err(invalid("effect.uncommitted"));
        }
        if let Some(outcome) = self.compensate_subscription_effect(effect)? {
            return Ok(outcome);
        }
        if effect.kind == OwnedEffectKind::Publication {
            return self.compensate_publication(operation, effect);
        }
        if effect.effect_id != EFFECT_ID {
            return self.artifacts.compensate_artifact(effect);
        }
        let (operation_id, intent) = self.permission_marker(effect)?;
        if operation_id != operation.operation_id {
            return Err(invalid("permission.effect.operation-binding"));
        }
        // Security hardening is monotonic. Rollback re-authenticates the exact identity at 0600
        // and records compensation, but intentionally never restores an unsafe mode.
        if self.verify_or_harden(&intent).is_err() {
            return Ok(CompensationOutcome::OwnershipLost);
        }
        if operation
            .step(OperationStepKind::ApplyAgentArtifacts)
            .status
            == OperationStepStatus::Compensated
        {
            Ok(CompensationOutcome::AlreadyCompensated)
        } else {
            Ok(CompensationOutcome::Compensated)
        }
    }
}

fn invalid(context: &'static str) -> PortError {
    PortError::new(PortErrorCode::InvalidData, context)
}

#[cfg(all(test, unix))]
mod tests;

impl LocalControlAdapter {
    pub(super) fn require_current_operation(
        &self,
        operation: &hiroute_domain::OperationV1,
    ) -> PortResult<()> {
        if !self
            .stores_lock()?
            .control()
            .operation_is_current(operation)?
        {
            return Err(PortError::new(
                PortErrorCode::Conflict,
                "operation.committed-current",
            ));
        }
        Ok(())
    }
}