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.

12.2 KB
Raw Blame
//! A spawned ACP agent relayed line by line, which on Unix can be handed to
//! the next macrod process image without stopping.
//!
//! [`AcpProcess::connect_to`] drives an agent through the SDK, which owns
//! the reads and writes. The harness bridge instead relays raw lines, and
//! needs what the SDK cannot give it: to stop reading at a line boundary,
//! finish the writes already queued, and take the pipes back.

use std::time::Duration;

use agent_client_protocol::util::internal_error;
use agent_client_protocol::{Error, LineDirection};
use tokio::io::{AsyncBufReadExt as _, AsyncWriteExt as _, BufReader};
use tokio::process::{ChildStderr, ChildStdin, ChildStdout};
use tokio::sync::{mpsc, oneshot};
use tokio::task::JoinHandle;
use tokio_util::compat::TokioAsyncReadCompatExt as _;

use super::{
    AcpProcess, ChildGuard, DebugCallback, SHUTDOWN_GRACE_PERIOD, SpawnedChild, StderrDrainResult,
    drain_stderr,
};

/// An agent process this daemon started (or inherited), not yet relayed.
pub(crate) struct RunningAgent {
    stdin: ChildStdin,
    stdout: ChildStdout,
    stderr: ChildStderr,
    /// Output read past the last relayed line. Always the start of a line.
    pending_output: Vec<u8>,
    guard: ChildGuard,
}

impl AcpProcess {
    /// Spawn the agent for a line relay ([`RunningAgent::attach`]).
    pub(crate) fn start(&self) -> Result<RunningAgent, Error> {
        let SpawnedChild {
            stdin,
            stdout,
            stderr,
            guard,
        } = self.spawn()?;
        Ok(RunningAgent {
            stdin,
            stdout,
            stderr,
            pending_output: Vec::new(),
            guard,
        })
    }
}

impl RunningAgent {
    /// Start relaying: stdout is split into lines, stdin takes lines, and
    /// stderr is drained. `debug` sees every line in every direction.
    pub(crate) fn attach(self, debug: DebugCallback) -> AttachedAgent {
        let Self {
            stdin,
            stdout,
            mut stderr,
            pending_output,
            guard,
        } = self;

        let (lines_tx, lines) = mpsc::unbounded_channel();
        let (stop_reading, reading_stopped) = oneshot::channel();
        let reader = tokio::spawn(read_lines(
            BufReader::new(stdout),
            pending_output,
            lines_tx,
            reading_stopped,
            debug.clone(),
        ));

        let (writes, writes_rx) = mpsc::unbounded_channel();
        let writer = tokio::spawn(write_lines(stdin, writes_rx, debug.clone()));

        let (stop_stderr, stderr_stopped) = oneshot::channel::<()>();
        let stderr_task = tokio::spawn(async move {
            let drained = drain_stderr(&mut (&mut stderr).compat(), Some(debug), async {
                let _ = stderr_stopped.await;
            })
            .await;
            (stderr, drained)
        });

        AttachedAgent {
            lines,
            stop_reading: Some(stop_reading),
            reader,
            writes,
            writer,
            stop_stderr,
            stderr: stderr_task,
            guard,
        }
    }
}

/// What the relayed agent did next.
pub(crate) enum AgentEvent {
    /// An output line, or `None` once its stdout ended.
    Line(Option<String>),
    /// The process exited.
    Exited(std::io::Result<std::process::ExitStatus>),
}

/// An agent whose stdio is being relayed.
pub(crate) struct AttachedAgent {
    lines: mpsc::UnboundedReceiver<String>,
    stop_reading: Option<oneshot::Sender<()>>,
    reader: JoinHandle<std::io::Result<(BufReader<ChildStdout>, Vec<u8>)>>,
    writes: mpsc::UnboundedSender<String>,
    writer: JoinHandle<std::io::Result<ChildStdin>>,
    stop_stderr: oneshot::Sender<()>,
    stderr: JoinHandle<(ChildStderr, StderrDrainResult)>,
    guard: ChildGuard,
}

impl AttachedAgent {
    /// The agent's next output line; `None` once its stdout has ended or
    /// reading was stopped and every line read before is delivered.
    pub(crate) async fn next_line(&mut self) -> Option<String> {
        self.lines.recv().await
    }

    /// Queue a line for the agent's stdin. Lines are written whole and in
    /// order.
    pub(crate) fn send_line(&self, line: String) -> std::io::Result<()> {
        self.writes
            .send(line)
            .map_err(|_| std::io::Error::other("the agent's stdin writer stopped"))
    }

    /// Resolves when the agent process exits. Cancel-safe.
    pub(crate) async fn exited(&mut self) -> std::io::Result<std::process::ExitStatus> {
        self.guard.wait().await
    }

    /// The next output line or the process exit, whichever comes first.
    /// Cancel-safe.
    pub(crate) async fn next_event(&mut self) -> AgentEvent {
        tokio::select! {
            line = self.lines.recv() => AgentEvent::Line(line),
            status = self.guard.wait() => AgentEvent::Exited(status),
        }
    }

    /// Stop reading after the line in progress; [`Self::next_line`] then
    /// returns what was already read, then `None`.
    pub(crate) fn stop_reading(&mut self) {
        if let Some(stop) = self.stop_reading.take() {
            let _ = stop.send(());
        }
    }

    /// End the relay after the agent exited with `status`: the rest of its
    /// process group is killed, and a failure carries the stderr tail.
    pub(crate) async fn finish(self, status: std::process::ExitStatus) -> Result<(), Error> {
        let Self {
            mut guard,
            stderr,
            stop_stderr,
            reader,
            writer,
            ..
        } = self;
        // A launcher may exit while a descendant still holds its stdio.
        guard.terminate();
        reader.abort();
        writer.abort();
        if status.success() {
            stderr.abort();
            return Ok(());
        }
        let captured = match tokio::time::timeout(SHUTDOWN_GRACE_PERIOD, stderr).await {
            Ok(Ok((_, drained))) => drained.captured,
            _ => {
                drop(stop_stderr);
                String::new()
            }
        };
        if captured.is_empty() {
            Err(internal_error(format!("Process exited with {status}")))
        } else {
            Err(internal_error(format!(
                "Process exited with {status}: {captured}"
            )))
        }
    }

    /// Take the agent back from the relay without stopping it: reading has
    /// stopped ([`Self::stop_reading`]) and every line read was taken, the
    /// queued writes are flushed, and what was read past the last line is
    /// kept for whoever relays the agent next.
    #[cfg(unix)]
    pub(crate) async fn detach(self, within: Duration) -> std::io::Result<RunningAgent> {
        let Self {
            lines,
            stop_reading,
            reader,
            writes,
            writer,
            stop_stderr,
            stderr,
            guard,
        } = self;
        debug_assert!(stop_reading.is_none(), "stop reading before detaching");
        drop(lines);
        drop(writes);
        let _ = stop_stderr.send(());
        let detached = async {
            let (stdout, pending_output) = reader.await.map_err(std::io::Error::other)??;
            let stdin = writer.await.map_err(std::io::Error::other)??;
            let (stderr, _) = stderr.await.map_err(std::io::Error::other)?;
            Ok::<_, std::io::Error>(RunningAgent {
                stdin,
                stdout: stdout.into_inner(),
                stderr,
                pending_output,
                guard,
            })
        };
        tokio::time::timeout(within, detached)
            .await
            .map_err(|_| std::io::Error::other("the agent's pipes did not settle in time"))?
    }
}

/// Split stdout into lines until EOF or `stop`. On stop, returns the reader
/// and the bytes read past the last full line, so nothing is lost.
async fn read_lines(
    mut stdout: BufReader<ChildStdout>,
    mut partial: Vec<u8>,
    lines: mpsc::UnboundedSender<String>,
    mut stop: oneshot::Receiver<()>,
    debug: DebugCallback,
) -> std::io::Result<(BufReader<ChildStdout>, Vec<u8>)> {
    // Output handed over by an earlier process image may hold whole lines.
    while let Some(end) = partial.iter().position(|byte| *byte == b'\n') {
        deliver(partial.drain(..=end).collect(), &lines, &debug);
    }
    loop {
        // `partial` survives a cancelled `read_until`: whatever it read stays
        // in it, and the rest stays in the reader's buffer.
        tokio::select! {
            biased;
            _ = &mut stop => {
                let mut unread = partial;
                unread.extend_from_slice(stdout.buffer());
                let buffered = stdout.buffer().len();
                stdout.consume(buffered);
                return Ok((stdout, unread));
            }
            read = stdout.read_until(b'\n', &mut partial) => {
                if read? == 0 {
                    // EOF: an unterminated last line is still a line.
                    if !partial.is_empty() {
                        deliver(std::mem::take(&mut partial), &lines, &debug);
                    }
                    return Ok((stdout, Vec::new()));
                }
                if partial.last() == Some(&b'\n') {
                    deliver(std::mem::take(&mut partial), &lines, &debug);
                }
            }
        }
    }
}

fn deliver(mut line: Vec<u8>, lines: &mpsc::UnboundedSender<String>, debug: &DebugCallback) {
    if line.last() == Some(&b'\n') {
        line.pop();
    }
    if line.last() == Some(&b'\r') {
        line.pop();
    }
    if line.is_empty() {
        return;
    }
    match String::from_utf8(line) {
        Ok(line) => {
            debug(&line, LineDirection::Stdout);
            let _ = lines.send(line);
        }
        Err(error) => tracing::warn!(error = %error, "dropping a non-UTF-8 line from the agent"),
    }
}

/// Write each queued line whole, then hand stdin back once the queue closes.
async fn write_lines(
    mut stdin: ChildStdin,
    mut writes: mpsc::UnboundedReceiver<String>,
    debug: DebugCallback,
) -> std::io::Result<ChildStdin> {
    while let Some(line) = writes.recv().await {
        debug(&line, LineDirection::Stdin);
        let mut bytes = line.into_bytes();
        bytes.push(b'\n');
        stdin.write_all(&bytes).await?;
        stdin.flush().await?;
    }
    Ok(stdin)
}

#[cfg(unix)]
mod handoff {
    use std::os::fd::OwnedFd;

    use super::{ChildGuard, RunningAgent};
    use crate::handoff::{HandedOffAgent, HandedOffParts};
    use crate::turns::ActiveTurns;

    impl RunningAgent {
        /// Pick up an agent the previous process image handed over, and the
        /// turns it had running.
        pub(crate) fn adopt(agent: HandedOffAgent, turns: &ActiveTurns) -> std::io::Result<Self> {
            let HandedOffParts {
                pid,
                stdin,
                stdout,
                stderr,
                pending_output,
                active_prompts,
            } = agent.into_parts();
            turns.restore(active_prompts);
            let guard = ChildGuard::adopt(pid);
            Ok(Self {
                stdin: tokio::process::ChildStdin::from_std(std::process::ChildStdin::from(stdin))?,
                stdout: tokio::process::ChildStdout::from_std(std::process::ChildStdout::from(
                    stdout,
                ))?,
                stderr: tokio::process::ChildStderr::from_std(std::process::ChildStderr::from(
                    stderr,
                ))?,
                pending_output,
                guard,
            })
        }

        /// Hand the agent to the next process image. It keeps running; the
        /// guard no longer kills it.
        pub(crate) fn hand_off(
            mut self,
            active_prompts: Vec<String>,
        ) -> std::io::Result<HandedOffAgent> {
            let pid = self
                .guard
                .pid()
                .ok_or_else(|| std::io::Error::other("the agent has no pid"))?;
            let stdin: OwnedFd = self.stdin.into_owned_fd()?;
            let stdout: OwnedFd = self.stdout.into_owned_fd()?;
            let stderr: OwnedFd = self.stderr.into_owned_fd()?;
            self.guard.release();
            Ok(HandedOffAgent::new(
                pid,
                stdin,
                stdout,
                stderr,
                self.pending_output,
                active_prompts,
            ))
        }
    }
}