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.

26.0 KB
Raw Blame
//! ACP v1 only. No reconnect, new-session fallback, file/terminal RPC, or persistent approval.
use agent_client_protocol::schema::ProtocolVersion;
use agent_client_protocol::schema::v1::{
    AuthenticateRequest, CancelNotification, ClientCapabilities, InitializeRequest,
    LoadSessionRequest, NewSessionRequest, PermissionOptionKind, PromptRequest,
    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
    ResumeSessionRequest, SelectedPermissionOutcome, SessionNotification, SetSessionModeRequest,
};
use agent_client_protocol::{Agent, ConnectionTo};
use hiroute_domain::delegation::DelegationErrorV1;
use serde_json::{Map, Value, json};
use std::future::Future;
use std::path::PathBuf;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::time::Duration;
use tokio::io::{AsyncRead, AsyncWrite};
use tokio::time::{Instant, timeout, timeout_at};
use tokio_util::sync::CancellationToken;

use super::progress::ProgressSink;

mod identity;
mod model;
mod pi_failure;
mod transport;
pub use identity::AcpNativeIdentityContract;
pub use transport::MAX_ACP_FRAME_BYTES;

pub use hiroute_domain::delegation::DelegationSessionBindingV1 as AcpSessionBinding;

#[derive(Clone, Debug)]
pub enum AcpSessionStart {
    New,
    Load(AcpSessionBinding),
    Resume(AcpSessionBinding),
}

impl AcpSessionStart {
    /// DSH advertises the ACP resume extension instead of session/load. Both keep the
    /// exact existing binding; run_session still validates its native identity and capability.
    pub(crate) fn native_continuation(
        harness: hiroute_domain::delegation::WorkerHarnessV1,
        binding: AcpSessionBinding,
    ) -> Self {
        if harness == hiroute_domain::delegation::WorkerHarnessV1::DeepseekHarness {
            Self::Resume(binding)
        } else {
            Self::Load(binding)
        }
    }
}

/// Internal profile output, never a raw Local Control payload. Authentication can contain
/// a run secret: deliberately no Debug/Serialize implementation and no protocol logging.
pub struct AcpRunInput {
    pub cwd: PathBuf,
    pub prompt: String,
    pub session: AcpSessionStart,
    pub identity_contract: AcpNativeIdentityContract,
    pub session_meta: Map<String, Value>,
    /// Exact adapter-owned native mode selected after new/load and before the first prompt.
    /// Profiles with a native mode set this. DSH has no mode mutation; protocol fixtures
    /// may also omit it.
    pub native_session_mode: Option<String>,
    /// Profile's exact native model selector ID, confirmed before prompting. The frozen
    /// Plan/Gateway alias remains separate when the native client adds a provider prefix.
    /// Production runs and installation probes set this; protocol-only fixtures may omit it.
    pub expected_model: Option<String>,
    pub authentication: Option<Value>,
    pub deadline: Instant,
    pub cancellation: CancellationToken,
}

pub trait AcpRunJournal: Send + Sync {
    /// Transient startup receipt after a successful, version-checked initialize.
    /// It does not imply session/model readiness or permission to send a prompt.
    fn initialized(&self) {}
    fn session_bound(&self, binding: &AcpSessionBinding) -> Result<(), DelegationErrorV1>;
    /// Must durably record the send intent before returning Ok. Failure means no prompt.
    fn before_prompt(&self) -> Result<(), DelegationErrorV1>;
    fn text_update(&self, text: &str) -> Result<(), DelegationErrorV1>;
    /// Compatibility fallback for an unexpected permission request. Recheck the current run
    /// lifecycle and selected policy on EACH request; this is not the normal autonomy mechanism.
    fn allow_permission_once(&self, request: &Value) -> bool;
}

#[derive(Clone)]
pub struct AcpRunOutcome {
    pub session: AcpSessionBinding,
    pub stop_reason: String,
    pub text: String,
    pub content_incomplete: bool,
}

/// Lifecycle-only terminal work that must finish before dropping the live ACP transport.
/// No protocol or persisted field is added. The lifecycle keeps terminal publication,
/// credential revocation and exact native history observation in their original order.
pub(crate) trait AcpTerminalCheckpoint: Send + Sync {
    fn before_transport_close<'a>(
        &'a self,
        outcome: &'a AcpRunOutcome,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
}

#[derive(Default)]
struct Updates {
    session: Option<String>,
    text: String,
    incomplete: bool,
    prompt_started: bool,
}

pub async fn run_acp<R, W>(
    reader: R,
    writer: W,
    input: AcpRunInput,
    journal: Arc<dyn AcpRunJournal>,
) -> Result<AcpRunOutcome, DelegationErrorV1>
where
    R: AsyncRead + Unpin + Send + 'static,
    W: AsyncWrite + Unpin + Send + 'static,
{
    run_acp_with_progress(reader, writer, input, journal, None).await
}

pub(crate) async fn run_acp_with_progress<R, W>(
    reader: R,
    writer: W,
    input: AcpRunInput,
    journal: Arc<dyn AcpRunJournal>,
    progress: Option<ProgressSink>,
) -> Result<AcpRunOutcome, DelegationErrorV1>
where
    R: AsyncRead + Unpin + Send + 'static,
    W: AsyncWrite + Unpin + Send + 'static,
{
    run_acp_with_terminal_checkpoint(reader, writer, input, journal, progress, None).await
}

pub(crate) async fn run_acp_with_terminal_checkpoint<R, W>(
    reader: R,
    writer: W,
    input: AcpRunInput,
    journal: Arc<dyn AcpRunJournal>,
    progress: Option<ProgressSink>,
    terminal_checkpoint: Option<Arc<dyn AcpTerminalCheckpoint>>,
) -> Result<AcpRunOutcome, DelegationErrorV1>
where
    R: AsyncRead + Unpin + Send + 'static,
    W: AsyncWrite + Unpin + Send + 'static,
{
    if !input.cwd.is_absolute() || input.prompt.is_empty() || input.prompt.len() > 256 * 1024 {
        return Err(DelegationErrorV1::InvalidArguments);
    }
    let updates = Arc::new(Mutex::new(Updates::default()));
    let notifications = updates.clone();
    let notification_journal = journal.clone();
    let notification_progress = progress.clone();
    let permissions = updates.clone();
    let permission_journal = journal.clone();
    let permission_cancellation = input.cancellation.clone();
    let connection_cancellation = input.cancellation.clone();
    let permission_deadline = input.deadline;
    let hard_deadline = input.deadline + Duration::from_secs(5);
    let connected = agent_client_protocol::Client
        .builder()
        .on_receive_notification(
            async move |notification: SessionNotification, _cx| {
                let mut state = notifications.lock().unwrap_or_else(|e| e.into_inner());
                // Native adapters may announce configuration during session/new, before its
                // response binds the session. Load also replays history. Neither belongs to
                // this run's output, and an unbound startup notification is not lost output.
                if !state.prompt_started {
                    return Ok(());
                }
                let session_matches =
                    state.session.as_deref() == Some(notification.session_id.to_string().as_str());
                let update = serde_json::to_value(notification.update).unwrap_or(Value::Null);
                if !session_matches {
                    state.incomplete = true;
                    return Ok(());
                }
                if update["sessionUpdate"] == "agent_message_chunk"
                    && let Some(text) = update.pointer("/content/text").and_then(Value::as_str)
                {
                    if let Some(progress) = notification_progress.as_ref() {
                        progress.push(text);
                    }
                    if state.text.len().saturating_add(text.len()) <= MAX_ACP_FRAME_BYTES {
                        state.text.push_str(text);
                        if notification_journal.text_update(text).is_err() {
                            state.incomplete = true;
                        }
                    } else {
                        state.incomplete = true;
                    }
                }
                Ok(())
            },
            agent_client_protocol::on_receive_notification!(),
        )
        .on_receive_request(
            async move |request: RequestPermissionRequest, responder, _cx| {
                let matches = {
                    let state = permissions.lock().unwrap_or_else(|e| e.into_inner());
                    state.prompt_started
                        && state.session.as_deref() == Some(request.session_id.to_string().as_str())
                };
                let request_value = serde_json::to_value(&request).unwrap_or(Value::Null);
                let selected = (matches
                    && !permission_cancellation.is_cancelled()
                    && Instant::now() < permission_deadline)
                    .then(|| {
                        if permission_journal.allow_permission_once(&request_value) {
                            request
                                .options
                                .iter()
                                .find(|o| o.kind == PermissionOptionKind::AllowOnce)
                        } else {
                            None
                        }
                    })
                    .flatten();
                let outcome = selected.map_or(RequestPermissionOutcome::Cancelled, |option| {
                    RequestPermissionOutcome::Selected(SelectedPermissionOutcome::new(
                        option.option_id.clone(),
                    ))
                });
                responder.respond(RequestPermissionResponse::new(outcome))
            },
            agent_client_protocol::on_receive_request!(),
        )
        .connect_with(
            transport::bounded_transport(reader, writer),
            async move |connection: ConnectionTo<Agent>| {
                let outcome =
                    run_session(connection, input, journal, updates.clone(), progress).await;
                // A terminal response ends tool permission and text admission even while
                // a native transcript is draining on this still-live connection.
                updates
                    .lock()
                    .unwrap_or_else(|e| e.into_inner())
                    .prompt_started = false;
                if let (Ok(outcome), Some(checkpoint)) = (&outcome, terminal_checkpoint)
                    && outcome.stop_reason != "cancelled"
                {
                    checkpoint.before_transport_close(outcome).await;
                }
                Ok(outcome)
            },
        );
    tokio::pin!(connected);
    tokio::select! {
        biased;
        _ = connection_cancellation.cancelled() => {
            // Give the ACP notification/prompt response a bounded graceful window. Some adapters
            // keep their transport open after an ignored prompt cancellation; the lifecycle must
            // then return so its existing owned-process stop and material cleanup can run.
            match timeout(Duration::from_secs(6), &mut connected).await {
                Ok(Ok(Ok(outcome))) => Ok(outcome),
                _ => Err(DelegationErrorV1::Cancelled),
            }
        },
        result = timeout_at(hard_deadline, &mut connected) => {
            result
                .map_err(|_| DelegationErrorV1::DeadlineExceeded)?
                .map_err(|_| DelegationErrorV1::ProtocolFailed)?
        },
    }
}

async fn run_session(
    connection: ConnectionTo<Agent>,
    input: AcpRunInput,
    journal: Arc<dyn AcpRunJournal>,
    updates: Arc<Mutex<Updates>>,
    progress: Option<ProgressSink>,
) -> Result<AcpRunOutcome, DelegationErrorV1> {
    let initialized = phase(
        "initialize",
        &input.cancellation,
        input.deadline,
        connection.send_request(initialize_request()?).block_task(),
    )
    .await?;
    if initialized.protocol_version != ProtocolVersion::V1 {
        return Err(DelegationErrorV1::CapabilityUnavailable);
    }
    if input.identity_contract == AcpNativeIdentityContract::CodexThreadV1
        && !advertises_session_failure(initialized.meta.as_ref())
    {
        // The adapter has already spawned. Use the lifecycle's bounded progress capture,
        // which is flushed after owned-process cleanup, without inventing a model result.
        if let Some(progress) = progress.as_ref() {
            progress.push("[HiRoute] The selected codex-acp adapter does not advertise the required AIR v1 sessionFailure capability. Update the adapter to a version supporting this capability, select it again in Worker dependencies, and submit the task again.\n");
        }
        return Err(DelegationErrorV1::CapabilityUnavailable);
    }
    journal.initialized();
    if let Some(authentication) = input.authentication {
        let request: AuthenticateRequest = serde_json::from_value(authentication)
            .map_err(|_| DelegationErrorV1::InvalidArguments)?;
        phase(
            "authenticate",
            &input.cancellation,
            input.deadline,
            connection.send_request(request).block_task(),
        )
        .await?;
    }
    let (binding, modes, config_options) = match input.session {
        AcpSessionStart::New => {
            let request: NewSessionRequest = serde_json::from_value(json!({
                "cwd":input.cwd,"mcpServers":[],"_meta":input.session_meta,
            }))
            .map_err(|_| DelegationErrorV1::InvalidArguments)?;
            let response = phase(
                "new-session",
                &input.cancellation,
                input.deadline,
                connection.send_request(request).block_task(),
            )
            .await?;
            let raw =
                serde_json::to_value(&response).map_err(|_| DelegationErrorV1::ProtocolFailed)?;
            (
                AcpSessionBinding {
                    acp_session_id: response.session_id.to_string(),
                    native_session_id: input
                        .identity_contract
                        .new_native(&response.session_id.to_string(), &raw)?,
                },
                response.modes,
                response.config_options,
            )
        }
        AcpSessionStart::Resume(expected) => {
            if initialized
                .agent_capabilities
                .session_capabilities
                .resume
                .is_none()
                || input.identity_contract != AcpNativeIdentityContract::DshSessionV1
                || expected.native_session_id.as_deref() != Some(expected.acp_session_id.as_str())
                || expected.acp_session_id.is_empty()
            {
                return Err(DelegationErrorV1::ResumeUnavailable);
            }
            updates.lock().unwrap_or_else(|e| e.into_inner()).session =
                Some(expected.acp_session_id.clone());
            let request: ResumeSessionRequest = serde_json::from_value(json!({
                "sessionId":expected.acp_session_id,"cwd":input.cwd,"mcpServers":[],
            }))
            .map_err(|_| DelegationErrorV1::InvalidArguments)?;
            let response = phase(
                "resume-session",
                &input.cancellation,
                input.deadline,
                connection.send_request(request).block_task(),
            )
            .await
            .map_err(|error| {
                if error == DelegationErrorV1::ProtocolFailed {
                    DelegationErrorV1::ResumeUnavailable
                } else {
                    error
                }
            })?;
            (expected, response.modes, response.config_options)
        }
        AcpSessionStart::Load(expected) => {
            let prerequisites_ready = initialized.agent_capabilities.load_session
                && expected.native_session_id.is_some()
                && !expected.acp_session_id.is_empty()
                && input.identity_contract != AcpNativeIdentityContract::Unverified;
            if !prerequisites_ready {
                return Err(DelegationErrorV1::ResumeUnavailable);
            }
            updates.lock().unwrap_or_else(|e| e.into_inner()).session =
                Some(expected.acp_session_id.clone());
            let request: LoadSessionRequest = serde_json::from_value(json!({
                "sessionId":expected.acp_session_id,"cwd":input.cwd,"mcpServers":[],"_meta":input.session_meta,
            })).map_err(|_| DelegationErrorV1::InvalidArguments)?;
            let response = phase(
                "load-session",
                &input.cancellation,
                input.deadline,
                connection.send_request(request).block_task(),
            )
            .await
            .map_err(|error| {
                if error == DelegationErrorV1::ProtocolFailed {
                    DelegationErrorV1::ResumeUnavailable
                } else {
                    error
                }
            })?;
            let raw =
                serde_json::to_value(&response).map_err(|_| DelegationErrorV1::ProtocolFailed)?;
            let identity_verified = input.identity_contract.verify_load(&expected, &raw);
            if !identity_verified {
                return Err(DelegationErrorV1::ResumeUnavailable);
            }
            (expected, response.modes, response.config_options)
        }
    };
    if binding.acp_session_id.is_empty() || binding.acp_session_id.len() > 1024 {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    updates.lock().unwrap_or_else(|e| e.into_inner()).session =
        Some(binding.acp_session_id.clone());
    journal.session_bound(&binding)?;
    let typed_mode = input.identity_contract == AcpNativeIdentityContract::OpenCodeSessionV1;
    let config_options = if typed_mode {
        let expected = input
            .native_session_mode
            .as_deref()
            .ok_or(DelegationErrorV1::CapabilityUnavailable)?;
        Some(
            model::ensure_mode(
                &connection,
                &binding.acp_session_id,
                config_options.as_deref(),
                expected,
                &input.cancellation,
                input.deadline,
            )
            .await?,
        )
    } else {
        config_options
    };
    if let Some(expected_model) = input.expected_model.as_deref() {
        model::ensure_model(
            &connection,
            &binding.acp_session_id,
            config_options.as_deref(),
            expected_model,
            &input.cancellation,
            input.deadline,
        )
        .await?;
    }
    if let Some(native_session_mode) = input.native_session_mode.filter(|_| !typed_mode) {
        let mode_available = modes.as_ref().is_some_and(|modes| {
            modes
                .available_modes
                .iter()
                .any(|mode| mode.id.to_string() == native_session_mode)
        });
        if !mode_available {
            return Err(DelegationErrorV1::CapabilityUnavailable);
        }
        phase(
            "set-mode",
            &input.cancellation,
            input.deadline,
            connection
                .send_request(SetSessionModeRequest::new(
                    binding.acp_session_id.clone(),
                    native_session_mode,
                ))
                .block_task(),
        )
        .await
        .map_err(|error| {
            if error == DelegationErrorV1::ProtocolFailed {
                DelegationErrorV1::CapabilityUnavailable
            } else {
                error
            }
        })?;
    }
    if input.cancellation.is_cancelled() {
        return Err(DelegationErrorV1::Cancelled);
    }
    if Instant::now() >= input.deadline {
        return Err(DelegationErrorV1::DeadlineExceeded);
    }
    let request: PromptRequest = serde_json::from_value(json!({
        "sessionId":binding.acp_session_id,"prompt":[{"type":"text","text":input.prompt}],
    }))
    .map_err(|_| DelegationErrorV1::InvalidArguments)?;
    journal.before_prompt()?;
    updates
        .lock()
        .unwrap_or_else(|e| e.into_inner())
        .prompt_started = true;
    let prompt = connection.send_request(request).block_task();
    tokio::pin!(prompt);
    let response = tokio::select! {
        biased;
        _ = input.cancellation.cancelled() => None,
        _ = tokio::time::sleep_until(input.deadline) => None,
        response = &mut prompt => Some(response.map_err(pi_failure::map_error)?),
    };
    let stop_reason = if let Some(response) = response {
        let prompt_failed = prompt_session_failure(response.meta.as_ref())?;
        let stop_reason = serde_json::to_value(response.stop_reason)
            .ok()
            .and_then(|v| v.as_str().map(str::to_owned))
            .ok_or(DelegationErrorV1::ProtocolFailed)?;
        if prompt_failed {
            return Err(DelegationErrorV1::PromptFailed);
        }
        stop_reason
    } else {
        let cancel: CancelNotification =
            serde_json::from_value(json!({"sessionId":binding.acp_session_id}))
                .map_err(|_| DelegationErrorV1::InvalidArguments)?;
        connection
            .send_notification(cancel)
            .map_err(|_| DelegationErrorV1::ProtocolFailed)?;
        timeout(Duration::from_secs(5), &mut prompt)
            .await
            .map_err(|_| DelegationErrorV1::DeadlineExceeded)?
            .map_err(|_| DelegationErrorV1::ProtocolFailed)?;
        "cancelled".to_owned()
    };
    let mut state = updates.lock().unwrap_or_else(|e| e.into_inner());
    Ok(AcpRunOutcome {
        session: binding,
        stop_reason,
        text: std::mem::take(&mut state.text),
        content_incomplete: state.incomplete,
    })
}

fn advertises_session_failure(meta: Option<&Map<String, Value>>) -> bool {
    let Some(air) = meta
        .and_then(|meta| meta.get("jetbrains"))
        .and_then(|value| value.get("air"))
    else {
        return false;
    };
    air.get("version")
        .and_then(Value::as_u64)
        .is_some_and(|version| version >= 1)
        && air
            .get("capabilities")
            .and_then(Value::as_array)
            .is_some_and(|capabilities| {
                capabilities
                    .iter()
                    .any(|value| value.as_str() == Some("sessionFailure"))
            })
}

fn initialize_request() -> Result<InitializeRequest, DelegationErrorV1> {
    let client_capabilities: ClientCapabilities = serde_json::from_value(json!({
        "_meta": {
            "jetbrains": {
                "air": {
                    "version": 1,
                    "capabilities": ["sessionFailure"]
                }
            }
        }
    }))
    .map_err(|_| DelegationErrorV1::ProtocolFailed)?;
    Ok(InitializeRequest::new(ProtocolVersion::V1).client_capabilities(client_capabilities))
}

/// The negotiated v1 extension reports a terminal model/adapter error on a successful ACP
/// PromptResponse. Treating only the JSON-RPC envelope as authoritative would falsely complete
/// the Worker run. Unknown metadata outside this exact extension remains opaque.
fn prompt_session_failure(meta: Option<&Map<String, Value>>) -> Result<bool, DelegationErrorV1> {
    let Some(air) = meta
        .and_then(|meta| meta.get("jetbrains"))
        .and_then(Value::as_object)
        .and_then(|jetbrains| jetbrains.get("air"))
        .and_then(Value::as_object)
    else {
        return Ok(false);
    };
    let Some(failure) = air.get("sessionFailure") else {
        return Ok(false);
    };
    if !air
        .get("version")
        .and_then(Value::as_u64)
        .is_some_and(|version| version >= 1)
    {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    let failure = failure
        .as_object()
        .ok_or(DelegationErrorV1::ProtocolFailed)?;
    let required_string = |field: &str, limit: usize| {
        failure
            .get(field)
            .and_then(Value::as_str)
            .filter(|value| {
                !value.is_empty() && value.len() <= limit && !value.chars().any(char::is_control)
            })
            .ok_or(DelegationErrorV1::ProtocolFailed)
    };
    required_string("id", 1_024)?;
    if !failure
        .get("title")
        .and_then(Value::as_str)
        .is_some_and(|title| !title.is_empty() && title.len() <= MAX_ACP_FRAME_BYTES)
    {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    if failure.get("revision").and_then(Value::as_u64) == Some(0)
        || failure.get("revision").and_then(Value::as_u64).is_none()
    {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    if !matches!(
        required_string("category", 32)?,
        "connection" | "access" | "limit" | "request" | "service" | "unknown"
    ) {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    let severity = required_string("severity", 16)?;
    if !matches!(severity, "warning" | "error") {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    if failure.get("details").is_some_and(|details| {
        !details
            .as_str()
            .is_some_and(|details| details.len() <= MAX_ACP_FRAME_BYTES)
    }) {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    let actions = failure
        .get("actions")
        .and_then(Value::as_array)
        .filter(|actions| actions.len() <= 32)
        .ok_or(DelegationErrorV1::ProtocolFailed)?;
    if actions.iter().any(|action| {
        !action.as_str().is_some_and(|action| {
            !action.is_empty() && action.len() <= 64 && !action.chars().any(char::is_control)
        })
    }) {
        return Err(DelegationErrorV1::ProtocolFailed);
    }
    Ok(severity == "error")
}

async fn phase<T>(
    stage: &'static str,
    cancellation: &CancellationToken,
    deadline: Instant,
    future: impl Future<Output = Result<T, agent_client_protocol::Error>>,
) -> Result<T, DelegationErrorV1> {
    #[cfg(not(test))]
    let _ = stage;
    tokio::select! {
        biased;
        _ = cancellation.cancelled() => Err(DelegationErrorV1::Cancelled),
        _ = tokio::time::sleep_until(deadline) => Err(DelegationErrorV1::DeadlineExceeded),
        result = future => result.map_err(|error| {
            #[cfg(test)]
            eprintln!("native acceptance ACP stage={} request-error-code={}", stage, i32::from(error.code));
            pi_failure::map_error(error)
        }),
    }
}

#[cfg(test)]
mod identity_tests;
#[cfg(test)]
mod model_tests;
#[cfg(test)]
mod notification_tests;
#[cfg(test)]
mod security_tests;
#[cfg(test)]
mod tests;

#[cfg(test)]
mod opencode_tests;