Trait Actions 

pub trait Actions: Send + Sync {
    // Required methods
    fn terminate_session(&self, pid: u32) -> Result<(), String>;
    fn inject_text(&self, session_id: &str, text: &str) -> Result<(), String>;
    fn set_gate_mode(&self, mode: BrainGateMode) -> Result<(), String>;
    fn log_observation(
        &self,
        observation: ObservationInput,
    ) -> Result<(), String>;
    fn log_decision(&self, input: LogDecisionInput) -> Result<(), String>;
    fn mark_canonical(
        &self,
        decision_id: &str,
        note: Option<String>,
    ) -> Result<(), String>;
    fn bind_bus_role(
        &self,
        name: &str,
        cwd: &str,
        pid: u32,
    ) -> Result<(), String>;
    fn cancel_task(&self, task_id: &str) -> Result<(), String>;
    fn set_supervisor_drain(&self, draining: bool) -> Result<(), String>;
    fn retry_task(&self, task_id: &str) -> Result<(), String>;
    fn approve_task(&self, task_id: &str) -> Result<(), String>;
    fn send_session_to_peer(
        &self,
        session_id: &str,
        transcript: Option<&Path>,
        cwd: &str,
        peer: &str,
    ) -> Result<String, String>;
}

Side-effecting paths the TUI invokes when the user takes an action (terminating a session, sending a prompt, flipping the brain mode, recording an observation, marking a decision canonical for teaching).

Each method is fallible — implementations return a Result rather than silently swallowing errors so the TUI can surface failures in the status bar instead of pretending an action succeeded.

Not modeled here (intentionally):

• launch::* — launching a new Claude Code session is wider than a single call (cwd selection, model defaults, plugin propagation). Will get its own trait once the TUI’s launcher surface is refactored alongside #275.
• mailbox::deliver_pending — orchestrator-style mailbox delivery; should eventually move to an Orchestrator trait, not Actions.
• log_decision (vs. log_observation) — currently only called from the plugin gate path, not the TUI. Stays a direct call until a TUI site needs it.

Required Methods

fn terminate_session(&self, pid: u32) -> Result<(), String>

Terminate the OS process with the given PID. The TUI uses this for “kill session” hotkeys.

fn inject_text(&self, session_id: &str, text: &str) -> Result<(), String>

Inject text into the session’s terminal. Implementations pick the right backend (tmux, Kitty, etc.) from the session metadata.

The text is sent verbatim — the caller is responsible for any trailing newline they want. Sanitization (e.g. neutralizing a leading /) belongs to the caller; this trait is a transport.

fn set_gate_mode(&self, mode: BrainGateMode) -> Result<(), String>

Update the persisted brain gate mode. Reflected back through BrainView::gate_mode on the next call.

fn log_observation(&self, observation: ObservationInput) -> Result<(), String>

Record an observation about a user action — non-LLM “the user did X.” Drives the brain’s outcome telemetry and preference distillation.

fn log_decision(&self, input: LogDecisionInput) -> Result<(), String>

Record a user’s accept/reject decision on a brain suggestion. The distinction from log_observation is that log_decision carries the actual suggestion that was on screen — the brain pairs it with the user’s response for outcome telemetry, counterfactual analysis, and few-shot retrieval.

fn mark_canonical( &self, decision_id: &str, note: Option<String>, ) -> Result<(), String>

Mark a past brain decision as canonical for teaching. Optional note is the operator’s annotation. Used by the Brain Review surface.

fn bind_bus_role(&self, name: &str, cwd: &str, pid: u32) -> Result<(), String>

Bind an agent-bus role to a (cwd, pid) pair. The TUI calls this from the new role-bind key (Ctrl+R) so the operator can attach a role to a specific running Claude session without dropping to another terminal. Returns Err when the bus feature is compiled out or the DB write fails. See issue #307.

fn cancel_task(&self, task_id: &str) -> Result<(), String>

Cancel a supervisor task (move it to CANCELLED). Used by the Supervisor panel’s one-key cancel (#368). Err when the coord feature is compiled out, the task is already terminal, or the store write fails.

fn set_supervisor_drain(&self, draining: bool) -> Result<(), String>

Set or clear the supervisor drain marker. When draining, the reconciler stops issuing new task assignments while letting running tasks finish. Err when the coord feature is compiled out.

fn retry_task(&self, task_id: &str) -> Result<(), String>

Re-queue a failed/cancelled task (move it back to PENDING so the reconciler re-assigns it). Err for a DONE task (nothing to retry), a still-active task, or when the coord feature is compiled out.

fn approve_task(&self, task_id: &str) -> Result<(), String>

Approve a NEEDS_HUMAN task — accept the work as-is and move it to DONE, overriding the verifier that escalated it. Err when the task isn’t in NEEDS_HUMAN, or the coord feature is compiled out.

fn send_session_to_peer( &self, session_id: &str, transcript: Option<&Path>, cwd: &str, peer: &str, ) -> Result<String, String>

Move a conversation to a paired peer, so it can be resumed there (#510). The TUI calls this from the send hotkey; transcript is the path session discovery already resolved, which is more reliable than re-deriving it from cwd and the id.

Returns the session id the transcript actually travels under, which is not always session_id: discovery can hand back a transcript belonging to a different id, and the bytes decide.

Everything checkable without the network — transcript readable, peer paired, an address to dial — is checked before returning Ok. The megabytes themselves go in a detached child, because a median transcript is 5.45 MB and the caller is a render loop. So Ok means “accepted and started”, not “delivered”; the ledger behind claudectl relay sessions is where delivery shows up.

Err when the relay feature is compiled out.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Actions for MockRuntime