Struct AcpController 

pub struct AcpController {
    tab_id: String,
    block_id: String,
    inner: Arc<Mutex<AcpInner>>,
    broker: Option<Arc<Broker>>,
    event_bus: Option<Arc<EventBus>>,
    mstore: Option<Arc<Store>>,
    filestore: Option<Arc<FileStore>>,
    health_monitor: Arc<TurnActivityTracker>,
    next_rpc_id: Arc<AtomicU64>,
    outstanding_prompt_ids: Arc<Mutex<HashSet<u64>>>,
    start_lock: Mutex<()>,
}

AcpController manages an ACP-speaking agent process.

Fields

tab_id: String

block_id: String

inner: Arc<Mutex<AcpInner>>

broker: Option<Arc<Broker>>

event_bus: Option<Arc<EventBus>>

mstore: Option<Arc<Store>>

filestore: Option<Arc<FileStore>>

health_monitor: Arc<TurnActivityTracker>

next_rpc_id: Arc<AtomicU64>

Monotonically increasing JSON-RPC request ID.

outstanding_prompt_ids: Arc<Mutex<HashSet<u64>>>

Every session/prompt request id that has been SENT but not yet RESOLVED (by either a real stopReason completion or a JSON-RPC error rejection). The turn is genuinely over only once this set is empty — see resolve_prompt_and_check_idle’s doc comment for why tracking the full set (not just “the latest” id) is necessary: steering can leave multiple prompts outstanding at once, and responses/rejections can arrive in any order relative to each other and relative to new sends (independent stdin-writer and stdout-reader tasks, no ordering guarantee between them). codex P2 on PR #2338 (twenty-seventh through thirtieth re-reviews).

start_lock: Mutex<()>

Serializes ensure_started, so two deliveries that find the agent stopped can’t both start it.

Implementations

impl AcpController

pub fn new( tab_id: String, block_id: String, broker: Option<Arc<Broker>>, event_bus: Option<Arc<EventBus>>, mstore: Option<Arc<Store>>, filestore: Option<Arc<FileStore>>, ) -> Self

fn next_id(&self) -> u64

fn set_status(inner: &mut AcpInner, status: &str)

fn get_status_snapshot(&self) -> BlockControllerRuntimeStatus

fn publish_status(&self)

pub(crate) fn is_running(&self) -> bool

fn make_request(&self, method: &str, params: Value) -> String

Build a JSON-RPC 2.0 request.

fn make_notification(&self, method: &str, params: Value) -> String

Build a JSON-RPC 2.0 notification (no id field).

fn spawn_process( &self, cli_command: String, cli_args: Vec<String>, working_dir: String, env_vars: HashMap<String, String>, ) -> Result<(), String>

Spawn the ACP agent process and perform the initialize handshake.

impl AcpController

fn begin_process(&self) -> u64

A new process takes over the controller: the generation moves on, and the prompts the previous process never answered are forgotten. Its waiter, which sees the new generation, no longer clears them; left there they would keep the turn active for good.

pub fn ensure_started( &self, block_meta: HashMap<String, Value>, ) -> Result<(), String>

Start the agent again if its process has exited, from the pane’s meta; a no-op when it is running. One start at a time: a second delivery waits here and then finds it running.

pub fn send_message( &self, message: String, message_id: Option<&str>, ) -> Result<(), String>

A user message from agentinput / agent.send (run_agent_turn): sent as session/prompt, then acknowledged the way the other controllers acknowledge theirs, so the pane stops showing it as pending.

fn spawn_env( &self, block_meta: &HashMap<String, Value>, ) -> HashMap<String, String>

The env this block’s ACP process is spawned with: cmd:env (either shape), with the block’s row UID + token carried onto it — identity M4b-2. Buys no attribution today (ACP agents are not given agentmux-mcp) but keeps the counters true.

Trait Implementations

impl Controller for AcpController

fn start( &self, block_meta: HashMap<String, Value>, _rt_opts: Option<Value>, _force: bool, ) -> Result<(), String>

Start the controller. May spawn background tasks. force restarts even if already running.

fn stop(&self, _graceful: bool, _new_status: &str) -> Result<(), String>

Stop the controller. graceful waits for process to exit; new_status is the target state.

fn get_runtime_status(&self) -> BlockControllerRuntimeStatus

Get the current runtime status.

fn send_input( &self, input: BlockInputUnion, _seq: Option<u64>, ) -> Result<(), String>

Send input (terminal data, signal, or resize) to the controller. seq is the per-TermViewModel monotonic counter; None means fire-and-forget (no ordering).

fn turn_tracker(&self) -> Option<Arc<TurnActivityTracker>>

This controller’s turn tracker, for the turn ledger’s bookkeeping from outside the controller (a held message’s join hint). None for controllers that track no turns.

fn controller_type(&self) -> &str

Get the controller type (e.g., “shell”, “cmd”).

fn block_id(&self) -> &str

Get the block ID.

fn as_any(&self) -> &dyn Any

Downcast support for concrete controller types.

fn stop_for_replace(&self, new_status: &str) -> Result<(), String>

Stop this controller because it’s being REPLACED by a new one for the same block (session restart / resync’s needs_replace path), NOT because the block itself is being closed. Must terminate this controller’s own CLI process so it doesn’t linger, but — unlike stop() — must NOT reach any declared-background descendant the process may have spawned (e.g. a task dev instance launched via run_in_background: true); those must survive the replace. See docs/specs/SPEC_BACKGROUND_TASK_TEARDOWN_SURVIVAL_2026_08_20.md.

fn shutdown( &self, _deadline: Instant, ) -> Pin<Box<dyn Future<Output = StopOutcome> + Send>>

Stop gracefully because the block is being CLOSED: end any turn in progress, ask the process to exit, force-kill at deadline. The returned future resolves once the process has actually exited (or there was none). Does NOT drop the block’s process tracker — the caller does that after this resolves, so nothing the agent started outlives it. See docs/specs/SPEC_AGENT_PANE_CLOSE_GRACEFUL_SHUTDOWN_2026_09_18.md §9.3.

fn agent_id(&self) -> Option<String>

This block’s own live, spawn-time-captured jekt/muxbus identity, if it has one — an independent source of truth for the recipient- identity check in ReactiveHandler::inject_message_inner, deliberately NOT derived from ReactiveHandler’s own name_to_blocks/agent_info maps (checking a registry against itself would be a tautology and catch nothing). Default None for controller types that aren’t jekt-addressable at all (e.g. plain terminals) — only ShellController and PersistentSubprocessController currently override this, mirroring the two paths that already resolve a jekt-registration identity at spawn time (resolve_agent_id_for_jekt, muxbus_agent_id_from_env).

fn turn_provenance(&self) -> Option<TurnProvenance>

What started this agent’s current turn (SPEC_AGENT_SELF_QUIT §6.3), if the controller tracks it. None = unknown, which never counts as the user — the safe answer for controllers that can’t tell (ACP, App Server, subprocess: both origins reach them through one method).

fn set_agent_id(&self, _id: Option<String>)

Refresh this block’s own captured jekt/muxbus identity (see agent_id’s doc comment). Called whenever ReactiveHandler::register_agent/register_agent_with_nonce (re-)registers THIS block’s block_id under a (possibly different) agent_id, so the two independently-written copies never drift apart (#2697: agent_id() was captured once at spawn and never refreshed, while the registry’s name bindings get re-keyed on every register_agent call — e.g. handle_reactive_register’s frontend-initiated HTTP path — causing a legitimately renamed or reconfigured agent’s own messages to be falsely rejected as an identity mismatch). Default no-op for controller types that don’t override agent_id either.

fn stable_agent_id(&self) -> Option<String>

This block’s STABLE jekt identity — AGENTMUX_AGENT_ID as captured once at spawn, never refreshed. Distinct from agent_id, which tracks the LIVE, renameable display name and is deliberately refreshed every turn (see that method’s doc comment on #2697). AGENTMUX_AGENT_ID is embedded verbatim in PR-body tags specifically because it does NOT change if the agent is later renamed — but ReactiveHandler’s registry only tracks one key per block, and every turn’s agent_id() refresh evicts whatever this block was previously registered under. ReactiveHandler::inject_message_inner’s recipient-identity check (#2695) uses this alongside agent_id() so a jekt addressed to the stable ID is validated correctly even after the primary registry key has moved on to the live display name. See INCIDENT_2026_09_09_JEKT_STABLE_ID_ALIAS.md. Default None, mirroring agent_id’s default — only PersistentSubprocessController currently overrides this.

fn stable_agent_uid(&self) -> Option<String>

Identity M2: this block’s UID (db_agents.id) as carried in its spawn env (AGENTMUX_AGENT_UID, set by build_persistent_spawn_env since M1a), captured once at spawn like [stable_agent_id]. Backs the registry’s UID confirmer: consulted only for targets that resolved by UID, and None — a registered-but-not-yet-spawned controller, or a block with no row — is “unverifiable”, not a mismatch. Default None; only PersistentSubprocessController overrides this.