Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! `macrod herdr-acp`: an ACP agent whose sessions are live coding-agent TUIs
//! (Claude Code or Codex) in herdr windows.
//!
//! macrod runs this as its harness like any other ACP agent, so sessions
//! still open, prompt, stream, and stop through Macro's ACP infrastructure.
//! Behind the protocol, each session is a real interactive `claude` or
//! `codex` in its own herdr tab, rooted at the session's working directory:
//!
//! - the first `session/prompt` opens the tab and starts the agent there
//! with the session's model and Macro MCP servers;
//! - prompts are typed into the TUI with `herdr agent prompt`;
//! - the agent's own session transcript is tailed and streamed back as
//! `session/update`s, and its end-of-turn record ends the turn;
//! - a permission dialog in the TUI becomes a `session/request_permission`,
//! answered by pressing the matching key (see `permission`);
//! `session/cancel` presses Esc.
//!
//! Anyone watching the herdr window can also type into the TUI directly.
use std::collections::{HashMap, VecDeque};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use serde_json::{Value, json};
use tokio::io::{AsyncBufReadExt as _, AsyncWriteExt as _, BufReader};
use tokio::sync::{mpsc, oneshot};
use tokio_util::sync::CancellationToken;
use tracing::Instrument as _;
use super::HerdrSession;
use super::cli::{AgentLaunch, HerdrCli, HerdrError};
use super::hub::title_from;
use super::store::{Record, Store, write_private};
use super::tail::Cursor;
use agent_client_protocol::schema::v1::{
ListSessionsRequest, ListSessionsResponse, SessionId, SessionInfo,
};
use agent_fold::domain::transcript::{Fold, LogEvent};
use agent_runtime_protocol::domain::turn::{FailureNotice, FailureNoticeKind};
use claude_fold::ClaudeLog;
use codex_fold::CodexLog;
mod commands;
mod effort;
mod models;
mod permission;
#[cfg(test)]
use permission::permission_title;
use permission::{OpenTool, track_open_tool};
/// The subcommand macrod's harness config names to run this adapter.
pub(crate) const SUBCOMMAND: &str = "herdr-acp";
const MODEL_CONFIG_ID: &str = "model";
/// Attempts to read one native agent's state while listing live sessions.
const LIVE_SESSION_LOOKUPS: usize = 3;
const DEFAULT_MODEL: &str = "default";
const CLAUDE_MODELS: &[(&str, &str)] = &[
(DEFAULT_MODEL, "Default (Claude Code's choice)"),
("opus", "Opus"),
("sonnet", "Sonnet"),
("haiku", "Haiku"),
];
const CODEX_MODELS: &[(&str, &str)] = &[
(DEFAULT_MODEL, "Default (Codex's choice)"),
("gpt-6-astra", "GPT-6 Astra"),
("gpt-5.6", "GPT-5.6"),
("gpt-5.5", "GPT-5.5"),
];
const POLL: Duration = Duration::from_millis(250);
/// Transcript polls per herdr status check.
const STATUS_EVERY: u32 = 4;
/// Consecutive ready status checks, with no transcript ending, that end a
/// turn anyway (slash commands and interrupted turns write no final message).
const SETTLED_CHECKS: u32 = 3;
/// How long the transcript must stay quiet before a ready status ends a turn.
const SETTLED_QUIET: Duration = Duration::from_secs(3);
const QUIET_START: Duration = Duration::from_secs(20);
const MISSING_AGENT_CHECKS: u32 = 5;
/// Esc presses a cancel spends before the native turn is left to run.
const INTERRUPT_PRESSES: u32 = 3;
/// Status checks, one per [`POLL`], after each Esc press.
const INTERRUPT_CHECKS: u32 = 4;
/// Transcript polls per check, while idle, that the session's native agent
/// still exists in herdr.
const CLOSED_CHECK_EVERY: u32 = 20;
/// How long that check may take before it is skipped as inconclusive.
const CLOSED_CHECK_TIMEOUT: Duration = Duration::from_secs(2);
/// Which coding-agent TUI each session runs.
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
clap::ValueEnum,
serde::Serialize,
serde::Deserialize,
)]
pub(crate) enum TuiAgent {
/// Claude Code (`claude`).
#[default]
Claude,
/// OpenAI Codex (`codex`).
Codex,
}
impl TuiAgent {
/// herdr's `--kind` for the agent, which is also its command.
pub(crate) fn herdr_kind(self) -> &'static str {
match self {
Self::Claude => "claude",
Self::Codex => "codex",
}
}
/// Whether the TUI reports its own status through OSC 7501, which
/// herdr-core relies on to see it working, blocked, or ready.
pub(crate) fn reports_status(self) -> bool {
match self {
Self::Claude => true,
Self::Codex => false,
}
}
fn models(self) -> &'static [(&'static str, &'static str)] {
match self {
Self::Claude => CLAUDE_MODELS,
Self::Codex => CODEX_MODELS,
}
}
fn log(self) -> Transcript {
match self {
Self::Claude => Transcript::Claude(ClaudeLog::default()),
Self::Codex => Transcript::Codex(CodexLog::default()),
}
}
}
/// A session transcript reader for the agent that writes it.
enum Transcript {
Claude(ClaudeLog),
Codex(CodexLog),
}
impl Transcript {
fn entry(&mut self, line: &str) -> Vec<LogEvent> {
match self {
Self::Claude(log) => log.entry(line),
Self::Codex(log) => log.entry(line),
}
}
}
/// How `macrod herdr-acp` runs its agents.
#[derive(Debug, Clone, Default)]
pub(crate) struct AdapterOptions {
/// Private storage shared with the dispatcher's repository preparation.
pub state_dir: Option<PathBuf>,
/// Native model ID for new sessions.
pub model: Option<String>,
/// Sessions use dispatcher-managed worktrees.
pub managed_worktrees: bool,
/// The agent TUI sessions run.
pub kind: TuiAgent,
/// Passed to Claude Code as `--permission-mode`.
pub permission_mode: Option<String>,
/// Open session windows in the background instead of switching to them.
pub no_focus: bool,
/// Extra arguments for every agent launch, after the adapter's own.
pub agent_args: Vec<String>,
}
#[derive(Debug)]
struct RpcError {
code: i64,
message: String,
data: Option<Value>,
}
impl RpcError {
fn internal(message: impl Into<String>) -> Self {
Self {
code: -32603,
message: message.into(),
data: None,
}
}
fn invalid(message: impl Into<String>) -> Self {
Self {
code: -32602,
message: message.into(),
data: None,
}
}
/// A prompt that was stopped before it was typed into the TUI. Answering
/// `cancelled` would read in Macro as a message the agent saw.
fn not_delivered() -> Self {
let notice = FailureNotice {
kind: FailureNoticeKind::PromptNotDelivered,
title: "Message not delivered".to_owned(),
body: "The turn running in Herdr was stopped before this message was typed in, so the agent never received it. Send it again.".to_owned(),
link: None,
};
Self {
code: -32603,
message: "the prompt was stopped before it reached the native agent".to_owned(),
data: serde_json::to_value(notice).ok(),
}
}
}
impl From<HerdrError> for RpcError {
fn from(error: HerdrError) -> Self {
Self::internal(error.to_string())
}
}
mod environment {
macro_env_var::maybe_env_var! {
pub struct Home;
}
}
/// Serve ACP on stdin/stdout until stdin closes.
pub async fn run(options: AdapterOptions) -> rootcause::Result<()> {
let (out_tx, mut out_rx) = mpsc::unbounded_channel::<Value>();
let writer = tokio::spawn(async move {
let mut stdout = tokio::io::stdout();
while let Some(message) = out_rx.recv().await {
let mut line = message.to_string();
line.push('\n');
if stdout.write_all(line.as_bytes()).await.is_err() || stdout.flush().await.is_err() {
return;
}
}
});
let herdr = HerdrSession::detect();
let home = environment::Home::new().and_then(|home| home.value().map(PathBuf::from));
let state_dir = options
.state_dir
.clone()
.or_else(|| {
home.as_ref()
.map(|home| home.join(".macrod/herdr/standalone"))
})
.ok_or_else(|| rootcause::report!("HOME or --state-dir is required"))?;
let shutdown = CancellationToken::new();
let adapter = Arc::new(Adapter {
out: out_tx,
pending: Mutex::new(HashMap::new()),
next_id: AtomicU64::new(0),
sessions: Mutex::new(HashMap::new()),
herdr: herdr.as_ref().map(HerdrSession::cli),
options,
home,
store: Store(state_dir),
shutdown: shutdown.clone(),
claimed: Mutex::new(std::collections::HashSet::new()),
});
let mut requests = tokio::task::JoinSet::new();
let mut lines = BufReader::new(tokio::io::stdin()).lines();
while let Some(line) = lines.next_line().await? {
while requests.try_join_next().is_some() {}
let Ok(message) = serde_json::from_str::<Value>(&line) else {
continue;
};
let id = message.get("id").filter(|id| !id.is_null()).cloned();
let params = message.get("params").cloned().unwrap_or(Value::Null);
match (message.get("method").and_then(Value::as_str), id) {
(Some(method), Some(id)) => {
let adapter = adapter.clone();
let method = method.to_owned();
requests.spawn(async move {
let prompt_session = if method == "session/prompt" {
adapter.session(¶ms).ok()
} else {
None
};
if prompt_session
.as_ref()
.is_some_and(|session| session.prompt_pending.swap(true, Ordering::SeqCst))
{
adapter.respond(
id,
Err(RpcError::invalid("a prompt is already in progress")),
);
return;
}
adapter.respond_to_request(id, &method, params).await;
if let Some(session) = prompt_session {
session.prompt_pending.store(false, Ordering::SeqCst);
}
});
}
(Some("session/cancel"), None) => adapter.cancel(¶ms),
(Some(_), None) => {}
(None, Some(id)) => adapter.answered(&id, message),
(None, None) => {}
}
}
shutdown.cancel();
requests.abort_all();
while requests.join_next().await.is_some() {}
lock(&adapter.pending).clear();
drop(adapter);
let _ = writer.await;
Ok(())
}
struct Adapter {
store: Store,
shutdown: CancellationToken,
out: mpsc::UnboundedSender<Value>,
pending: Mutex<HashMap<String, oneshot::Sender<Value>>>,
next_id: AtomicU64,
sessions: Mutex<HashMap<String, Arc<Session>>>,
herdr: Option<HerdrCli>,
options: AdapterOptions,
home: Option<PathBuf>,
/// Transcripts already bound to a session, so two sessions in the same
/// directory never read the same Codex rollout.
claimed: Mutex<std::collections::HashSet<PathBuf>>,
}
struct Session {
id: String,
cwd: PathBuf,
mcp_servers: Vec<Value>,
model: Mutex<String>,
effort: Mutex<Option<String>>,
native_id: Mutex<Option<String>>,
prompt_pending: AtomicBool,
live: tokio::sync::Mutex<Option<Live>>,
cancel: Mutex<Option<CancellationToken>>,
/// Tools a user in Macro chose to always allow for this session, where
/// the native dialog had no "don't ask again" answer of its own.
always_allowed: Mutex<std::collections::HashSet<String>>,
}
struct PermissionEpoch(Arc<AtomicU64>);
impl Drop for PermissionEpoch {
fn drop(&mut self) {
self.0.fetch_add(1, Ordering::SeqCst);
}
}
struct PromptCancellation<'a>(&'a Mutex<Option<CancellationToken>>);
impl Drop for PromptCancellation<'_> {
fn drop(&mut self) {
lock(self.0).take();
}
}
/// A session's running TUI.
struct Live {
session: String,
cwd: PathBuf,
started: std::time::SystemTime,
name: String,
log: Transcript,
path: Option<PathBuf>,
cursor: Cursor,
pending: VecDeque<LogEvent>,
/// This process launched the agent or saw it running. Only such an
/// agent's disappearance is a close: a session restored after herdr
/// itself restarted finds every agent gone without anyone closing them.
seen_alive: bool,
/// `_session/closed` was sent for this agent. A relaunch starts a new
/// `Live`, so a later close of the new agent is reported again.
closed_reported: bool,
}
fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
impl Adapter {
fn send(&self, message: Value) {
let _ = self.out.send(message);
}
fn respond(&self, id: Value, result: Result<Value, RpcError>) {
self.send(match result {
Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}),
Err(error) => {
let mut body = json!({"code": error.code, "message": error.message});
if let Some(data) = error.data {
body["data"] = data;
}
json!({"jsonrpc": "2.0", "id": id, "error": body})
}
});
}
fn notify_update(&self, session: &str, update: Value) {
self.send(json!({
"jsonrpc": "2.0",
"method": "session/update",
"params": {"sessionId": session, "update": update},
}));
}
/// Send a request to the client and wait for its answer.
async fn call(&self, method: &str, params: Value) -> Option<Value> {
let id = format!(
"macrod-herdr-{}",
self.next_id.fetch_add(1, Ordering::Relaxed)
);
let (tx, rx) = oneshot::channel();
lock(&self.pending).insert(Value::String(id.clone()).to_string(), tx);
self.send(json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}));
let answer = tokio::select! {
answer = rx => answer.ok(),
() = self.shutdown.cancelled() => None,
};
lock(&self.pending).remove(&Value::String(id).to_string());
answer
}
fn answered(&self, id: &Value, message: Value) {
if let Some(waiter) = lock(&self.pending).remove(&id.to_string()) {
let _ = waiter.send(message);
}
}
fn session(&self, params: &Value) -> Result<Arc<Session>, RpcError> {
let id = params
.get("sessionId")
.and_then(Value::as_str)
.ok_or_else(|| RpcError::invalid("missing sessionId"))?;
lock(&self.sessions)
.get(id)
.cloned()
.ok_or_else(|| RpcError::invalid(format!("unknown session {id}")))
}
fn cancel(self: &Arc<Self>, params: &Value) {
let Ok(session) = self.session(params) else {
return;
};
if let Some(cancel) = lock(&session.cancel).as_ref() {
cancel.cancel();
return;
}
let Some(herdr) = self.herdr.clone() else {
return;
};
let name = agent_name(&session.id);
let native_id = lock(&session.native_id).clone();
tokio::spawn(async move {
let Ok(info) = herdr.agent_info(&name).await else {
return;
};
if native_id.is_none()
|| info.session_id != native_id
|| !matches!(info.status.as_str(), "working" | "blocked")
{
return;
}
match interrupt(&herdr, &name).await {
Ok(true) => {}
Ok(false) => tracing::warn!(%name, "the native turn kept running after Esc"),
Err(error) => tracing::warn!(%error, "could not interrupt native turn"),
}
});
}
async fn request(self: &Arc<Self>, method: &str, params: Value) -> Result<Value, RpcError> {
match method {
"initialize" => Ok(json!({
"protocolVersion": 1,
"agentCapabilities": {
"loadSession": true,
"sessionCapabilities": {"list": {}},
"promptCapabilities": {"image": false, "audio": false, "embeddedContext": false},
},
"authMethods": [],
"agentInfo": {"name": "macrod-herdr", "version": env!("CARGO_PKG_VERSION")},
})),
"session/list" => {
let request = serde_json::from_value::<ListSessionsRequest>(params)
.map_err(|error| RpcError::invalid(error.to_string()))?;
serde_json::to_value(self.list_sessions(request.cwd.as_deref()).await)
.map_err(|error| RpcError::internal(error.to_string()))
}
"session/new" => self.new_session(¶ms),
"session/load" => self.load_session(¶ms).await,
"session/set_config_option" => {
let session = self.session(¶ms)?;
let value = params
.get("value")
.and_then(Value::as_str)
.ok_or_else(|| RpcError::invalid("missing configuration value"))?;
match params.get("configId").and_then(Value::as_str) {
Some(MODEL_CONFIG_ID) => self.set_model(&session, value).await,
Some(effort::CONFIG_ID) if self.options.kind == TuiAgent::Codex => {
self.set_effort(&session, value).await
}
_ => Err(RpcError::invalid("unsupported configuration option")),
}
}
"session/prompt" => {
let session = self.session(¶ms)?;
let text = prompt_text(params.get("prompt").unwrap_or(&Value::Null));
self.prompt(&session, &text)
.await
.map(|stop| json!({"stopReason": stop}))
}
_ => Err(RpcError {
code: -32601,
message: format!("{method} is not supported"),
data: None,
}),
}
}
/// `session/list`: stored sessions whose Herdr agent still runs, oldest
/// first, in `cwd` when given. Read-only: the client's following
/// `session/load` attaches them. A closed agent is not live, so it is
/// never reopened; other lookup failures are retried before a session is
/// left out.
async fn list_sessions(&self, cwd: Option<&Path>) -> ListSessionsResponse {
use futures::StreamExt as _;
let Some(herdr) = &self.herdr else {
return ListSessionsResponse::new(Vec::new());
};
let mut records: Vec<Record> = futures::stream::iter(
self.store.list().into_iter().filter(|record| {
record.kind == self.options.kind && cwd.is_none_or(|cwd| record.cwd == cwd)
}),
)
.map(|record| async move {
let name = agent_name(&record.id);
for _ in 0..LIVE_SESSION_LOOKUPS {
match herdr.agent_info(&name).await {
Ok(_) => return Some(record),
Err(error) if error.missing_agent() => return None,
Err(error) => {
tracing::warn!(%name, %error, "could not tell whether a native agent still runs");
}
}
}
None
})
.buffer_unordered(8)
.filter_map(std::future::ready)
.collect()
.await;
records.sort_by(|a, b| a.started.cmp(&b.started).then_with(|| a.id.cmp(&b.id)));
ListSessionsResponse::new(
records
.into_iter()
.map(|record| SessionInfo::new(SessionId::new(record.id), record.cwd))
.collect(),
)
}
fn new_session(self: &Arc<Self>, params: &Value) -> Result<Value, RpcError> {
let id = uuid::Uuid::new_v4().to_string();
let cwd = params
.get("cwd")
.and_then(Value::as_str)
.map(PathBuf::from)
.ok_or_else(|| RpcError::invalid("missing cwd"))?;
let session = Arc::new(Session {
id: id.clone(),
cwd,
mcp_servers: params
.get("mcpServers")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default(),
model: Mutex::new(
self.options
.model
.clone()
.unwrap_or_else(|| DEFAULT_MODEL.to_owned()),
),
native_id: Mutex::new(None),
effort: Mutex::new(None),
prompt_pending: AtomicBool::new(false),
live: tokio::sync::Mutex::new(None),
cancel: Mutex::new(None),
always_allowed: Mutex::new(std::collections::HashSet::new()),
});
self.save(&session, None)?;
lock(&self.sessions).insert(id.clone(), session.clone());
self.observe(&session);
Ok(json!({"sessionId": id, "configOptions": self.session_options(&session)}))
}
fn save(&self, session: &Session, live: Option<&Live>) -> Result<(), RpcError> {
self.store
.save(&Record {
version: 1,
id: session.id.clone(),
kind: self.options.kind,
cwd: session.cwd.clone(),
model: lock(&session.model).clone(),
native_id: lock(&session.native_id).clone(),
transcript: live.and_then(|live| live.path.clone()),
started: live
.map(|live| live.started)
.unwrap_or_else(std::time::SystemTime::now)
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs(),
})
.map_err(|error| RpcError::internal(format!("could not save native session: {error}")))
}
async fn load_session(self: &Arc<Self>, params: &Value) -> Result<Value, RpcError> {
let id = params
.get("sessionId")
.and_then(Value::as_str)
.ok_or_else(|| RpcError::invalid("missing sessionId"))?;
let existing = lock(&self.sessions).get(id).cloned();
if let Some(existing) = &existing {
let mut live = existing
.live
.try_lock()
.map_err(|_| RpcError::invalid("cannot reload during a Macro prompt"))?;
if existing.prompt_pending.load(Ordering::SeqCst) {
return Err(RpcError::invalid("cannot reload during a Macro prompt"));
}
*live = None;
lock(&self.sessions).remove(id);
}
let record = self.store.load(id).map_err(|error| {
RpcError::internal(format!("could not restore native session: {error}"))
})?;
if record.kind != self.options.kind
|| params.get("cwd").and_then(Value::as_str).map(Path::new)
!= Some(record.cwd.as_path())
{
return Err(RpcError::invalid(
"saved session belongs to a different agent or workspace",
));
}
let mut live = Live {
session: id.to_owned(),
cwd: record.cwd.clone(),
started: std::time::UNIX_EPOCH + Duration::from_secs(record.started),
name: agent_name(id),
log: self.options.kind.log(),
path: record.transcript,
cursor: Cursor::default(),
pending: VecDeque::new(),
seen_alive: false,
closed_reported: false,
};
if live.path.is_none() {
live.path = self.locate(&live, record.native_id.as_deref());
}
let session = Arc::new(Session {
id: id.to_owned(),
cwd: record.cwd,
mcp_servers: params
.get("mcpServers")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default(),
model: Mutex::new(record.model.clone()),
effort: Mutex::new(None),
native_id: Mutex::new(record.native_id),
prompt_pending: AtomicBool::new(false),
live: tokio::sync::Mutex::new(None),
cancel: Mutex::new(None),
always_allowed: Mutex::new(std::collections::HashSet::new()),
});
// ACP load stages this complete history until our successful response.
loop {
let offset = live.cursor.offset;
self.forward(&session, &mut live, &mut None)?;
if offset == live.cursor.offset && live.pending.is_empty() {
break;
}
}
self.sync_model(&session, &live).await;
*session.live.lock().await = Some(live);
lock(&self.sessions).insert(id.to_owned(), session.clone());
self.observe(&session);
Ok(json!({"configOptions": self.session_options(&session)}))
}
fn observe(self: &Arc<Self>, session: &Arc<Session>) {
let adapter = Arc::downgrade(self);
let session = Arc::downgrade(session);
let shutdown = self.shutdown.clone();
tokio::spawn(async move {
let mut ticks = 0u32;
// A turn started in the TUI: only its transcript or a settled
// native status can end it.
let mut open = false;
let mut settled = 0u32;
let mut last_output = Instant::now();
loop {
tokio::select! {
() = shutdown.cancelled() => break,
() = tokio::time::sleep(POLL) => {}
}
let (Some(adapter), Some(session)) = (adapter.upgrade(), session.upgrade()) else {
break;
};
if session.prompt_pending.load(Ordering::SeqCst) {
continue;
}
// A Macro prompt owns the reader until its response is sent.
let Ok(mut guard) = session.live.try_lock() else {
continue;
};
let Some(live) = guard.as_mut() else {
continue;
};
ticks = ticks.wrapping_add(1);
match adapter.forward(&session, live, &mut None) {
Ok((moved, ended)) => {
if moved {
last_output = Instant::now();
settled = 0;
}
open = ended.is_none() && (open || moved);
}
Err(error) => {
tracing::warn!(session = %session.id, error = %error.message, "native transcript observation stopped");
adapter.turn_complete(&session.id, "failed");
break;
}
}
if ticks.is_multiple_of(STATUS_EVERY) {
adapter.sync_model(&session, live).await;
// Interrupted turns, killed CLIs, and CLI events nothing
// answers write no turn end; herdr still sees the TUI idle.
if open {
settled = if adapter.native_idle(live).await {
settled + 1
} else {
0
};
if settled >= SETTLED_CHECKS && last_output.elapsed() >= SETTLED_QUIET {
tracing::info!(session = %session.id, "native turn settled without a transcript ending");
adapter.turn_complete(&session.id, "end_turn");
open = false;
settled = 0;
}
}
}
if ticks.is_multiple_of(CLOSED_CHECK_EVERY)
&& let Some(herdr) = &adapter.herdr
{
adapter.report_if_closed(herdr, &session, live).await;
}
}
});
}
/// Tell the client, once per native agent, that the agent was closed in
/// herdr - its tab or pane ended by the person or the agent. Only herdr's
/// explicit `agent_not_found` for an agent this process saw running
/// counts: a socket error, timeout, or unreadable answer may be transient,
/// and an agent missing since startup was lost, not closed. The next
/// prompt still relaunches the session.
async fn report_if_closed(&self, herdr: &HerdrCli, session: &Session, live: &mut Live) {
if live.closed_reported {
return;
}
let error =
match tokio::time::timeout(CLOSED_CHECK_TIMEOUT, herdr.agent_info(&live.name)).await {
Ok(Ok(_)) => {
live.seen_alive = true;
return;
}
Ok(Err(error)) => error,
Err(_) => return,
};
if !live.seen_alive || !error.missing_agent() {
return;
}
live.closed_reported = true;
tracing::info!(session = %session.id, "native agent was closed in herdr");
self.send(
json!({"jsonrpc":"2.0", "method":"_session/closed", "params":{"sessionId":session.id}}),
);
}
/// Whether herdr reports the session's native agent done with its turn.
async fn native_idle(&self, live: &Live) -> bool {
let Some(herdr) = &self.herdr else {
return false;
};
herdr
.agent_info(&live.name)
.await
.is_ok_and(|info| matches!(info.status.as_str(), "idle" | "done"))
}
fn turn_complete(&self, session: &str, stop: &str) {
let outcome = match stop {
"cancelled" => json!({"kind":"cancelled"}),
"failed" => {
json!({"kind":"failed", "message":"native transcript could not be read; reload the session"})
}
_ => json!({"kind":"finished"}),
};
self.send(json!({"jsonrpc":"2.0", "method":"_session/turn_complete", "params":{"sessionId":session, "outcome":outcome}}));
}
async fn prompt(
self: &Arc<Self>,
session: &Arc<Session>,
text: &str,
) -> Result<&'static str, RpcError> {
let herdr = self.herdr.as_ref().ok_or_else(|| {
RpcError::internal("macrod herdr-acp needs a macrod started inside herdr")
})?;
let cancel = CancellationToken::new();
*lock(&session.cancel) = Some(cancel.clone());
let _cancellation = PromptCancellation(&session.cancel);
let mut guard = session.live.lock().await;
if let Some(live) = guard.as_mut() {
// Queued like input typed into the TUI mid-turn: the prompt waits
// for the native turn, which streams and asks for permission
// meanwhile, and a stop interrupts that turn.
let wait = tracing::info_span!(
"macrod.herdr.prompt_wait",
session_id = %session.id,
native_turns = 0u32,
exit_dismissed = false,
outcome = tracing::field::Empty,
);
let waited = async {
let mut native_turns = 0u32;
loop {
if cancel.is_cancelled() {
return Ok(None);
}
let info = herdr.agent_info(&live.name).await;
if !info
.as_ref()
.is_ok_and(|info| matches!(info.status.as_str(), "working" | "blocked"))
{
return Ok(Some(info));
}
if info.as_ref().is_ok_and(|info| info.status == "blocked")
&& self.stay(herdr, &live.name).await?
{
tracing::Span::current().record("exit_dismissed", true);
continue;
}
native_turns += 1;
tracing::Span::current().record("native_turns", native_turns);
// An interrupted native turn ends "cancelled" too; only a
// Stop from Macro drops the waiting prompt, which then
// answers as not delivered.
self.follow(herdr, session, live, &cancel, true).await?;
if cancel.is_cancelled() {
return Ok(None);
}
}
}
.instrument(wait.clone())
.await
.inspect_err(|error: &RpcError| {
wait.record("outcome", "failed");
tracing::warn!(parent: &wait, error = %error.message, "queued prompt failed while waiting");
})?;
let Some(info) = waited else {
wait.record("outcome", "not_delivered");
return Err(RpcError::not_delivered());
};
wait.record("outcome", "ready");
match info {
Ok(info) => {
if info.cwd.as_ref().is_some_and(|cwd| cwd != &session.cwd)
|| info
.session_id
.as_ref()
.zip(lock(&session.native_id).as_ref())
.is_some_and(|(actual, expected)| actual != expected)
{
return Err(RpcError::invalid(
"Herdr agent identity no longer matches this session",
));
}
}
Err(error) if error.missing_agent() => {
let old = guard.take().expect("live session was checked above");
let mut restarted = self.launch(herdr, session, text).await?;
restarted.path = old.path;
restarted.cursor = old.cursor;
restarted.log = old.log;
restarted.pending = old.pending;
*guard = Some(restarted);
self.save(session, guard.as_ref())?;
}
Err(error) => return Err(error.into()),
}
}
if guard.is_none() {
*guard = Some(self.launch(herdr, session, text).await?);
self.save(session, guard.as_ref())?;
}
let Some(live) = guard.as_mut() else {
return Err(RpcError::internal("the Claude Code window did not start"));
};
// Relay whatever the native session did before this prompt, so a
// turn end already in the transcript never ends this prompt's turn.
loop {
let offset = live.cursor.offset;
self.forward(session, live, &mut None)?;
if offset == live.cursor.offset && live.pending.is_empty() {
break;
}
}
if cancel.is_cancelled() {
return Err(RpcError::not_delivered());
}
// The observer cannot acquire this session until the turn ends. Publish
// native settings now, while the freshly started composer is visible.
self.sync_model(session, live).await;
if self.options.kind == TuiAgent::Codex
&& let Some(requested) = effort::command(text)
{
let requested = requested?;
let message = tokio::select! {
() = cancel.cancelled() => return Ok("cancelled"),
result = tokio::time::timeout(Duration::from_secs(20), self.codex_effort(session, live, requested)) => {
result.map_err(|_| RpcError::internal("effort change was not confirmed; check the native session in Herdr"))??
}
};
self.notify_update(
&session.id,
json!({
"sessionUpdate":"agent_message_chunk", "content":{"type":"text","text":message},
}),
);
return Ok("end_turn");
}
herdr.prompt_agent(&live.name, text).await?;
if let Some(command) = commands::native_control(self.options.kind, text) {
// Herdr acknowledges PTY delivery, not the resulting setting. These
// commands need not write a transcript entry or start a model turn.
self.notify_update(&session.id, json!({
"sessionUpdate": "agent_message_chunk",
"content": {"type": "text", "text": format!(
"Sent `{command}` to {} in Herdr. Check its response and complete any confirmation there.",
self.options.kind.herdr_kind(),
)},
}));
return Ok("end_turn");
}
let outcome = self.follow(herdr, session, live, &cancel, false).await;
*lock(&session.cancel) = None;
self.save(session, guard.as_ref())?;
outcome
}
/// Dismiss the exit confirmation a second Ctrl-C in Herdr leaves behind,
/// so the prompt waiting on it can run. Returns whether it pressed Esc.
async fn stay(&self, herdr: &HerdrCli, name: &str) -> Result<bool, RpcError> {
let before = herdr.agent_info(name).await?;
let screen = herdr.read_agent(name).await?;
if !super::controls::exit_confirmation(self.options.kind, &screen) {
return Ok(false);
}
let after = herdr.agent_info(name).await?;
let current = herdr.read_agent(name).await?;
if !super::controls::same_dialog(
&screen,
¤t,
before.state_change_seq,
after.state_change_seq,
&after.status,
) {
return Ok(false);
}
herdr.send_keys(name, &["esc"]).await?;
tracing::info!(
agent = name,
"dismissed the native exit confirmation for a queued prompt"
);
tokio::time::sleep(POLL).await;
Ok(true)
}
/// Open the session's herdr window and start the agent in it.
async fn launch(
&self,
herdr: &HerdrCli,
session: &Session,
first_prompt: &str,
) -> Result<Live, RpcError> {
let kind = self.options.kind;
let label = title_from(first_prompt).unwrap_or_else(|| kind.herdr_kind().to_owned());
let source = if self.options.managed_worktrees {
Some(
crate::outbound::git::primary_worktree(&session.cwd)
.await
.map_err(|error| RpcError::internal(error.to_string()))?,
)
} else {
None
};
let model = lock(&session.model).clone();
let mut args = Vec::new();
let resume = lock(&session.native_id).clone();
if let Some(id) = &resume {
args.extend([
if kind == TuiAgent::Claude {
"--resume"
} else {
"resume"
}
.to_owned(),
id.clone(),
]);
}
if model != DEFAULT_MODEL && resume.is_none() {
args.extend(["--model".to_owned(), model.clone()]);
}
if kind == TuiAgent::Claude {
if resume.is_none() {
args.extend(["--session-id".to_owned(), session.id.clone()]);
}
if let Some(mode) = &self.options.permission_mode {
args.extend(["--permission-mode".to_owned(), mode.clone()]);
}
if let Some(config) = self.write_mcp_config(session)? {
args.extend([
"--mcp-config".to_owned(),
config.to_string_lossy().into_owned(),
]);
}
}
let mut environment = None;
if kind == TuiAgent::Codex && !session.mcp_servers.is_empty() {
let prepared = super::mcp::codex(
&self.store.0.join("mcp").join(&session.id),
&session.mcp_servers,
)
.map_err(|error| RpcError::internal(error.to_string()))?;
args.extend(prepared.args);
environment = Some(prepared.environment);
}
args.extend(self.options.agent_args.iter().cloned());
let name = agent_name(&session.id);
let started = std::time::SystemTime::now();
let window = herdr
.launch_agent(&AgentLaunch {
name: &name,
kind: kind.herdr_kind(),
reports_status: kind.reports_status(),
cwd: &session.cwd,
label: &label,
focus: !self.options.no_focus,
worktree_source: source.as_deref(),
environment: environment.as_deref(),
args: &args,
})
.await?;
tracing::info!(
session = %session.id,
pane = %window.pane_id,
agent = kind.herdr_kind(),
"agent started in herdr"
);
if kind == TuiAgent::Claude {
*lock(&session.native_id) = Some(session.id.clone());
}
Ok(Live {
session: session.id.clone(),
cwd: session.cwd.clone(),
started,
name,
log: self.options.kind.log(),
path: None,
cursor: Cursor::default(),
pending: VecDeque::new(),
seen_alive: true,
closed_reported: false,
})
}
/// Hand Claude Code the MCP servers Macro gave the session, in a file
/// only this user can read: the entries carry session credentials.
fn write_mcp_config(&self, session: &Session) -> Result<Option<PathBuf>, RpcError> {
let servers = claude_mcp_servers(&session.mcp_servers);
if servers.is_empty() {
return Ok(None);
}
let dir = self.store.0.join("mcp");
std::fs::create_dir_all(&dir).map_err(|error| RpcError::internal(error.to_string()))?;
let path = dir.join(format!("{}.mcp.json", session.id));
let body = json!({"mcpServers": servers}).to_string();
write_private(&path, body.as_bytes())
.map_err(|error| RpcError::internal(error.to_string()))?;
Ok(Some(path))
}
/// Stream the turn from the transcript until it ends. `running` says
/// the native turn is known to have started, so it may end without
/// ever reporting `working` (a dialog dismissed in Herdr).
async fn follow(
self: &Arc<Self>,
herdr: &HerdrCli,
session: &Arc<Session>,
live: &mut Live,
cancel: &CancellationToken,
running: bool,
) -> Result<&'static str, RpcError> {
let started = Instant::now();
let mut ticks = 0u32;
let mut settled = 0u32;
let mut missing = 0u32;
let mut active = running;
let mut open_tool: Option<OpenTool> = None;
// Bumped whenever a dialog is asked about or goes away, so a late
// answer from Macro never presses keys into a different dialog.
let generation = Arc::new(AtomicU64::new(0));
let mut asking = false;
let mut last_output = Instant::now();
let mut asked_seq = None;
let mut interrupt_failed = false;
let _epoch = PermissionEpoch(generation.clone());
loop {
tokio::select! {
() = cancel.cancelled(), if !interrupt_failed => {
if interrupt(herdr, &live.name).await? {
self.forward(session, live, &mut open_tool)?;
return Ok("cancelled");
}
// Answering `cancelled` now would end the turn in Macro
// while the agent keeps working; follow it to its end.
tracing::warn!(session = %session.id, "the native turn kept running after Esc");
interrupt_failed = true;
}
() = tokio::time::sleep(POLL) => {}
}
let (moved, ended) = self.forward(session, live, &mut open_tool)?;
if moved {
last_output = Instant::now();
}
if let Some(stop) = ended {
return Ok(stop);
}
ticks += 1;
if !ticks.is_multiple_of(STATUS_EVERY) {
continue;
}
// A startup screen may have hidden the footer before submission.
// Retry without waiting for a model response to release the observer.
let needs_settings = lock(&session.effort).is_none();
if needs_settings {
self.sync_model(session, live).await;
}
let info = match herdr.agent_info(&live.name).await {
Ok(info) => {
missing = 0;
if info.session_id.is_some() {
*lock(&session.native_id) = info.session_id.clone();
}
if live.path.is_none() {
live.path = self.locate(live, info.session_id.as_deref());
}
self.save(session, Some(live))?;
info
}
Err(error) => {
missing += 1;
if missing >= MISSING_AGENT_CHECKS {
return Err(RpcError::internal(format!(
"the agent's herdr window is gone: {error}"
)));
}
continue;
}
};
let status = info.status;
if asked_seq.is_some_and(|seq| seq != info.state_change_seq) {
asking = false;
generation.fetch_add(1, Ordering::SeqCst);
}
if status != "blocked" && std::mem::take(&mut asking) {
generation.fetch_add(1, Ordering::SeqCst);
}
match status.as_str() {
"working" => {
active = true;
settled = 0;
}
"blocked" => {
settled = 0;
if !std::mem::replace(&mut asking, true) {
asked_seq = Some(info.state_change_seq);
let current = generation.fetch_add(1, Ordering::SeqCst) + 1;
self.ask_permission(session, live, open_tool.clone(), current, &generation);
}
}
"idle" | "done" => {
settled += 1;
if active && settled >= SETTLED_CHECKS && last_output.elapsed() >= SETTLED_QUIET
{
self.forward(session, live, &mut open_tool)?;
return Ok("end_turn");
}
if !active && started.elapsed() > QUIET_START {
return Err(RpcError::internal(
"the native TUI did not confirm prompt submission; check its input in Herdr",
));
}
}
_ => {}
}
}
}
/// Relay new transcript lines. Returns whether anything moved and the
/// stop reason if the turn ended.
fn forward(
&self,
session: &Session,
live: &mut Live,
open_tool: &mut Option<OpenTool>,
) -> Result<(bool, Option<&'static str>), RpcError> {
let mut moved = false;
let mut ended = None;
if live.pending.is_empty() {
live.pending = self.drain(live)?.into();
}
while let Some(event) = live.pending.pop_front() {
match event {
LogEvent::ModelChanged(model) => {
self.report_model(session, live, &model)?;
}
LogEvent::Update(update) => {
moved = true;
// Codex logs a command only once it has run, so its log
// never names the call a permission dialog is about.
if self.options.kind == TuiAgent::Claude {
track_open_tool(open_tool, &update);
}
self.notify_update(&session.id, update);
}
LogEvent::TurnEnded(stop) => {
self.turn_complete(&session.id, stop);
ended = Some(stop);
break;
}
// A waiting Macro prompt owns the next turn: the item joins
// it, and only the prompt's own turn end may answer it.
LogEvent::LateUpdate(update) => {
moved = true;
self.notify_update(&session.id, update);
if !session.prompt_pending.load(Ordering::SeqCst) {
self.turn_complete(&session.id, "end_turn");
}
}
}
}
Ok((moved, ended))
}
/// Where the agent writes the session's transcript, once it exists.
/// Claude Code names it after the id this adapter gave it; Codex mints
/// its own id, which herdr reports once the session is live.
fn locate(&self, live: &Live, agent_session: Option<&str>) -> Option<PathBuf> {
let home = self.home.as_deref()?;
let path = match self.options.kind {
TuiAgent::Claude => find_claude_transcript(&home.join(".claude"), &live.session),
TuiAgent::Codex => {
let sessions = home.join(".codex").join("sessions");
let claimed = lock(&self.claimed);
agent_session
.and_then(|id| find_codex_rollout(&sessions, id))
.or_else(|| newest_codex_rollout(&sessions, &live.cwd, live.started, &claimed))
}
}?;
lock(&self.claimed).insert(path.clone());
Some(path)
}
/// Read whole new lines from the session's transcript.
fn drain(&self, live: &mut Live) -> Result<Vec<LogEvent>, RpcError> {
if live.path.is_none() {
live.path = self.locate(live, None);
}
let Some(path) = &live.path else {
return Ok(Vec::new());
};
let lines = live.cursor.read(path).map_err(|error| {
RpcError::internal(format!("could not read native transcript: {error}"))
})?;
Ok(lines
.into_iter()
.flat_map(|line| live.log.entry(&line))
.collect())
}
}
/// A herdr agent name for the session: `[a-z][a-z0-9_-]{0,31}`.
/// Press Esc until herdr reports the agent `idle` or `done`, and say whether
/// it is. One press is not proof: in Claude Code's vim editor mode the first
/// Esc only leaves insert mode. No press follows a stop, since Esc at an idle
/// Claude Code prompt opens its rewind menu.
#[tracing::instrument(
name = "macrod.herdr.interrupt",
skip(herdr),
fields(herdr.agent = name, presses, stopped),
err
)]
async fn interrupt(herdr: &HerdrCli, name: &str) -> Result<bool, HerdrError> {
let span = tracing::Span::current();
for press in 1..=INTERRUPT_PRESSES {
span.record("presses", press);
herdr.send_keys(name, &["esc"]).await?;
for _ in 0..INTERRUPT_CHECKS {
tokio::time::sleep(POLL).await;
let status = herdr.agent_info(name).await?.status;
if matches!(status.as_str(), "idle" | "done") {
span.record("stopped", true);
return Ok(true);
}
}
}
span.record("stopped", false);
Ok(false)
}
pub(crate) fn agent_name(session: &str) -> String {
let short: String = session
.chars()
.filter(char::is_ascii_alphanumeric)
.take(12)
.collect::<String>()
.to_ascii_lowercase();
format!("macro-{short}")
}
fn config_options(kind: TuiAgent, current: &str) -> Value {
let mut options = kind
.models()
.iter()
.map(|(value, name)| json!({"value": value, "name": name}))
.collect::<Vec<_>>();
if !kind.models().iter().any(|(value, _)| *value == current) {
options.push(json!({"value": current, "name": current}));
}
json!([{
"id": MODEL_CONFIG_ID,
"name": "Model",
"category": "model",
"type": "select",
"currentValue": current,
"options": options,
}])
}
pub(crate) fn prompt_text(prompt: &Value) -> String {
prompt
.as_array()
.into_iter()
.flatten()
.filter_map(|block| match block.get("type").and_then(Value::as_str)? {
"text" => block.get("text").and_then(Value::as_str).map(str::to_owned),
"resource_link" => block
.get("uri")
.and_then(Value::as_str)
.map(|uri| format!("@{}", uri.strip_prefix("file://").unwrap_or(uri))),
_ => None,
})
.collect::<Vec<_>>()
.join("\n")
}
/// ACP `mcpServers` entries in Claude Code's `--mcp-config` shape.
pub(crate) fn claude_mcp_servers(servers: &[Value]) -> serde_json::Map<String, Value> {
let pairs = |list: Option<&Value>| -> serde_json::Map<String, Value> {
list.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(|pair| {
Some((
pair.get("name")?.as_str()?.to_owned(),
pair.get("value")?.clone(),
))
})
.collect()
};
servers
.iter()
.filter_map(|server| {
let name = server.get("name")?.as_str()?.to_owned();
let config = match server.get("type").and_then(Value::as_str) {
Some(kind @ ("http" | "sse")) => json!({
"type": kind,
"url": server.get("url")?,
"headers": pairs(server.get("headers")),
}),
_ => json!({
"command": server.get("command")?,
"args": server.get("args").cloned().unwrap_or_else(|| json!([])),
"env": pairs(server.get("env")),
}),
};
Some((name, config))
})
.collect()
}
fn codex_rollouts(sessions: &Path) -> Vec<PathBuf> {
let mut found = Vec::new();
let mut stack = vec![sessions.to_owned()];
while let Some(dir) = stack.pop() {
let Ok(entries) = std::fs::read_dir(&dir) else {
continue;
};
for path in entries.filter_map(Result::ok).map(|entry| entry.path()) {
if path.is_dir() {
stack.push(path);
} else if path
.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.starts_with("rollout-") && name.ends_with(".jsonl"))
{
found.push(path);
}
}
}
found
}
/// The newest unclaimed rollout Codex started in `cwd` since `since`, for
/// when herdr cannot name the Codex session.
fn newest_codex_rollout(
sessions: &Path,
cwd: &Path,
since: std::time::SystemTime,
claimed: &std::collections::HashSet<PathBuf>,
) -> Option<PathBuf> {
let since = since
.checked_sub(Duration::from_secs(2))
.unwrap_or(std::time::UNIX_EPOCH);
codex_rollouts(sessions)
.into_iter()
.filter(|path| !claimed.contains(path))
.filter_map(|path| {
let modified = std::fs::metadata(&path)
.and_then(|meta| meta.modified())
.ok()?;
(modified >= since).then_some((modified, path))
})
.filter(|(_, path)| rollout_cwd(path).is_some_and(|dir| dir == cwd))
.max_by_key(|(modified, _)| *modified)
.map(|(_, path)| path)
}
/// The working directory in a rollout's leading `session_meta` record.
fn rollout_cwd(path: &Path) -> Option<PathBuf> {
use std::io::BufRead as _;
let mut first = String::new();
std::io::BufReader::new(std::fs::File::open(path).ok()?)
.read_line(&mut first)
.ok()?;
let meta: Value = serde_json::from_str(&first).ok()?;
(meta.get("type")?.as_str()? == "session_meta")
.then(|| meta.pointer("/payload/cwd")?.as_str().map(PathBuf::from))
.flatten()
}
/// `rollout-<time>-<session>.jsonl` under Codex's dated session folders.
fn find_codex_rollout(sessions: &Path, session: &str) -> Option<PathBuf> {
if session.is_empty() {
return None;
}
let suffix = format!("-{session}.jsonl");
codex_rollouts(sessions).into_iter().find(|path| {
path.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.ends_with(&suffix))
})
}
fn find_claude_transcript(claude_home: &Path, session: &str) -> Option<PathBuf> {
if session.is_empty() {
return None;
}
let file = format!("{session}.jsonl");
std::fs::read_dir(claude_home.join("projects"))
.ok()?
.filter_map(Result::ok)
.map(|project| project.path().join(&file))
.find(|path| path.is_file())
}
#[cfg(test)]
mod test;