aion_server/assistant/sessions/

launch.rs

//! Composing the ACP harness one session runs on.
//!
//! Everything a spawn needs is decided here, once, from the CATALOGUE entry the
//! operator picked plus the session's own identity — so no other module builds a
//! `Command`, and the facts that are easy to get wrong are in one place with
//! their reasons beside them.
//!
//! # Nothing here is configuration any more
//!
//! The launch line is the catalogue's (`aion_integration_acp::catalogue`), which
//! is what makes a fresh install usable: no command, no arguments, no working
//! directory, no timeouts. What is left are three product decisions, each stated
//! out loud below rather than defaulted quietly — the environment the child
//! gets, where it is rooted, and how its permission requests are answered.
//!
//! # The child's environment is CONSTRUCTED
//!
//! `env_clear()` then exactly [`AGENT_ENVIRONMENT`] resolved out of the server's
//! own environment, plus the account's declared variables. A variable nobody
//! named cannot reach the agent whatever this server carries — the rule that
//! exists because one agent's own shell variable once reached a nested
//! `claude-code-acp` and made it refuse every `session/new`.
//!
//! An account names its variables on BOTH sides (the name the child gets, the
//! name it is read from), so no value is ever written into a config file. A
//! source the server does not carry is a TYPED ABSENCE here — never an empty
//! string handed to an agent that would then look logged out for a reason
//! nobody could see.
//!
//! # `cwd` is NOT a boundary
//!
//! An ACP agent's tools are not confined by the directory it was started in, and
//! the catalogue's launch lines carry no confinement flag of their own (they are
//! each agent's documented ACP invocation, verbatim, and `--workspace-root` is
//! not a flag `npx @agentclientprotocol/claude-agent-acp` accepts). What
//! confines the agent is the CONTAINMENT — it runs in its own process group and
//! the session takes the group with it — and what roots it is the server's own
//! working directory, which is the one directory an operator has already chosen
//! by starting the server there. Nothing here asks which directory the repo is
//! in; the console tells the agent through `assistant_context`.
//!
//! # Values never reach a log line
//!
//! The declaration is NAMES; the resolved values are placed on the `Command` and
//! never rendered. Nothing here logs an environment value, and nothing puts the
//! session bearer anywhere but into the MCP server specification.
//! `launch_tests.rs` pins both.

use std::path::PathBuf;
use std::time::Duration;

use aion_core::AssistantSessionId;
use aion_integration_acp::catalogue::CatalogueHarness;
use aion_integration_acp::{AcpHarness, McpServerSpec, PermissionPolicy};
use aion_integrations::{EnvironmentDeclaration, HarnessWorkspace};

use crate::config::ResolvedAssistantAccount;

use super::error::AssistantSessionError;
use super::token::{self, MintedSessionToken};

/// The environment variable NAMES every assistant agent is launched with.
///
/// A fixed, stated set rather than an operator knob, because the round-2
/// amendment retired the knob and because every name here is needed for the
/// catalogue's own launch lines to work at all:
///
/// - `PATH` — `npx` and `opencode` are looked up on it; without it nothing execs.
/// - `HOME` — where the harness keeps its OWN login state (`~/.claude`,
///   `~/.codex`) and where `npx` caches the adapter it fetches. This is the
///   variable that makes "log the harness in on the server host" true.
/// - `TMPDIR` — `npx` unpacks into it; on macOS it is per-user and absent from a
///   cleared environment.
/// - `SHELL`, `USER`, `LOGNAME` — an agent that runs a tool runs it through a
///   shell, and the tools it runs (git, most of all) identify the user by these.
/// - `LANG`, `LC_ALL` — text encoding; an agent reading source under the C
///   locale mangles anything that is not ASCII.
/// - `TERM` — some agents refuse to start with no terminal type at all.
/// - `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_STATE_HOME` —
///   where a harness keeps its login state on Linux when the operator moved it.
/// - `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and their lowercase spellings — on
///   a corporate network an agent with no proxy cannot reach its own API, and
///   the failure surfaces as an inscrutable timeout.
/// - `SSL_CERT_FILE`, `SSL_CERT_DIR`, `NODE_EXTRA_CA_CERTS` — the same story for
///   a private certificate authority.
///
/// A name that is not here can still reach a particular agent: an account
/// declares it, which is what the `[assistant]` section is now FOR.
const AGENT_ENVIRONMENT: &[&str] = &[
    "PATH",
    "HOME",
    "TMPDIR",
    "SHELL",
    "USER",
    "LOGNAME",
    "LANG",
    "LC_ALL",
    "TERM",
    "XDG_CONFIG_HOME",
    "XDG_DATA_HOME",
    "XDG_CACHE_HOME",
    "XDG_STATE_HOME",
    "HTTP_PROXY",
    "HTTPS_PROXY",
    "NO_PROXY",
    "http_proxy",
    "https_proxy",
    "no_proxy",
    "SSL_CERT_FILE",
    "SSL_CERT_DIR",
    "NODE_EXTRA_CA_CERTS",
];

/// How long the agent's exit is awaited after its stdin closes and its process
/// group has been asked to stop, before the group is killed.
///
/// NOT an operator knob and not a policy: it is the distribution's ONE
/// termination grace, imported by reference from the process-group containment
/// every declared body already runs under, so the assistant's agent and a
/// worker-owned command are stopped on the same ladder with the same window.
/// The round-2 amendment retired `exit_grace` as configuration; what is left is
/// the mechanism's own bound, and a second copy of that number is what would
/// make the two drift.
const TERMINATION_GRACE: Duration = aion_worker::PROCESS_GROUP_TERMINATION_GRACE;

/// How an assistant agent's permission requests are answered.
///
/// `allow-once` — approve one-shot requests, never a durable "remember this"
/// grant — and the reasoning is worth stating, because it is the one product
/// decision here that is not forced.
///
/// The operator summoned this agent from their own console, in their own
/// session, on their own machine, and every request and decision is recorded on
/// the transcript they are watching. `deny` would make a stock server's
/// assistant unable to read a file or run a check — the whole of what it is for
/// — and, with the knob retired, would leave the operator nothing to change. A
/// durable grant would outlive the conversation that gave it. So: one-shot,
/// recorded, and bounded by the process group the session takes with it.
///
/// An in-console permission prompt is a stated non-goal of this cut (contract
/// §3); this is the policy that stands in its place, and the surface says so.
const PERMISSION: PermissionPolicy = PermissionPolicy::AllowOnce;

/// Where a spawned agent dials this server back.
///
/// TWO routes, one address. The general `/mcp` catalogue is the workflow tool
/// surface and is dark unless `[mcp] enabled`; `/assistant/mcp` is the
/// assistant's OWN catalogue and is served whenever this server can state an
/// address at all, because it is how a session's agent learns what is on the
/// operator's screen — the answer to "never ask which directory the repo is in".
///
/// `None` for the whole struct means this server cannot state a dialable address
/// (a configured port of zero, whose real port is only known after bind), and
/// then no MCP server of ours is handed over at all.
#[derive(Clone, Debug)]
pub struct AssistantEndpoints {
    /// The dialable origin, `http://host:port`, with no trailing slash.
    pub base: String,
    /// Whether the general `/mcp` route is mounted on it.
    pub aion_mcp_enabled: bool,
}

impl AssistantEndpoints {
    /// This server's general MCP route, when it is mounted.
    #[must_use]
    pub fn aion_mcp_url(&self) -> Option<String> {
        self.aion_mcp_enabled
            .then(|| format!("{}{}", self.base, crate::mcp::MCP_PATH))
    }

    /// This server's ASSISTANT-ONLY MCP route.
    ///
    /// Always present: its catalogue is one tool about this session, and it is
    /// authorized by the session's own bearer rather than by anything the
    /// general surface's `[mcp] enabled` switch governs.
    #[must_use]
    pub fn assistant_mcp_url(&self) -> String {
        format!("{}{}", self.base, crate::assistant::mcp::ASSISTANT_MCP_PATH)
    }
}

/// Everything one spawn needs.
pub(crate) struct HarnessPlan {
    /// The configured harness, ready to start.
    pub(crate) harness: AcpHarness,
    /// The session bearer minted for it — `None` when the session was given no
    /// MCP server of ours and so needs no identity of its own.
    pub(crate) token: Option<MintedSessionToken>,
}

/// Build the harness one session runs on.
///
/// # Errors
///
/// [`AssistantSessionError::HarnessUnavailable`] when the catalogue entry's
/// program does not resolve on this server's `PATH` — re-measured HERE, at the
/// spawn, because availability is a fact about this machine now and not about
/// the machine as it was when the session was created.
/// [`AssistantSessionError::AccountEnvironmentAbsent`] when an account names a
/// server variable this server does not carry.
/// [`AssistantSessionError::Internal`] when the server has no working directory
/// to root the agent in, or the declaration cannot be built.
pub(crate) fn plan(
    session_id: AssistantSessionId,
    harness: &'static CatalogueHarness,
    account: Option<&ResolvedAssistantAccount>,
    endpoints: Option<&AssistantEndpoints>,
) -> Result<HarnessPlan, AssistantSessionError> {
    if !harness.available() {
        return Err(AssistantSessionError::HarnessUnavailable {
            harness: harness.id.to_owned(),
            launch: harness.launch(),
            install_hint: harness.install_hint.to_owned(),
        });
    }
    let (environment, account_variables) = resolve_environment(harness, account)?;
    let workspace = server_workspace()?;
    let (mcp_servers, token) = mcp_servers(session_id, endpoints);

    let mut built = AcpHarness::new(
        harness.program,
        harness.args.iter().copied(),
        HarnessWorkspace::Fixed(workspace),
        PERMISSION,
        TERMINATION_GRACE,
    )
    .with_declared_environment(environment)
    // The agent is a LAUNCHER (`npx` execs node, node runs the adapter, the
    // adapter runs tools), so ending this session has to take the group and not
    // the child. This is the assistant's own containment: the server owns the
    // process directly, and nothing outside it would stop the tree.
    .with_process_group_containment()
    .with_mcp_servers(mcp_servers);

    // The account's variables go on LAST, over the stated set, because that is
    // what an account IS: the one or two variables that point a harness at a
    // different login on disk. They are values by this point, and they are
    // placed on the command rather than logged.
    for (child, value) in account_variables {
        built = built.with_env(child, value);
    }

    Ok(HarnessPlan {
        harness: built,
        token,
    })
}

/// The child's declared environment, and the account's variables resolved into
/// the names the child is given.
///
/// Two passes through the SAME [`EnvironmentDeclaration`] discipline, because
/// they answer two different questions. The stated set is an allow-list: a
/// server with no `TERM` is a server with no `TERM`, and the child simply does
/// not get one. An ACCOUNT's names are a REQUIREMENT: the operator declared them
/// to select a login, so a source this server does not carry is a typed absence
/// naming the variable — never an empty string, which would present to the
/// operator as a harness that is mysteriously logged out.
///
/// The account's value is then carried under the name the account said, which is
/// what lets two accounts select two different login directories through the one
/// variable a harness actually reads.
fn resolve_environment(
    harness: &CatalogueHarness,
    account: Option<&ResolvedAssistantAccount>,
) -> Result<(aion_integrations::ChildEnvironment, Vec<(String, String)>), AssistantSessionError> {
    let declaration =
        EnvironmentDeclaration::new(AGENT_ENVIRONMENT.iter().copied()).map_err(|error| {
            AssistantSessionError::Internal(format!(
                "the assistant's own environment declaration cannot be built ({error}); it is a \
                 constant in this module, so reaching this is a server defect"
            ))
        })?;
    let environment = declaration.resolve_from_process();
    let Some(account) = account else {
        return Ok((environment, Vec::new()));
    };
    let sources = EnvironmentDeclaration::new(account.source_names())
        .map_err(|error| {
            AssistantSessionError::Internal(format!(
                "the account `{}` on harness `{}` declares an environment the launcher cannot \
                 build ({error}); the names are checked at config load, so reaching this is a \
                 server defect",
                account.name, harness.id
            ))
        })?
        .resolve_from_process();
    if !sources.absent().is_empty() {
        let variables = account
            .env
            .iter()
            .filter(|(_child, source)| sources.absent().iter().any(|name| name == source))
            .map(|(child, source)| {
                format!("`{source}` (which the agent would receive as `{child}`)")
            })
            .collect::<Vec<_>>()
            .join(", ");
        return Err(AssistantSessionError::AccountEnvironmentAbsent {
            harness: harness.id.to_owned(),
            account: account.name.clone(),
            variables,
        });
    }
    let carried = account
        .env
        .iter()
        .filter_map(|(child, source)| {
            sources
                .pairs()
                .iter()
                .find(|(name, _value)| name == source)
                .map(|(_name, value)| (child.clone(), value.clone()))
        })
        .collect();
    Ok((environment, carried))
}

/// The directory an assistant agent is rooted at: the server's own.
///
/// The one directory an operator has already chosen — they started the server
/// there — and the only one available without asking a question the amendment
/// forbids asking. It is not a boundary (see the module docs) and is not
/// pretended to be one.
fn server_workspace() -> Result<PathBuf, AssistantSessionError> {
    std::env::current_dir().map_err(|error| {
        AssistantSessionError::Internal(format!(
            "this server cannot read its own working directory ({error}), so it cannot say where \
             an assistant agent would run; ACP requires an absolute session root and this server \
             will not invent one"
        ))
    })
}

/// The MCP servers this session's agent is told about, and the bearer that
/// identifies it to both of this server's own routes.
///
/// TWO specs of ours, never one merged catalogue: the general `/mcp` tools are
/// the workflow surface any authorized caller reaches, and `assistant_context`
/// is about THIS conversation and belongs to nobody else. Publishing it in the
/// general catalogue would make one session's screen a tool every caller could
/// see listed; giving it its own route with its own catalogue and the session
/// bearer as the only credential is what keeps the two apart by construction
/// rather than by a filter somebody has to remember to apply.
///
/// ONE bearer covers both, because both are this server and the identity being
/// asserted — "I am session X's agent" — is the same on each.
///
/// The general route is handed over exactly when it is MOUNTED. It used to take
/// an `[assistant.tools] aion` switch as well; with that knob retired, `[mcp]
/// enabled` is the one place an operator says whether this server publishes
/// workflow tools at all, and a second switch saying it again is a second thing
/// to keep in step.
fn mcp_servers(
    session_id: AssistantSessionId,
    endpoints: Option<&AssistantEndpoints>,
) -> (Vec<McpServerSpec>, Option<MintedSessionToken>) {
    let mut servers = Vec::new();
    let Some(endpoints) = endpoints else {
        // Sessions still run; the agent simply cannot ask what is on screen.
        // Said out loud rather than left as a tool that silently is not there.
        tracing::warn!(
            "this server can state no dialable address, so assistant sessions are opened without \
             the `assistant_context` tool; the agent will not be able to read what is on the \
             operator's screen"
        );
        return (servers, None);
    };
    let minted = MintedSessionToken::mint();
    let headers = session_headers(session_id, &minted);
    if let Some(url) = endpoints.aion_mcp_url() {
        servers.push(McpServerSpec::Http {
            name: AION_MCP_SERVER_NAME.to_owned(),
            url,
            headers: headers.clone(),
        });
    }
    servers.push(McpServerSpec::Http {
        name: ASSISTANT_MCP_SERVER_NAME.to_owned(),
        url: endpoints.assistant_mcp_url(),
        headers,
    });
    (servers, Some(minted))
}

/// The headers that say WHICH session is calling, and prove it.
fn session_headers(
    session_id: AssistantSessionId,
    minted: &MintedSessionToken,
) -> Vec<(String, String)> {
    vec![
        (
            AUTHORIZATION_HEADER.to_owned(),
            token::authorization_value(minted.secret()),
        ),
        (
            token::SESSION_ID_HEADER.to_owned(),
            token::session_header_value(session_id),
        ),
    ]
}

/// The name the agent shows for this server's own workflow tools.
pub(crate) const AION_MCP_SERVER_NAME: &str = "aion";

/// The name the agent shows for the assistant's own tools.
pub(crate) const ASSISTANT_MCP_SERVER_NAME: &str = "assistant";

/// The header the session bearer rides on.
const AUTHORIZATION_HEADER: &str = "authorization";

#[cfg(test)]
#[path = "launch_tests.rs"]
mod tests;