Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

25.9 KB
Raw Blame
//! Spawning and supervising the ACP child process.
//!
//! This is a local port of the SDK's `AcpAgent` (`agent-client-protocol`,
//! `src/acp_agent.rs`, at the rev pinned in the workspace `Cargo.toml`). It
//! exists because `AcpAgentConfig` is exactly `{command, args, env}` and the
//! SDK's spawn path never calls `Command::current_dir`, so the only ways to
//! give the child a working directory were mutating the daemon's own cwd or a
//! `/bin/sh -c 'cd …'` wrapper. Here the daemon owns the
//! `std::process::Command`, sets `current_dir` and the process group directly,
//! and hands the pipes to the SDK's public [`Lines`] transport - the same seam
//! `AcpAgent` itself connects through. `ByteStreams` is not usable here: it
//! wraps the line layer internally, and the debug tap and the stdout-EOF
//! signal both hook individual lines.
//!
//! Everything other than the spawn is kept behaviour-for-behaviour with
//! `AcpAgent::connect_to`, and must be re-read against it whenever the SDK
//! pin moves:
//! - process-group kill on drop ([`ChildGuard`]), created before the first poll
//!   so cancelling the connection early still tears the group down;
//! - continuous stderr draining with a bounded tail ([`StderrTail`]) that is
//!   reported together with a nonzero exit status;
//! - the per-line debug tap on stdin, stdout and stderr;
//! - the stdout-EOF signal that bounds a final stdin write once the child has
//!   half-closed stdout ([`write_line_with_shutdown_timeout`]);
//! - the grace periods around protocol shutdown and child exit.
//!
//! Deliberately not ported: the Windows `CREATE_NO_WINDOW` creation flag.
//! `macrod` is itself a console program, so a console child inherits its
//! console rather than opening a new one.
//!
//! If the SDK ever grows a working-directory option on `AcpAgentConfig`,
//! delete this module and go back to `AcpAgent`.

use std::collections::BTreeMap;
use std::collections::VecDeque;
use std::path::PathBuf;
use std::pin::pin;
use std::sync::Arc;
use std::time::Duration;

use agent_client_protocol::util::internal_error;
use agent_client_protocol::{Agent, Client, ConnectTo, Error, LineDirection, Lines};
use tokio::process::{Child, ChildStderr, ChildStdin, ChildStdout};
use tokio_util::compat::{TokioAsyncReadCompatExt as _, TokioAsyncWriteCompatExt as _};

#[cfg(windows)]
mod job;
mod running;
#[cfg(test)]
mod test;

pub(crate) use running::{AgentEvent, AttachedAgent, RunningAgent};

type DebugCallback = Arc<dyn Fn(&str, LineDirection) + Send + Sync + 'static>;

const STDERR_CAPTURE_LIMIT: usize = 64 * 1024;
const STDERR_READ_BUFFER_SIZE: usize = 8 * 1024;
const STDERR_LINE_TRUNCATION_MARKER: &str = "… [stderr line truncated]";
pub(crate) const SHUTDOWN_GRACE_PERIOD: Duration = Duration::from_secs(1);

/// An ACP agent launched as a child of this daemon, in a chosen directory.
///
/// The child inherits the daemon's environment. Connecting it (via
/// [`ConnectTo`]) spawns the process and supervises it for the life of the
/// connection.
pub(crate) struct AcpProcess {
    command: PathBuf,
    args: Vec<String>,
    cwd: PathBuf,
    env: BTreeMap<String, String>,
    debug_callback: Option<DebugCallback>,
}

impl AcpProcess {
    pub(crate) fn new(
        command: impl Into<PathBuf>,
        args: Vec<String>,
        cwd: impl Into<PathBuf>,
    ) -> Self {
        Self {
            command: command.into(),
            args,
            cwd: cwd.into(),
            env: BTreeMap::new(),
            debug_callback: None,
        }
    }

    /// Add environment variables on top of the ones this process already has.
    ///
    /// The npm ACP adapters bundle their own copy of the CLI they wrap and
    /// take an absolute path to the one to run instead - `CODEX_PATH`,
    /// `CLAUDE_CODE_EXECUTABLE` - so the bridge and the model probe must be
    /// given the same variables or they inspect one CLI and run another.
    #[must_use]
    pub(crate) fn envs(mut self, env: impl IntoIterator<Item = (String, String)>) -> Self {
        self.env.extend(env);
        self
    }

    /// Observe every line crossing the child's stdin and stdout, plus its
    /// stderr. Exceptionally long stderr lines are truncated. The bridge taps
    /// lines in its own relay ([`RunningAgent::attach`]).
    #[cfg(test)]
    #[must_use]
    pub(crate) fn with_debug<Callback>(mut self, callback: Callback) -> Self
    where
        Callback: Fn(&str, LineDirection) + Send + Sync + 'static,
    {
        self.debug_callback = Some(Arc::new(callback));
        self
    }

    fn spawn(&self) -> Result<SpawnedChild, Error> {
        let mut command = std::process::Command::new(crate::executable::launchable(&self.command));
        command
            .args(&self.args)
            .current_dir(&self.cwd)
            .envs(&self.env)
            .stdin(std::process::Stdio::piped())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped());
        #[cfg(unix)]
        {
            use std::os::unix::process::CommandExt as _;

            // A handoff descriptor number means nothing in the agent.
            command.env_remove(crate::handoff::HANDOFF_ENV);
            // The child leads its own process group so `ChildGuard` can kill
            // the whole tree. Agents commonly sit behind wrapper launchers
            // (`npx …`, `uvx …`): killing only the immediate child orphans the
            // real agent, which re-parents to pid 1 and does not reliably exit
            // on stdin EOF.
            command.process_group(0);
        }

        // `kill_on_drop` covers a child dropped before `ChildGuard` holds it.
        let mut child = tokio::process::Command::from(command)
            .kill_on_drop(true)
            .spawn()
            .map_err(|error| internal_error(format!("Failed to spawn process: {error}")))?;
        let stdin = child
            .stdin
            .take()
            .ok_or_else(|| internal_error("Failed to open stdin"))?;
        let stdout = child
            .stdout
            .take()
            .ok_or_else(|| internal_error("Failed to open stdout"))?;
        let stderr = child
            .stderr
            .take()
            .ok_or_else(|| internal_error("Failed to open stderr"))?;

        Ok(SpawnedChild {
            stdin,
            stdout,
            stderr,
            guard: ChildGuard::new(child)
                .map_err(|error| internal_error(format!("Failed to supervise process: {error}")))?,
        })
    }
}

struct SpawnedChild {
    stdin: ChildStdin,
    stdout: ChildStdout,
    stderr: ChildStderr,
    guard: ChildGuard,
}

/// Kills the child - and its whole process group (Unix) or job (Windows) -
/// when dropped, unless it is handed on ([`ChildGuard::release`]).
struct ChildGuard {
    child: GuardedChild,
    /// Captured at spawn: tokio forgets the pid once the child is reaped, and
    /// the group kill must still reach descendants a wrapper left behind.
    #[cfg(unix)]
    process_group: Option<rustix::process::Pid>,
    #[cfg(windows)]
    job: job::Job,
}

enum GuardedChild {
    Spawned(Child),
    /// A child an earlier macrod process image spawned and handed over. It is
    /// still this process's child, so a blocking `waitpid` reaps it.
    /// `None` once its exit has been reported.
    #[cfg(unix)]
    Adopted(Option<tokio::sync::oneshot::Receiver<std::io::Result<std::process::ExitStatus>>>),
    /// Handed on to the next process image; nothing left to supervise.
    Released,
}

impl ChildGuard {
    fn new(child: Child) -> std::io::Result<Self> {
        #[cfg(unix)]
        let process_group = child
            .id()
            .and_then(|id| rustix::process::Pid::from_raw(id.cast_signed()));
        #[cfg(windows)]
        let job = child
            .raw_handle()
            .ok_or_else(|| std::io::Error::other("the child exited before it could be supervised"))
            .and_then(job::Job::containing)?;
        Ok(Self {
            child: GuardedChild::Spawned(child),
            #[cfg(unix)]
            process_group,
            #[cfg(windows)]
            job,
        })
    }

    /// Supervise a child this process inherited across `execve`. It leads
    /// its own process group, like every child [`AcpProcess`] spawns.
    #[cfg(unix)]
    fn adopt(pid: rustix::process::Pid) -> Self {
        let (exit_tx, exit) = tokio::sync::oneshot::channel();
        std::thread::spawn(move || {
            use std::os::unix::process::ExitStatusExt as _;

            let status = rustix::process::waitpid(Some(pid), rustix::process::WaitOptions::empty())
                .map_err(std::io::Error::from)
                .and_then(|status| {
                    status.ok_or_else(|| std::io::Error::other("waitpid returned no status"))
                })
                .map(|(_, status)| std::process::ExitStatus::from_raw(status.as_raw()));
            let _ = exit_tx.send(status);
        });
        Self {
            child: GuardedChild::Adopted(Some(exit)),
            process_group: Some(pid),
        }
    }

    async fn wait(&mut self) -> std::io::Result<std::process::ExitStatus> {
        match &mut self.child {
            GuardedChild::Spawned(child) => child.wait().await,
            #[cfg(unix)]
            GuardedChild::Adopted(pending_exit) => {
                let Some(exit) = pending_exit.as_mut() else {
                    return std::future::pending().await;
                };
                let status = exit
                    .await
                    .unwrap_or_else(|_| Err(std::io::Error::other("the child waiter stopped")));
                *pending_exit = None;
                status
            }
            GuardedChild::Released => std::future::pending().await,
        }
    }

    /// The child's pid, for handing it to the next process image.
    #[cfg(unix)]
    fn pid(&self) -> Option<rustix::process::Pid> {
        self.process_group
    }

    /// Stop supervising without killing: the child outlives this guard.
    #[cfg(unix)]
    fn release(&mut self) {
        // Forgotten, not dropped: tokio's `Child` kills on drop
        // (`kill_on_drop`) and would otherwise reap the process this image
        // no longer owns.
        if let GuardedChild::Spawned(child) =
            std::mem::replace(&mut self.child, GuardedChild::Released)
        {
            std::mem::forget(child);
        }
        self.process_group = None;
    }

    fn terminate(&mut self) {
        // SIGKILL the group first: it reaches grandchildren spawned by wrapper
        // launchers, and also the case where the direct child already exited
        // but its wrapper left the real agent running. An error (`ESRCH`)
        // just means the group is already gone.
        #[cfg(unix)]
        if let Some(process_group) = self.process_group {
            let _result =
                rustix::process::kill_process_group(process_group, rustix::process::Signal::KILL);
        }
        #[cfg(windows)]
        self.job.terminate();
        // A no-op double tap: the group or job already held the child.
        if let GuardedChild::Spawned(child) = &mut self.child {
            drop(child.start_kill());
        }
    }
}

impl Drop for ChildGuard {
    fn drop(&mut self) {
        self.terminate();
    }
}

#[derive(Default)]
struct StderrTail {
    bytes: VecDeque<u8>,
    truncated: bool,
}

impl StderrTail {
    fn push(&mut self, bytes: &[u8]) {
        if bytes.len() >= STDERR_CAPTURE_LIMIT {
            self.truncated |= !self.bytes.is_empty() || bytes.len() > STDERR_CAPTURE_LIMIT;
            self.bytes.clear();
            self.bytes
                .extend(bytes[bytes.len() - STDERR_CAPTURE_LIMIT..].iter().copied());
            return;
        }

        let overflow = self
            .bytes
            .len()
            .saturating_add(bytes.len())
            .saturating_sub(STDERR_CAPTURE_LIMIT);
        if overflow > 0 {
            self.truncated = true;
            drop(self.bytes.drain(..overflow));
        }
        self.bytes.extend(bytes.iter().copied());
    }

    fn into_string(mut self) -> String {
        let truncated = self.truncated;
        let stderr = String::from_utf8_lossy(self.bytes.make_contiguous());
        if truncated {
            format!("[stderr truncated; showing last {STDERR_CAPTURE_LIMIT} bytes]\n{stderr}")
        } else {
            stderr.into_owned()
        }
    }
}

#[derive(Default)]
struct StderrDebugLines {
    current: Vec<u8>,
    truncated: bool,
    pending_carriage_return: bool,
}

impl StderrDebugLines {
    fn push(&mut self, bytes: &[u8], callback: &DebugCallback) {
        for &byte in bytes {
            if self.pending_carriage_return {
                if byte == b'\n' {
                    self.pending_carriage_return = false;
                    self.emit(callback);
                    continue;
                }

                self.push_byte(b'\r');
                self.pending_carriage_return = false;
            }

            match byte {
                b'\r' => self.pending_carriage_return = true,
                b'\n' => self.emit(callback),
                byte => self.push_byte(byte),
            }
        }
    }

    fn finish(&mut self, callback: &DebugCallback) {
        if self.pending_carriage_return {
            self.push_byte(b'\r');
            self.pending_carriage_return = false;
        }
        if !self.current.is_empty() || self.truncated {
            self.emit(callback);
        }
    }

    fn push_byte(&mut self, byte: u8) {
        if self.current.len() < STDERR_CAPTURE_LIMIT {
            self.current.push(byte);
        } else {
            self.truncated = true;
        }
    }

    fn emit(&mut self, callback: &DebugCallback) {
        let line = String::from_utf8_lossy(&self.current);

        if self.truncated {
            let mut line = line.into_owned();
            line.push_str(STDERR_LINE_TRUNCATION_MARKER);
            callback(&line, LineDirection::Stderr);
        } else {
            callback(line.as_ref(), LineDirection::Stderr);
        }

        self.current.clear();
        self.truncated = false;
    }
}

struct StderrDrainResult {
    captured: String,
    read_error: Option<std::io::Error>,
}

/// Read stderr to EOF, or until `stop` resolves. Never leaving the pipe
/// unread matters: a full pipe buffer blocks the child.
async fn drain_stderr(
    stderr: &mut (impl futures::AsyncRead + Unpin),
    debug_callback: Option<DebugCallback>,
    stop: impl Future<Output = ()>,
) -> StderrDrainResult {
    use futures::AsyncReadExt as _;

    let mut tail = StderrTail::default();
    let mut debug_lines = debug_callback.as_ref().map(|_| StderrDebugLines::default());
    let mut buffer = [0; STDERR_READ_BUFFER_SIZE];
    let mut stop = pin!(stop);

    let read_error = loop {
        let read = tokio::select! {
            biased;
            () = &mut stop => break None,
            read = stderr.read(&mut buffer) => read,
        };
        match read {
            Ok(0) => break None,
            Ok(read) => {
                let bytes = &buffer[..read];
                tail.push(bytes);
                if let (Some(lines), Some(callback)) =
                    (debug_lines.as_mut(), debug_callback.as_ref())
                {
                    lines.push(bytes, callback);
                }
            }
            Err(error) => break Some(error),
        }
    };

    if let (Some(lines), Some(callback)) = (debug_lines.as_mut(), debug_callback.as_ref()) {
        lines.finish(callback);
    }

    StderrDrainResult {
        captured: tail.into_string(),
        read_error,
    }
}

struct ExitedChild {
    guard: ChildGuard,
    status: std::process::ExitStatus,
    stderr_rx: futures::channel::oneshot::Receiver<String>,
}

/// Wait for the direct child while retaining its process-group guard and
/// stderr receiver for exit reporting.
async fn wait_for_child(
    mut guard: ChildGuard,
    stderr_rx: futures::channel::oneshot::Receiver<String>,
) -> Result<ExitedChild, Error> {
    let status = guard
        .wait()
        .await
        .map_err(|error| internal_error(format!("Failed to wait for process: {error}")))?;

    Ok(ExitedChild {
        guard,
        status,
        stderr_rx,
    })
}

/// Report an observed child exit, including the bounded stderr tail for a
/// nonzero status.
async fn finish_child_exit(child: ExitedChild) -> Result<(), Error> {
    let ExitedChild {
        mut guard,
        status,
        stderr_rx,
    } = child;

    // A launcher may exit while a descendant remains alive holding inherited
    // stdio. Terminate the rest of the group before waiting for stderr EOF.
    guard.terminate();

    if status.success() {
        return Ok(());
    }

    let grace = pin!(tokio::time::sleep(SHUTDOWN_GRACE_PERIOD));
    let stderr = match futures::future::select(stderr_rx, grace).await {
        futures::future::Either::Left((stderr, _)) => stderr.unwrap_or_default(),
        futures::future::Either::Right((_, stderr_rx)) => {
            tracing::debug!(
                grace = ?SHUTDOWN_GRACE_PERIOD,
                "agent stderr remained open after process exit; reporting status without it"
            );
            drop(stderr_rx);
            String::new()
        }
    };

    let message = if stderr.is_empty() {
        format!("Process exited with {status}")
    } else {
        format!("Process exited with {status}: {stderr}")
    };

    Err(internal_error(message))
}

async fn await_protocol_shutdown_after_successful_child_exit<Protocol>(
    protocol_future: Protocol,
    grace: Duration,
) -> Result<(), Error>
where
    Protocol: Future<Output = Result<(), Error>> + Unpin,
{
    let timer = pin!(tokio::time::sleep(grace));
    match futures::future::select(protocol_future, timer).await {
        futures::future::Either::Left((result, _)) => result,
        futures::future::Either::Right((_, protocol_future)) => {
            tracing::debug!(
                ?grace,
                "protocol transport remained open after successful agent process exit; stopping it"
            );
            drop(protocol_future);
            Ok(())
        }
    }
}

async fn write_line<Writer>(writer: &mut Writer, line: String) -> std::io::Result<()>
where
    Writer: futures::AsyncWrite + Unpin + ?Sized,
{
    use futures::AsyncWriteExt as _;

    let mut bytes = line.into_bytes();
    bytes.push(b'\n');
    writer.write_all(&bytes).await?;
    writer.flush().await
}

async fn write_line_with_shutdown_timeout<Writer>(
    writer: &mut Writer,
    line: String,
    stdout_eof_rx: &mut Option<futures::channel::oneshot::Receiver<()>>,
    stdout_eof_seen: &mut bool,
    grace: Duration,
) -> std::io::Result<()>
where
    Writer: futures::AsyncWrite + Unpin + ?Sized,
{
    let write = Box::pin(write_line(writer, line));

    if *stdout_eof_seen {
        return await_write_during_shutdown(write, grace).await;
    }

    let Some(stdout_eof) = stdout_eof_rx.as_mut() else {
        return write.await;
    };

    match futures::future::select(write, stdout_eof).await {
        futures::future::Either::Left((result, _)) => result,
        futures::future::Either::Right((stdout_eof, write)) => {
            *stdout_eof_rx = None;
            if stdout_eof.is_err() {
                // Dropping the incoming stream cancels the signal. Only an
                // explicit send represents a clean EOF.
                return write.await;
            }

            *stdout_eof_seen = true;
            await_write_during_shutdown(write, grace).await
        }
    }
}

async fn await_write_during_shutdown<Write>(write: Write, grace: Duration) -> std::io::Result<()>
where
    Write: Future<Output = std::io::Result<()>> + Unpin,
{
    let timer = pin!(tokio::time::sleep(grace));
    match futures::future::select(write, timer).await {
        futures::future::Either::Left((result, _)) => result,
        futures::future::Either::Right((_, write)) => {
            tracing::debug!(
                ?grace,
                "pending protocol output did not drain after agent stdout closed"
            );
            drop(write);
            Err(std::io::Error::new(
                std::io::ErrorKind::TimedOut,
                format!(
                    "Agent closed its protocol output but pending protocol output did not drain within {grace:?}"
                ),
            ))
        }
    }
}

impl ConnectTo<Client> for AcpProcess {
    async fn connect_to(self, client: impl ConnectTo<Agent>) -> Result<(), Error> {
        use futures::io::BufReader;
        use futures::{AsyncBufReadExt as _, StreamExt as _};

        let SpawnedChild {
            stdin,
            stdout,
            stderr,
            guard,
        } = self.spawn()?;

        let (stderr_tx, stderr_rx) = futures::channel::oneshot::channel::<String>();

        // Raced against the protocol below, so it runs on this task.
        let debug_callback = self.debug_callback.clone();
        let stderr_future = async move {
            let StderrDrainResult {
                captured,
                read_error,
            } = drain_stderr(&mut stderr.compat(), debug_callback, std::future::pending()).await;
            drop(stderr_tx.send(captured));

            if let Some(error) = read_error {
                tracing::warn!(
                    ?error,
                    "failed to read process stderr; stderr will no longer be captured"
                );
            }
        };

        // The guard already exists, so cancelling this connection before the
        // monitor is first polled still terminates the whole process group.
        let child_wait = wait_for_child(guard, stderr_rx);

        let incoming_lines: std::pin::Pin<
            Box<dyn futures::Stream<Item = std::io::Result<String>> + Send>,
        > = if let Some(callback) = self.debug_callback.clone() {
            Box::pin(
                BufReader::new(stdout.compat())
                    .lines()
                    .inspect(move |result| {
                        if let Ok(line) = result {
                            callback(line, LineDirection::Stdout);
                        }
                    }),
            )
        } else {
            Box::pin(BufReader::new(stdout.compat()).lines())
        };

        // The JSON-RPC transport keeps polling stdout while it drains stdin.
        // Signal physical EOF so a child that half-closes stdout and stops
        // reading cannot hold a final write open forever. Dropping this stream
        // merely cancels the signal and is not treated as EOF.
        let (stdout_eof_tx, stdout_eof_rx) = futures::channel::oneshot::channel();
        let mut stdout_eof_tx = Some(stdout_eof_tx);
        let mut incoming_lines = incoming_lines;
        let incoming_lines = Box::pin(futures::stream::poll_fn(move |context| {
            let next = incoming_lines.as_mut().poll_next(context);
            if matches!(next, std::task::Poll::Ready(None))
                && let Some(stdout_eof_tx) = stdout_eof_tx.take()
            {
                let _ = stdout_eof_tx.send(());
            }
            next
        }));

        let outgoing_sink: std::pin::Pin<
            Box<dyn futures::Sink<String, Error = std::io::Error> + Send>,
        > = Box::pin(futures::sink::unfold(
            (
                stdin.compat_write(),
                self.debug_callback.clone(),
                Some(stdout_eof_rx),
                false,
            ),
            async move |(mut writer, callback, mut stdout_eof_rx, mut stdout_eof_seen),
                        line: String| {
                if let Some(callback) = callback.as_ref() {
                    callback(&line, LineDirection::Stdin);
                }
                write_line_with_shutdown_timeout(
                    &mut writer,
                    line,
                    &mut stdout_eof_rx,
                    &mut stdout_eof_seen,
                    SHUTDOWN_GRACE_PERIOD,
                )
                .await?;
                Ok::<_, std::io::Error>((writer, callback, stdout_eof_rx, stdout_eof_seen))
            },
        ));

        let protocol_future =
            ConnectTo::<Client>::connect_to(Lines::new(outgoing_sink, incoming_lines), client);

        let stderr_future = pin!(stderr_future);
        let protocol_future = Box::pin(protocol_future);
        let child_wait = Box::pin(child_wait);

        // Errors stop the connection immediately. After protocol shutdown
        // succeeds, the child gets a bounded grace period so delayed failures
        // remain observable without a non-exiting launcher hanging shutdown.
        let main_race = async {
            match futures::future::select(protocol_future, child_wait).await {
                futures::future::Either::Left((result, child_wait)) => {
                    result?;
                    let grace = pin!(tokio::time::sleep(SHUTDOWN_GRACE_PERIOD));
                    match futures::future::select(child_wait, grace).await {
                        futures::future::Either::Left((child, _)) => {
                            finish_child_exit(child?).await
                        }
                        futures::future::Either::Right((_, child_wait)) => {
                            tracing::debug!(
                                grace = ?SHUTDOWN_GRACE_PERIOD,
                                "agent process did not exit after protocol shutdown; terminating it"
                            );
                            drop(child_wait);
                            Ok(())
                        }
                    }
                }
                futures::future::Either::Right((child, protocol_future)) => {
                    finish_child_exit(child?).await?;
                    await_protocol_shutdown_after_successful_child_exit(
                        protocol_future,
                        SHUTDOWN_GRACE_PERIOD,
                    )
                    .await
                }
            }
        };

        // Once the main race completes, stderr is no longer needed.
        let main_race = pin!(main_race);
        match futures::future::select(main_race, stderr_future).await {
            futures::future::Either::Left((result, _)) => result,
            futures::future::Either::Right(((), main_race)) => main_race.await,
        }
    }
}