Skip to main content

Actions

claudectl_core::runtime

Trait Actions 

Source 
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>;
}
Expand description

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§

Source

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

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§