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

.agents/skills/benchmarking-engine-builds/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: benchmarking-engine-builds
+description: Use when measuring or profiling how fast libtmux.experimental engines build tmux workspaces — comparing classic vs subprocess/control_mode/imsg/mock/pipelined, chasing a build-latency regression, reading percentile grids, or finding where a control-mode build spends its time (cProfile). Runs scripts/bench_engines.py hermetically on throwaway sockets.
+---
+
+# Benchmarking engine builds
+
+## Overview
+
+`scripts/bench_engines.py` times how long each experimental engine takes to
+build a tmux session structure (`W` windows × `P` panes-per-window), sweeping
+shapes × engines × wait-modes and reporting min/avg/median/p90/p95/p99/max.
+
+**Hermetic and safe to run beside a live tmux session:** every server gets its
+own socket under a throwaway `mkdtemp` dir, `TMUX` is unset before libtmux is
+imported, and an `atexit` hook kills every spawned server. The default tmux
+server is never contacted.
+
+It is a PEP 723 script — **always launch it with `uv run`**, never `python`, or
+its inline deps (`rich`, `typer`, editable `libtmux`) won't resolve.
+
+## When to use
+
+- Comparing engine build cost (which engine is fastest for a given shape).
+- Checking whether a change to the ops/plan/engine layer moved build latency.
+- Reading percentile spread (is p99 blowing out?) rather than a single number.
+- Locating the hot path inside one engine's build (`profile` → cProfile cumtime).
+
+## Quick reference
+
+Run from the repo root.
+
+| Command | What it does |
+|---|---|
+| `uv run scripts/bench_engines.py run` | full engine grid (the clean signal) |
+| `uv run scripts/bench_engines.py matrix --shapes 1x4,3x3,5x4` | 4-axis factorial: which choice drives build cost |
+| `uv run scripts/bench_engines.py concurrency --transport control_mode --k 4` | K builds sync-serial vs async-`gather` |
+| `uv run scripts/bench_engines.py contract` | mock-parity ops-language check only (for CI) |
+| `uv run scripts/bench_engines.py profile --engine control_mode --shape 8x4` | cProfile one engine, print slowest by cumtime |
+| `uv run scripts/bench_engines.py cell control_mode 8x4` | one isolated build (for wrapping in hyperfine) |
+
+`run` flags: `--shapes 1x1,1x4,3x3,5x4,8x4`, `--engines classic,subprocess,control_mode,imsg,mock,pipelined`,
+`--wait` (ALSO measure with shell-readiness wait), `--runs 20`, `--warmup 3`,
+`--json-out grid.json`. Shape is `windows x panes-per-window`.
+
+`matrix` sweeps five expression layers (`imperative`, `plan-seq`, `plan-fold`,
+`ws-seq`, `ws-fold`) × transport {subprocess, control_mode} × mode {sync, async}
+against a `classic` reference. `mock` is the offline correctness **oracle**, not
+a results row: `matrix --check` (default on) and `contract` assert every layer ×
+mode renders identical tmux argv to it, so the benchmark doubles as an
+ops-language contract test.
+
+Engines: `classic` (Server/Session/Window/Pane API) · `subprocess` (one fork
+per op) · `control_mode` (one persistent `tmux -C`) · `imsg` (AF_UNIX one-shot) ·
+`mock` (offline, in-memory Python floor) · `pipelined` (prototype: batch
+independent creates via `run_batch`).
+
+## Reading the results
+
+- **`control_mode` is the fastest shipped engine** (~21× classic at 32 panes)
+  because it avoids a per-op `tmux` fork. `pipelined` edges it (~1.4×) by
+  batching independent creates into ~3 round-trips.
+- **Builds are tmux-server-bound, not round-trip-bound** — one shell fork per
+  pane dominates, so cutting round-trips helps less than the count implies.
+  `mock` (~1–2 ms) is the pure-Python floor: the plan/compile layer is
+  negligible; the time is tmux.
+- **`profile` shows ~68% in `select.epoll.poll`** inside `_read_blocks`: each
+  created id is read back before the next op targets it. Latency-bound.
+
+## Common mistakes
+
+- Running with `python` instead of `uv run` — PEP 723 deps don't resolve.
+- **Comparing `--wait` against no-wait across engines.** Shell startup
+  (~0.8–2.1 s) dwarfs a fast build, so the ~20× engine win collapses to ~1.5×
+  once both sides wait. A classic-that-waits vs a builder-that-doesn't is
+  apples-to-oranges (this is the bogus "~79×" trap). Compare like with like.
+- Trusting hyperfine whole-process wall time over the in-process grid — Python
+  startup + import dwarfs a 3 ms build and understates the builder. The
+  in-process `run` grid is the clean signal.
+- Expecting `mock` under `--wait`: it has no real panes and is skipped.
+
+## Results & reproduction
+
+Committed results live in `scripts/bench-results/`: `RESULTS.md` (narrative +
+tables), `grid.json` (no-wait grid), `wait.json` (wait comparison). Regenerate
+the raw JSON with `--json-out`.

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

CHANGES

@@ -45,6 +45,33 @@ $ 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.
 ### Documentation
 
 #### Cleaner `from_env` examples (#719)
@@ -57,6 +84,60 @@ environment-setup plumbing, so each example leads with the constructor call it
 demonstrates instead of the socket-path and `$TMUX` boilerplate needed to run
 it.
 
+#### 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.62.0 (2026-07-12)
 
 libtmux 0.62.0 teaches libtmux objects to locate themselves and to resolve

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),