Typed tmux operation chains

[tony]

Summary

• Replace the raw run_command_chain and narrow build_forward_layout tools with one typed run_tmux_operations tool.
• Add discriminated Pydantic operation models for split_pane, send_keys, resize_pane, select_layout, set_option, and capture_pane, plus structured per-step and per-dispatch results.
• Compile ordered typed operations to the fewest safe native tmux dispatches: no-output mutations fold into tmux a ; b ; c, output/id capture steps stay attributable, and on_error="continue" uses standalone dispatches because native tmux chains abort on first failure.
• Preserve the single-split decoration fast path: an id-producing split_pane can fold with immediate send_keys / resize_pane operations that target its pane_ref through tmux's {marked} target while still returning the concrete pane id.
• Pin the libtmux dependency to a public commit instead of a sibling worktree path.

Changes by area

src/libtmux_mcp/tools/chain_tools.py

Adds the typed compiler and registers run_tmux_operations as a mutating, open-world tool. The compiler keeps a pending chain of no-output operations, flushes before output reads, captures split ids when needed, and returns both rendered argv and per-step status.

src/libtmux_mcp/models.py

Adds the typed operation union and structured result models. The operation list is validated through a module-level Pydantic TypeAdapter in the tool module.

Docs

Adds chain-tool docs and wires chain_tools plus the new models into the FastMCP docs catalog.

Dependency pin

Updates [tool.uv.sources] and uv.lock to use the public libtmux branch commit 591a312f78d165816bb95a035a46219657c4b53d.

Design notes

• The tool is typed, not raw tmux argv. Unsupported commands such as kill-server are not operation variants.
• Per-step stdout is only promised where it can be attributed. capture_pane and id-producing split steps force a dispatch boundary unless the single split-ref {marked} optimization applies.
• on_error="continue" deliberately disables native chaining. tmux ; sequences have abort-on-first-error semantics, so continuing later operations requires separate dispatches.
• The true one-connection, per-command-result path remains a future control-mode runner; this PR stays on the subprocess chain API.

Test plan

• rm -rf docs/_build
• uv run ruff check . --fix --show-fixes
• uv run ruff format .
• uv run mypy .
• uv run py.test --reruns 0 -vvv (612 passed)
• just build-docs

Companion PR

Depends on the libtmux experimental chain API in tmux-python/libtmux#685.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 80.45977% with 68 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.31%. Comparing base (188784b) to head (5ad5e56).

Files with missing lines	Patch %	Lines
src/libtmux_mcp/tools/chain_tools.py	76.98%	35 Missing and 20 partials ⚠️
src/libtmux_mcp/models.py	87.96%	11 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #81      +/-   ##
==========================================
- Coverage   84.67%   84.31%   -0.36%     
==========================================
  Files          43       44       +1     
  Lines        3197     3545     +348     
  Branches      438      484      +46     
==========================================
+ Hits         2707     2989     +282     
- Misses        360      405      +45     
- Partials      130      151      +21     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 4 issues:

1. ResizePaneOperation(zoom=False) toggles zoom instead of leaving it unchanged: _resize_pane_calls appends -Z whenever zoom is not None, but False is not None, and tmux resize-pane -Z only toggles (there is no zoom-off), so zoom=False flips zoom — the opposite of its apparent meaning. The model validator accepts zoom=False.

libtmux-mcp/src/libtmux_mcp/tools/chain_tools.py

Lines 200 to 205 in 55ea0b4

	"""Build ``resize-pane`` calls for a typed resize operation."""
	args: list[str | int] = []
	if operation.zoom is not None:
	args.append("-Z")
	if operation.height is not None:
	args.extend(("-y", operation.height))

2. SetOptionOperation validates target-without-scope but not scope-without-target, so scope="pane"/"window"/"session" with target=None passes validation and emits e.g. set-option -p <opt> <val> with no -t, silently mutating the control client's current pane/session.

libtmux-mcp/src/libtmux_mcp/models.py

Lines 796 to 803 in 55ea0b4

	@model_validator(mode="after")
	def _validate_target(self) -> SetOptionOperation:
	if self.target is not None and self.scope is None:
	msg = "scope is required when target is specified."
	raise ValueError(msg)
	return self

3. ControlModeRunner (the default transport="control") is closed only on the normal-exit path, not in a try/finally. An exception in the dispatch loop (e.g. asyncio.CancelledError, or anything re-raised by handle_tool_errors_async) skips close() and leaks the tmux -C subprocess (it has no __del__); these accumulate over the server's lifetime.

libtmux-mcp/src/libtmux_mcp/tools/chain_tools.py

Lines 1088 to 1093 in 55ea0b4

	created_pane_order,
	)
	if isinstance(runner, ControlModeRunner):
	await asyncio.to_thread(runner.close)
	return RunTmuxOperationsResult(
	succeeded=succeeded,

4. CHANGES describes an intermediate branch state for a never-released tool (AGENTS.md says "Do not mention intermediate branch states, abandoned approaches, or 'no longer' behavior unless users of a published release actually experienced the old state"). run-tmux-operations is new in this PR, so "now dispatches ... by default" and "a failing operation no longer aborts the rest" describe a transition no released user experienced.

libtmux-mcp/CHANGES

Lines 23 to 30 in 55ea0b4

	**Per-operation results over tmux control mode**
	{tooliconl}`run-tmux-operations` now dispatches over a persistent `tmux -C`
	control connection by default (`transport="control"`), so each operation in a
	folded chain keeps its own stdout and return code, and a failing operation no
	longer aborts the rest. Pass `transport="subprocess"` to fold into a single
	native `tmux a ; b ; c` sequence that returns one merged result and aborts on
	the first error.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}