[RFC]: bundle rmux CLI as an app-owned terminal runtime dependency

[hiqiancheng]

Summary

Bundle rmux as an app-owned CLI dependency, provision it the same way TouchAI already provisions
tk, and expose it on PATH for built-in bash execution. This RFC intentionally limits scope to raw CLI availability and daemon lifecycle management. It does not add managed shell sessions, persistent bash semantics, or UI/task projection yet.

Motivation

TouchAI needs a low-risk first step toward background and persistent terminal workflows without immediately changing the built-in bash contract or adding new runtime/session abstractions.

This solves three concrete problems:

• gives the model access to a capable terminal multiplexer/runtime through normal bash execution
• keeps the first increment narrow enough to validate whether model-driven
  mux usage is actually effective before adding higher-level APIs
• avoids prematurely coupling TouchAI's product architecture to
  mux-specific session semantics

Why now:

• TouchAI already has a bundled binary provisioning path for
  tk
• background task execution is an open product need ([Feature]: support background task execution #56)
• current bash execution is one-shot only, so the smallest useful experiment is exposing a proven CLI runtime before designing managed persistent sessions

Affected boundaries

• AgentService
• conversation runtime
• tool execution
• session persistence
• context construction
• instruction loading
• agent orchestration
• MCP integration
• database schema or migrations

Proposed design

Phase 1 scope only:

1. Provision
   mux as a bundled binary using the same runtime extraction/verification pattern currently used for
   tk.
2. Start an app-owned
   mux daemon during TouchAI startup, or lazily on first use, under TouchAI-controlled process ownership.
3. Ensure the bundled binary directory is appended to the built-in bash execution PATH, so models can invoke
   mux directly through bash.
4. On TouchAI shutdown, explicitly terminate the owned
   mux daemon and clean up any daemon state that belongs to this app instance.
5. Do not change built-in bash semantics: bash remains one-shot and non-interactive. Any persistence comes only from
   mux as an external CLI the model chooses to use.
6. Do not add command-text interception, shell hooking, session ownership registries, context auto-summaries, or UI surfaces in this phase.

Boundary decisions:

mux is a host capability, not a first-class session abstraction yet.

• The model may use
  mux or ignore it.
• TouchAI does not promise automatic understanding of
  mux sessions created through raw bash in this phase.

mux must be app-owned rather than user-global: TouchAI is responsible for starting it and stopping it with the app.

Alternatives and trade-offs

Recommended: bundled raw CLI first

Pros:

• narrowest viable increment
• reuses existing bundled binary architecture
• validates real model usage before deeper runtime changes
• avoids speculative abstractions around persistent shell ownership and context injection

Cons:

• TouchAI cannot automatically understand or project
  mux session state yet
• no managed task/session UI in phase 1
• cleanup and lifecycle are only app-level, not session-level

Rejected: implement managed persistent shell/session APIs first

Rejected because it expands immediately into RFC-first areas such as tool execution semantics, session persistence, context construction, and task projection. That is too much uncertainty before proving that bundled
mux materially improves agent workflows.

Rejected: hook �ash command strings and auto-detect

mux

Rejected because it creates an implicit protocol from shell text, which is hard to reason about, hard to test, and diverges from how Codex, Claude Code, and OpenCode separate one-shot shell from background or persistent execution.

Rejected: use only Rust crate integration now

Rejected for phase 1 because the immediate goal is model-callable CLI capability. Rust-side SDK integration may be appropriate later for managed sessions, but it does not replace the need to bundle and expose the runtime binary.

Upstream references

• Codex separates one-shot shell from explicit long-lived exec transport (exec_command / write_stdin) rather than hooking shell text.
• Claude Code keeps bash one-shot and uses explicit background task mechanisms.
• OpenCode keeps one-shot shell, PTY terminal APIs, and background task APIs as separate layers.

mux documents a CLI + daemon model suitable for persistent terminal workflows.

Related issues:

• [Feature]: support background task execution #56 support background task execution
• [Feature]: support streaming tool call results #11 support streaming tool call results
• [Feature]: track session working directory as persistent state instead of per-call parameter #213 track session working directory as persistent state instead of per-call parameter

Testing and rollout

Validation for this RFC's implementation should cover:

• bundled
  mux extraction and checksum verification on supported platforms
• daemon startup success and idempotency across repeated app launches
• daemon shutdown on normal app exit
• stale daemon cleanup behavior after abnormal previous termination
• bash environment visibility:
  mux is callable from built-in bash without extra user setup
• negative-path behavior when bundled binary is unavailable or fails to start

Rollout should remain behind implementation scope only; no user-facing persistent-shell feature claims should be made until a later RFC defines managed session semantics, projection, and context behavior.