Typed operations, engines, workspace, query & MCP (#689)

CHANGES

@@ -45,6 +45,88 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Experimental operations and engines (#690)
+
+Operations describe tmux commands as data. Each renders its argv against a tmux
+version (dropping flags an older tmux cannot accept), adapts raw output into a
+typed result, and serializes to and from plain dicts -- all without a running
+tmux server. The set spans the read seam (``list-*``, ``has-session``,
+``display-message``, ``show-options``, ``show-buffer``) and the
+mutating/creating surface for panes, windows, the server, options, environment,
+hooks, and paste buffers. A registry-generated catalog on the {ref}`experimental`
+page always matches the code.
+
+Engines run those operations behind one protocol, so the same operation returns
+the same typed result whether it goes through a subprocess (the classic path
+that reproduces today's libtmux behavior), an in-memory simulator for tests and
+dry runs, a persistent ``tmux -C`` control connection, an async transport, or
+tmux's native binary peer protocol. Results never raise on construction;
+raising is opt-in via ``raise_for_status()``, and how a failed result is handled
+is each engine's policy.
+
+A {class}`~libtmux.experimental.ops.plan.LazyPlan` records operations and yields
+forward references so a later operation can target an object that does not exist
+yet, resolved against captured ids at execution time. How a plan becomes tmux
+dispatches is a pluggable {class}`~libtmux.experimental.ops.planner.Planner`
+(sequential, ``;``-folding, or ``{marked}``-folding), so dispatch strategies can
+be A/B tested against the same plan with identical results.
+
+#### Declarative workspace builds fold to a few tmux calls (#690)
+
+A {class}`~libtmux.experimental.workspace.ir.Workspace` declares a session as a
+tree of windows and panes and lowers to a Core
+{class}`~libtmux.experimental.ops.plan.LazyPlan`, so a tmuxp-style spec can be
+analyzed, inspected, and built over any engine.
+{meth}`~libtmux.experimental.workspace.ir.Workspace.build` and its async twin
+{meth}`~libtmux.experimental.workspace.ir.Workspace.abuild` fold the build's
+dispatches by default: a multi-pane window collapses from one tmux call per
+operation into a handful of ``;``-chained and ``{marked}`` dispatches, so a
+session renders in a few round-trips instead of dozens.
+
+The resulting {class}`~libtmux.experimental.ops.plan.PlanResult` is identical to
+an unfolded build -- only the dispatch count changes -- because host-side steps
+(per-command sleeps, the ``wait_pane`` anti-race, ``before_script``) stay hard
+fold boundaries that a fold never crosses. Pass a
+{class}`~libtmux.experimental.ops.planner.SequentialPlanner` to ``build`` for one
+legible tmux call per operation when debugging.
+
+#### Floating panes on tmux 3.7 (#690)
+
+On tmux 3.7, the operations create floating panes -- overlays with an absolute
+size, position, and optional zoom. A ``new-pane`` operation, ``new_pane()`` on
+the pane wrappers, and a curated MCP tool each open one, and a
+{class}`~libtmux.experimental.workspace.ir.Workspace` can declare floating panes
+on a window, including a pane that overlays a different window.
+
+#### Query and command live panes with `panes()` (#690)
+
+{func}`~libtmux.experimental.query.panes` is a lazy, chainable query over the
+panes a running server has: ``filter``, ``order_by``, ``limit``, and ``map``
+compose and read nothing until a terminal call. The same query commands what it
+selects -- ``commands()`` attaches per-pane actions (send keys, resize, select,
+respawn, clear history, kill) that run as one folded tmux dispatch. A query
+resolves against a live engine or a plain list of pane snapshots, so the same
+code runs offline in tests.
+
+#### Drive tmux from an MCP server (#690)
+
+An optional Model Context Protocol server exposes tmux as tools an AI agent can
+call, installed with the ``libtmux[mcp]`` extra and launched as
+``libtmux-engine-mcp``. It offers a curated vocabulary of intuitive verbs
+(``send_input``, ``wait_for_output``, ``split_pane``, ``capture_pane``,
+``new_pane``, and the session, window, and pane lifecycle), a tool for every
+individual operation, and plan tools that preview or build a whole workspace in
+one call.
+
+The server is caller-aware: because a control-mode agent shares the server with
+the panes it drives, it knows which pane launched it and refuses to kill or
+respawn its own pane, window, or session. A safety level (``LIBTMUX_SAFETY``)
+keeps mutating and destructive tools hidden until an operator opts in, and a
+needle-free ``wait_for_output`` reports when a pane goes quiet after a command --
+no sentinel string -- and whether its process exited.
+
 ## libtmux 0.61.0 (2026-07-04)
 
 libtmux 0.61.0 hardens support for the tmux 3.7 patch line. It fixes

docs/_ext/tmuxop.py

@@ -0,0 +1,120 @@
+"""Sphinx directive that renders the experimental operation catalog.
+
+``.. tmuxop-catalog::`` (or the MyST fenced form) walks
+:func:`libtmux.experimental.ops.catalog` and emits a table of operations with
+their scope, safety tier, result type, minimum tmux version, and summary. The
+operation registry is the single source of truth, so the rendered reference
+cannot drift from the code.
+
+Options
+-------
+``:scope:`` / ``:safety:``
+    Filter to one scope (``pane``/``window``/``session``/``server``/``client``)
+    or safety tier (``readonly``/``mutating``/``destructive``).
+``:primitive-only:``
+    Show only operations that wrap a single tmux command.
+
+This is the in-repo renderer; a full gp-sphinx ``tmuxop`` domain (cross-reference
+roles + an operations index) can later replace it under the same directive name.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+
+if t.TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sphinx.application import Sphinx
+
+logger = logging.getLogger(__name__)
+
+_HEADERS = ("Operation", "Command", "Scope", "Safety", "Result", "Min tmux", "Summary")
+
+
+def _row(cells: Sequence[str]) -> nodes.row:
+    """Build a docutils table row from string cells."""
+    row = nodes.row()
+    for cell in cells:
+        entry = nodes.entry()
+        entry += nodes.paragraph(text=cell)
+        row += entry
+    return row
+
+
+def _table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> nodes.table:
+    """Build a simple docutils table."""
+    table = nodes.table()
+    tgroup = nodes.tgroup(cols=len(headers))
+    table += tgroup
+    for _ in headers:
+        tgroup += nodes.colspec(colwidth=1)
+    thead = nodes.thead()
+    thead += _row(headers)
+    tgroup += thead
+    tbody = nodes.tbody()
+    for row in rows:
+        tbody += _row(row)
+    tgroup += tbody
+    return table
+
+
+class TmuxopCatalogDirective(SphinxDirective):
+    """Render the operation catalog as a table."""
+
+    has_content = False
+    option_spec: t.ClassVar[dict[str, t.Any]] = {
+        "scope": directives.unchanged,
+        "safety": directives.unchanged,
+        "primitive-only": directives.flag,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        """Build the catalog table from the operation registry."""
+        from libtmux.experimental.ops import catalog
+
+        entries = catalog()
+        scope = self.options.get("scope")
+        safety = self.options.get("safety")
+        if scope:
+            entries = [entry for entry in entries if entry.scope == scope]
+        if safety:
+            entries = [entry for entry in entries if entry.safety == safety]
+        if "primitive-only" in self.options:
+            entries = [entry for entry in entries if entry.primitive]
+
+        if not entries:
+            logger.warning(
+                "tmuxop-catalog: no operations matched the given filters",
+                location=self.get_location(),
+            )
+            return []
+
+        rows = [
+            (
+                entry.kind,
+                entry.command,
+                entry.scope,
+                entry.safety,
+                entry.result_type,
+                entry.min_version or "-",
+                entry.summary,
+            )
+            for entry in entries
+        ]
+        return [_table(_HEADERS, rows)]
+
+
+def setup(app: Sphinx) -> dict[str, t.Any]:
+    """Register the directive."""
+    app.add_directive("tmuxop-catalog", TmuxopCatalogDirective)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/conf.py

@@ -15,6 +15,7 @@
 project_src = project_root / "src"
 
 sys.path.insert(0, str(project_src))
+sys.path.insert(0, str(cwd / "_ext"))
 
 # package data
 about: dict[str, str] = {}
@@ -34,6 +35,7 @@
         "sphinx_autodoc_api_style",
         "sphinx_autodoc_pytest_fixtures",
         "sphinx.ext.todo",
+        "tmuxop",
     ],
     intersphinx_mapping={
         "python": ("https://docs.python.org/", None),