libtmux_mcp.tools.wait_for_tools.wait_for_channel

API reference · Markdown

libtmux_mcp.tools.wait_for_tools.wait_for_channel ( channel : str , timeout : float = 30.0 , socket_name : str | None = None ) → str

functionasync [source] ¶

functionasync [source] ¶

libtmux_mcp.tools.wait_for_tools.wait_for_channel

Block until a tmux wait-for channel is signalled.

This is the AUTHORED-output synchronisation primitive: the channel only fires because your own composed shell command signals it. Reserve wait_for_text for output you did not author.

Agents can compose this with send_keys to turn shell-side milestones into explicit synchronisation points::

send_keys( "pytest; tmux wait-for -S tests_done", pane_id=..., ) wait_for_channel("tests_done", timeout=60)

Shell ; semantics fire wait-for -S whether the command succeeded or failed, so the edge-triggered signal never deadlocks on a crash. Do NOT chain exit $status after the signal — in an interactive shell that exits the shell itself, which destroys single-pane sessions. Exit-status preservation in interactive shells is out-of-scope; inspect the captured output for command-specific success markers.

Parameters

• channel ( str ) – Channel name. Must match ^[A-Za-z0-9_.:-]{1,128}$.

• timeout ( float ) – Maximum seconds to wait. The underlying tmux wait-for has no built-in timeout — this wrapper enforces it by killing the tmux child, which also happens if the call is cancelled. Defaults to 30 seconds. Capped by the same server wait ceiling as wait_for_text; an over-large value is not an error, the wait returns at the ceiling and the confirmation message names the timeout that was actually enforced.

• socket_name ( str | None ) – tmux socket name.

Returns

str Confirmation message naming the channel and the timeout actually enforced.

Raises

• ExpectedToolError – On timeout, invalid channel name, tmux error, or when the tmux server disappeared during the wait — tmux wait-for exits 0 for a clean server shutdown exactly as it does for a real signal, so that case is detected by re-probing the server and reported rather than passed off as success.