@jstn-sdk/rcs 0.1.0

package/crates/rcs-mux/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "rcs-mux"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/crates/rcs-mux/src/lib.rs

@@ -0,0 +1,91 @@
+mod tmux;
+mod types;
+
+pub use tmux::{build_capture_pane_args, TmuxAdapter};
+pub use types::*;
+
+pub fn canonical_contract_summary() -> String {
+    format!(
+        "mux-operations={operations}\nmux-target-kinds={target_kinds}\nsubmit-policy={submit_policy}\nreadiness={readiness}\nconfirmation={confirmation}\nadapter=tmux",
+        operations = MUX_OPERATION_NAMES.join(", "),
+        target_kinds = MUX_TARGET_KINDS.join(", "),
+        submit_policy = SubmitPolicy::enter(2, 100),
+        readiness = PaneReadinessReason::Ok,
+        confirmation = DeliveryConfirmation::Confirmed,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn canonical_contract_names_remain_generic() {
+        assert_eq!(
+            MUX_OPERATION_NAMES,
+            &[
+                "resolve-target",
+                "send-input",
+                "capture-tail",
+                "inspect-liveness",
+                "attach",
+                "detach",
+            ]
+        );
+        assert_eq!(MUX_TARGET_KINDS, &["delivery-handle", "detached"]);
+    }
+
+    #[test]
+    fn input_envelope_normalizes_literal_text_for_typed_send() {
+        let envelope = InputEnvelope::new("hello\nbridge", SubmitPolicy::enter(2, 100));
+        assert_eq!(envelope.normalized_text(), "hello bridge");
+        assert_eq!(envelope.submit.presses(), 2);
+        assert_eq!(
+            format!("{}", envelope.submit),
+            "enter(presses=2, delay_ms=100)"
+        );
+    }
+
+    #[test]
+    fn confirmation_policy_defaults_match_notify_hook_expectations() {
+        let policy = ConfirmationPolicy::default();
+        assert_eq!(policy.narrow_capture_lines, 8);
+        assert_eq!(policy.wide_capture_lines, 80);
+        assert_eq!(policy.verify_delay_ms, 250);
+        assert_eq!(policy.verify_rounds, 3);
+        assert!(policy.allow_active_task_confirmation);
+        assert!(policy.require_ready_for_worker_targets);
+        assert_eq!(policy.non_empty_tail_lines, 24);
+        assert!(policy.retry_submit_without_retyping);
+    }
+
+    #[test]
+    fn serde_roundtrip_mux_operation() {
+        let op = MuxOperation::SendInput {
+            target: MuxTarget::DeliveryHandle("sess:0.1".into()),
+            envelope: InputEnvelope::new("test", SubmitPolicy::enter(1, 50)),
+        };
+        let json = serde_json::to_string(&op).expect("serialize");
+        let deserialized: MuxOperation = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(format!("{deserialized:?}"), format!("{op:?}"));
+    }
+
+    #[test]
+    fn serde_roundtrip_mux_outcome() {
+        let outcome = MuxOutcome::TailCaptured {
+            visible_lines: 80,
+            body: "hello".into(),
+        };
+        let json = serde_json::to_string(&outcome).expect("serialize");
+        let deserialized: MuxOutcome = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(deserialized, outcome);
+    }
+
+    #[test]
+    fn serde_roundtrip_mux_error() {
+        let err = MuxError::InvalidTarget("bad".into());
+        let json = serde_json::to_string(&err).expect("serialize");
+        let deserialized: MuxError = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(deserialized, err);
+    }
+}

package/crates/rcs-mux/src/tmux.rs

@@ -0,0 +1,282 @@
+use std::process::Command;
+use std::thread;
+use std::time::Duration;
+
+use crate::types::{MuxAdapter, MuxError, MuxOperation, MuxOutcome, MuxTarget, SubmitPolicy};
+
+/// Run a tmux command with the given arguments. Returns stdout on success.
+fn run_tmux(args: &[&str]) -> Result<String, MuxError> {
+    let output = Command::new("tmux")
+        .args(args)
+        .output()
+        .map_err(|e| MuxError::AdapterFailed(format!("failed to run tmux: {e}")))?;
+
+    if output.status.success() {
+        String::from_utf8(output.stdout)
+            .map_err(|e| MuxError::AdapterFailed(format!("invalid utf-8 from tmux: {e}")))
+    } else {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        Err(MuxError::AdapterFailed(format!(
+            "tmux {} failed: {}",
+            args.first().unwrap_or(&""),
+            stderr.trim()
+        )))
+    }
+}
+
+/// Extract a tmux target string from a `MuxTarget`.
+fn resolve_target_handle(target: &MuxTarget) -> Result<String, MuxError> {
+    match target {
+        MuxTarget::DeliveryHandle(handle) => {
+            if handle.is_empty() {
+                Err(MuxError::InvalidTarget("empty delivery handle".into()))
+            } else {
+                Ok(handle.clone())
+            }
+        }
+        MuxTarget::Detached => Err(MuxError::InvalidTarget(
+            "cannot operate on a detached target".into(),
+        )),
+    }
+}
+
+/// Extract the session name portion from a tmux target string (e.g. "mysess:0.1" -> "mysess").
+fn session_from_handle(handle: &str) -> &str {
+    handle.split(':').next().unwrap_or(handle)
+}
+
+/// Build the argument list for `tmux send-keys` with literal text.
+pub(crate) fn build_send_keys_args<'a>(target: &'a str, text: &'a str) -> Vec<&'a str> {
+    vec!["send-keys", "-t", target, "-l", text]
+}
+
+/// Build the argument list for `tmux send-keys` enter press.
+pub(crate) fn build_enter_key_args(target: &str) -> Vec<String> {
+    vec!["send-keys".into(), "-t".into(), target.into(), "C-m".into()]
+}
+
+/// Build the argument list for `tmux capture-pane`.
+pub fn build_capture_pane_args(target: &str, visible_lines: usize) -> Vec<String> {
+    vec![
+        "capture-pane".into(),
+        "-t".into(),
+        target.into(),
+        "-p".into(),
+        "-S".into(),
+        format!("-{visible_lines}"),
+    ]
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+pub struct TmuxAdapter;
+
+impl TmuxAdapter {
+    pub fn new() -> Self {
+        Self
+    }
+
+    pub fn status(&self) -> &'static str {
+        "tmux adapter ready"
+    }
+
+    fn do_resolve_target(&self, target: &MuxTarget) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+
+        // Verify the target exists by listing all panes
+        let pane_list = run_tmux(&[
+            "list-panes",
+            "-a",
+            "-F",
+            "#{session_name}:#{window_index}.#{pane_index}",
+        ])?;
+
+        let found = pane_list.lines().any(|line| line.trim() == handle);
+        if found {
+            Ok(MuxOutcome::TargetResolved {
+                resolved_handle: handle,
+            })
+        } else {
+            Err(MuxError::InvalidTarget(format!("pane not found: {handle}")))
+        }
+    }
+
+    fn do_send_input(
+        &self,
+        target: &MuxTarget,
+        envelope: &crate::types::InputEnvelope,
+    ) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+        let text = envelope.normalized_text();
+
+        // Send the literal text
+        let args = build_send_keys_args(&handle, &text);
+        run_tmux(&args)?;
+
+        // Send enter presses per submit policy
+        if let SubmitPolicy::Enter { presses, delay_ms } = &envelope.submit {
+            for i in 0..*presses {
+                if i > 0 && *delay_ms > 0 {
+                    thread::sleep(Duration::from_millis(*delay_ms));
+                }
+                let enter_args = build_enter_key_args(&handle);
+                let str_args: Vec<&str> = enter_args.iter().map(|s| s.as_str()).collect();
+                run_tmux(&str_args)?;
+            }
+        }
+
+        Ok(MuxOutcome::InputAccepted {
+            bytes_written: text.len(),
+        })
+    }
+
+    fn do_capture_tail(
+        &self,
+        target: &MuxTarget,
+        visible_lines: usize,
+    ) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+        let args = build_capture_pane_args(&handle, visible_lines);
+        let str_args: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
+        let body = run_tmux(&str_args)?;
+
+        Ok(MuxOutcome::TailCaptured {
+            visible_lines,
+            body,
+        })
+    }
+
+    fn do_inspect_liveness(&self, target: &MuxTarget) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+        let session = session_from_handle(&handle);
+
+        let output = Command::new("tmux")
+            .args(["has-session", "-t", session])
+            .output()
+            .map_err(|e| MuxError::AdapterFailed(format!("failed to run tmux: {e}")))?;
+
+        Ok(MuxOutcome::LivenessChecked {
+            alive: output.status.success(),
+        })
+    }
+
+    fn do_attach(&self, target: &MuxTarget) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+        run_tmux(&["attach-session", "-t", &handle])?;
+        Ok(MuxOutcome::Attached { handle })
+    }
+
+    fn do_detach(&self, target: &MuxTarget) -> Result<MuxOutcome, MuxError> {
+        let handle = resolve_target_handle(target)?;
+        run_tmux(&["detach-client", "-t", &handle])?;
+        Ok(MuxOutcome::Detached { handle })
+    }
+}
+
+impl MuxAdapter for TmuxAdapter {
+    fn adapter_name(&self) -> &'static str {
+        "tmux"
+    }
+
+    fn execute(&self, operation: &MuxOperation) -> Result<MuxOutcome, MuxError> {
+        match operation {
+            MuxOperation::ResolveTarget { target } => self.do_resolve_target(target),
+            MuxOperation::SendInput { target, envelope } => self.do_send_input(target, envelope),
+            MuxOperation::CaptureTail {
+                target,
+                visible_lines,
+            } => self.do_capture_tail(target, *visible_lines),
+            MuxOperation::InspectLiveness { target } => self.do_inspect_liveness(target),
+            MuxOperation::Attach { target } => self.do_attach(target),
+            MuxOperation::Detach { target } => self.do_detach(target),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::{InputEnvelope, SubmitPolicy};
+
+    #[test]
+    fn resolve_target_handle_rejects_empty() {
+        let err = resolve_target_handle(&MuxTarget::DeliveryHandle(String::new()))
+            .expect_err("should reject empty");
+        assert!(matches!(err, MuxError::InvalidTarget(_)));
+    }
+
+    #[test]
+    fn resolve_target_handle_rejects_detached() {
+        let err = resolve_target_handle(&MuxTarget::Detached).expect_err("should reject detached");
+        assert!(matches!(err, MuxError::InvalidTarget(_)));
+    }
+
+    #[test]
+    fn resolve_target_handle_accepts_valid() {
+        let handle = resolve_target_handle(&MuxTarget::DeliveryHandle("sess:0.1".into()))
+            .expect("should accept valid handle");
+        assert_eq!(handle, "sess:0.1");
+    }
+
+    #[test]
+    fn session_from_handle_extracts_session() {
+        assert_eq!(session_from_handle("mysess:0.1"), "mysess");
+        assert_eq!(session_from_handle("plain"), "plain");
+        assert_eq!(session_from_handle("a:b:c"), "a");
+    }
+
+    #[test]
+    fn build_send_keys_args_constructs_correct_args() {
+        let args = build_send_keys_args("sess:0.1", "hello world");
+        assert_eq!(
+            args,
+            vec!["send-keys", "-t", "sess:0.1", "-l", "hello world"]
+        );
+    }
+
+    #[test]
+    fn build_enter_key_args_constructs_correct_args() {
+        let args = build_enter_key_args("sess:0.1");
+        assert_eq!(args, vec!["send-keys", "-t", "sess:0.1", "C-m"]);
+    }
+
+    #[test]
+    fn build_capture_pane_args_constructs_correct_args() {
+        let args = build_capture_pane_args("sess:0.1", 80);
+        assert_eq!(
+            args,
+            vec!["capture-pane", "-t", "sess:0.1", "-p", "-S", "-80"]
+        );
+    }
+
+    #[test]
+    fn send_keys_uses_normalized_text() {
+        let envelope = InputEnvelope::new("line1\nline2", SubmitPolicy::None);
+        let text = envelope.normalized_text();
+        assert_eq!(text, "line1 line2");
+        let args = build_send_keys_args("t:0.0", &text);
+        assert_eq!(args[4], "line1 line2");
+    }
+
+    #[test]
+    fn adapter_name_is_tmux() {
+        let adapter = TmuxAdapter::new();
+        assert_eq!(adapter.adapter_name(), "tmux");
+    }
+
+    #[test]
+    fn status_reports_ready() {
+        let adapter = TmuxAdapter::new();
+        assert_eq!(adapter.status(), "tmux adapter ready");
+    }
+
+    #[test]
+    fn execute_rejects_detached_target() {
+        let adapter = TmuxAdapter::new();
+        let result = adapter.execute(&MuxOperation::ResolveTarget {
+            target: MuxTarget::Detached,
+        });
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert!(matches!(err, MuxError::InvalidTarget(_)));
+    }
+}

package/crates/rcs-mux/src/types.rs

@@ -0,0 +1,306 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+pub const MUX_OPERATION_NAMES: &[&str] = &[
+    "resolve-target",
+    "send-input",
+    "capture-tail",
+    "inspect-liveness",
+    "attach",
+    "detach",
+];
+pub const MUX_TARGET_KINDS: &[&str] = &["delivery-handle", "detached"];
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data")]
+pub enum MuxTarget {
+    DeliveryHandle(String),
+    Detached,
+}
+
+impl MuxTarget {
+    pub fn delivery_handle(handle: impl Into<String>) -> Self {
+        Self::DeliveryHandle(handle.into())
+    }
+}
+
+impl fmt::Display for MuxTarget {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::DeliveryHandle(handle) => write!(f, "delivery-handle({handle})"),
+            Self::Detached => write!(f, "detached"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data")]
+pub enum SubmitPolicy {
+    None,
+    Enter { presses: u8, delay_ms: u64 },
+}
+
+impl SubmitPolicy {
+    pub fn enter(presses: u8, delay_ms: u64) -> Self {
+        Self::Enter {
+            presses: presses.max(1),
+            delay_ms,
+        }
+    }
+
+    pub fn presses(&self) -> u8 {
+        match self {
+            Self::None => 0,
+            Self::Enter { presses, .. } => *presses,
+        }
+    }
+}
+
+impl fmt::Display for SubmitPolicy {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::None => write!(f, "none"),
+            Self::Enter { presses, delay_ms } => {
+                write!(f, "enter(presses={presses}, delay_ms={delay_ms})")
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InputEnvelope {
+    pub literal_text: String,
+    pub submit: SubmitPolicy,
+    pub replace_newlines_with_spaces: bool,
+}
+
+impl InputEnvelope {
+    pub fn new(literal_text: impl Into<String>, submit: SubmitPolicy) -> Self {
+        Self {
+            literal_text: literal_text.into(),
+            submit,
+            replace_newlines_with_spaces: true,
+        }
+    }
+
+    pub fn normalized_text(&self) -> String {
+        if self.replace_newlines_with_spaces {
+            self.literal_text
+                .chars()
+                .map(|ch| if ch == '\r' || ch == '\n' { ' ' } else { ch })
+                .collect()
+        } else {
+            self.literal_text.clone()
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InjectionPreflight {
+    pub skip_if_scrolling: bool,
+    pub require_running_agent: bool,
+    pub require_ready: bool,
+    pub require_idle: bool,
+    pub capture_lines: usize,
+}
+
+impl Default for InjectionPreflight {
+    fn default() -> Self {
+        Self {
+            skip_if_scrolling: true,
+            require_running_agent: true,
+            require_ready: true,
+            require_idle: true,
+            capture_lines: 80,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data")]
+pub enum PaneReadinessReason {
+    Ok,
+    MissingTarget,
+    ScrollActive,
+    PaneRunningShell,
+    PaneHasActiveTask,
+    PaneNotReady,
+    TargetResolutionFailed(String),
+}
+
+impl fmt::Display for PaneReadinessReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Ok => write!(f, "ok"),
+            Self::MissingTarget => write!(f, "missing_target"),
+            Self::ScrollActive => write!(f, "scroll_active"),
+            Self::PaneRunningShell => write!(f, "pane_running_shell"),
+            Self::PaneHasActiveTask => write!(f, "pane_has_active_task"),
+            Self::PaneNotReady => write!(f, "pane_not_ready"),
+            Self::TargetResolutionFailed(reason) => {
+                write!(f, "target_resolution_failed({reason})")
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PaneReadiness {
+    pub reason: PaneReadinessReason,
+    pub pane_target: Option<String>,
+    pub pane_current_command: Option<String>,
+    pub pane_capture: Option<String>,
+}
+
+impl PaneReadiness {
+    pub fn ok(pane_target: impl Into<String>) -> Self {
+        Self {
+            reason: PaneReadinessReason::Ok,
+            pane_target: Some(pane_target.into()),
+            pane_current_command: None,
+            pane_capture: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum DeliveryConfirmation {
+    Confirmed,
+    ConfirmedActiveTask,
+    Unconfirmed,
+}
+
+impl fmt::Display for DeliveryConfirmation {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Confirmed => write!(f, "Confirmed"),
+            Self::ConfirmedActiveTask => write!(f, "ConfirmedActiveTask"),
+            Self::Unconfirmed => write!(f, "Unconfirmed"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ConfirmationPolicy {
+    pub narrow_capture_lines: usize,
+    pub wide_capture_lines: usize,
+    pub verify_delay_ms: u64,
+    pub verify_rounds: u8,
+    pub allow_active_task_confirmation: bool,
+    pub require_ready_for_worker_targets: bool,
+    pub non_empty_tail_lines: usize,
+    pub retry_submit_without_retyping: bool,
+}
+
+impl Default for ConfirmationPolicy {
+    fn default() -> Self {
+        Self {
+            narrow_capture_lines: 8,
+            wide_capture_lines: 80,
+            verify_delay_ms: 250,
+            verify_rounds: 3,
+            allow_active_task_confirmation: true,
+            require_ready_for_worker_targets: true,
+            non_empty_tail_lines: 24,
+            retry_submit_without_retyping: true,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeliveryAttempt {
+    pub pane_target: String,
+    pub input: InputEnvelope,
+    pub typed_prompt: bool,
+    pub confirmation: DeliveryConfirmation,
+}
+
+impl DeliveryAttempt {
+    pub fn new(
+        pane_target: impl Into<String>,
+        input: InputEnvelope,
+        typed_prompt: bool,
+        confirmation: DeliveryConfirmation,
+    ) -> Self {
+        Self {
+            pane_target: pane_target.into(),
+            input,
+            typed_prompt,
+            confirmation,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum MuxOperation {
+    ResolveTarget {
+        target: MuxTarget,
+    },
+    SendInput {
+        target: MuxTarget,
+        envelope: InputEnvelope,
+    },
+    CaptureTail {
+        target: MuxTarget,
+        visible_lines: usize,
+    },
+    InspectLiveness {
+        target: MuxTarget,
+    },
+    Attach {
+        target: MuxTarget,
+    },
+    Detach {
+        target: MuxTarget,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum MuxOutcome {
+    TargetResolved { resolved_handle: String },
+    InputAccepted { bytes_written: usize },
+    TailCaptured { visible_lines: usize, body: String },
+    LivenessChecked { alive: bool },
+    Attached { handle: String },
+    Detached { handle: String },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "data")]
+pub enum MuxError {
+    Unsupported(String),
+    InvalidTarget(String),
+    AdapterFailed(String),
+}
+
+impl fmt::Display for MuxError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Unsupported(message) => write!(f, "unsupported: {message}"),
+            Self::InvalidTarget(message) => write!(f, "invalid target: {message}"),
+            Self::AdapterFailed(message) => write!(f, "adapter failed: {message}"),
+        }
+    }
+}
+
+impl std::error::Error for MuxError {}
+
+pub trait MuxAdapter {
+    fn adapter_name(&self) -> &'static str;
+
+    fn execute(&self, operation: &MuxOperation) -> Result<MuxOutcome, MuxError>;
+}
+
+pub fn describe_operation(operation: &MuxOperation) -> &'static str {
+    match operation {
+        MuxOperation::ResolveTarget { .. } => "resolve-target",
+        MuxOperation::SendInput { .. } => "send-input",
+        MuxOperation::CaptureTail { .. } => "capture-tail",
+        MuxOperation::InspectLiveness { .. } => "inspect-liveness",
+        MuxOperation::Attach { .. } => "attach",
+        MuxOperation::Detach { .. } => "detach",
+    }
+}

package/crates/rcs-runtime/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "rcs-runtime"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "rcs-runtime"
+path = "src/main.rs"
+
+[dependencies]
+rcs-mux = { path = "../rcs-mux" }
+rcs-runtime-core = { path = "../rcs-runtime-core" }
+serde_json = "1"
+