Repository navigation
Description
Summary
Expose an owned program workflow in libtmux-mcp: launch literal arguments in a fresh PTY, inspect bounded output and completion evidence, send input, and explicitly stop or clean up that program. Report the connected daemon's feature decisions so an agent can choose an available operation before creating resources.
Motivation
The existing run_command tool sends a shell command into a borrowed pane and waits for a cooperative completion signal. An agent starting a test runner or development server also needs a separately owned lifetime, a handle it can revisit, and cleanup that preserves the user's existing session.
The Python core already tracks the owner in libtmux#823, with an initial implementation in libtmux#833. This issue tracks its MCP consumer. The core's stock-dispatcher implementation must remain usable independently of experimental engine branches.
Evidence
The current run_command implementation builds a shell payload, sends it to an existing pane, and waits on a private channel. RunCommandResult records shell status and bounded capture. Neither provides an independently owned program handle. The dependency declaration accepts libtmux>=0.62.0,<1.0; the proposed core owner is still separate work.
These are source observations. An MCP managed-program implementation and its runtime acceptance cases have not been qualified.
Proposal
- Provide run-to-completion and start/read/input/wait/stop/cleanup workflows over the same core owner. Reuse core lifecycle and capability decisions; keep shell-context
run_commandavailable for its existing use case. - Accept literal argument arrays, working directory, environment and terminal geometry. Return a program handle bound to its daemon and pane lifetime, exact exit status or signal when observed, and explicit unknown outcomes when evidence is missing.
- Make reads bounded and immediately useful while the program runs. Identify rendered capture, raw bytes and truncation or lost history in the result. Define final-output draining and backpressure before advertising byte streaming.
- Keep tool calls responsive to cancellation and concurrent requests. Cancelling an observation and terminating a program need distinct documented effects; a cancelled worker thread alone does not settle an owned subprocess. Retain the original failure and any cleanup failures.
- Expose supported, unsupported or unverified feature decisions with reasons from the actual connected daemon. Reuse the capability work in Gate unsafe optional tmux features independently #138 and libtmux#778. Test client/daemon version mismatch, prereleases, unknown versions, reconnects and server replacement. Refuse unsupported operations before launching or sending input.
- Extend the existing toolset declarations, result models and discoverable tool descriptions. Document ownership, local-versus-remote daemon restrictions, controller shutdown, retained output and process-tree limits. A managed PTY provides lifecycle management; operating-system confinement requires a separate mechanism.
- Keep the first delivery installable against its declared core dependency. Record core availability as a dependency and avoid silently requiring an unmerged engine branch or an unreleased package version.
Acceptance needs a short program that exits with status 7 and an unterminated final line; an interactive program receiving literal input; an unrelated pane that survives cleanup; refusal after external respawn or daemon replacement; cancellation that leaves no owned wait subprocess; and a second MCP request that remains responsive during a wait. Test discovery and the actual advertised schemas through an MCP client, including read-only tool selections. Pair critical guards with deliberate breaks that make their tests fail. Keep raw streaming or crash-recovery criteria open if the initial PR does not deliver them.
References
- Add atomic run/wait/capture tool with exit status #73 delivered the borrowed-shell run/wait/capture tool; its closure does not deliver a fresh program owner.
- run_command: tmux completion wrapper breaks over SSH panes (error connecting to socket) #132 records the borrowed-shell completion wrapper's remote-shell restriction.
- Clarify that MCP Safety controls tool visibility, not OS-level confinement. #127 tracks how tool visibility and operating-system confinement are described.
Activity