feat(fastmcp): align tool surface, prompts, and middleware (#15)

Broad follow-up to the initial MCP surface, realigning the server
around FastMCP 3.2 primitives and closing gaps that blocked real
agent workflows. Adds four prompt recipes, a full middleware stack
(timing, error-handling, audit, safety, readonly-retry,
tail-preserving response limiting), a discovery tool, buffer and
read-only hook tools, and channel-based wait primitives — all with
Pydantic output models, NumPy-docstring-derived parameter
descriptions, bounded outputs with tail-preserving truncation, and
CI coverage across the supported tmux matrix.

**New tools**
- Discovery: `list_servers` — enumerates live tmux sockets with
  an honest scope (default dir + `LIBTMUX_SOCKET_PATH` +
  `extra_socket_paths`) rather than a filesystem crawl.
- Waits: `wait_for_text`, `wait_for_content_change`,
  `wait_for_channel`, `signal_channel`. All bounded,
  `Context.report_progress` / `Context.warning` aware, and
  propagate `asyncio.CancelledError` cleanly. `capture_pane` calls
  run through `asyncio.to_thread` so FastMCP's event loop stays
  responsive under long waits.
- Buffers: `load_buffer`, `paste_buffer`, `show_buffer`,
  `delete_buffer`. Agent-namespaced as
  `libtmux_mcp_<uuid>_<name>` to prevent collisions; leaked
  buffers are GC'd on graceful lifespan shutdown.
- Hooks (read-only): `show_hook`, `show_hooks` — the latter
  merges the `-g` global-window tree into `scope='server'`.

**Prompt recipes**
- Four FastMCP prompts: `run_and_wait`, `diagnose_failing_pane`,
  `build_dev_workspace`, `interrupt_gracefully`. `run_and_wait`
  UUID-scopes its wait-for channel and uses `repr()` for
  send-keys payloads. `build_dev_workspace` uses the real tool
  parameter names (`session_name=`, `pane_id=`, `direction=`),
  drops stray Enter presses, and no longer waits for shell
  prompts after launching screen-grabbing programs (`vim`,
  `watch`, `tail -f`); a new `log_command` parameter replaces
  the Linux-only `/var/log/syslog` default.
- Set `LIBTMUX_MCP_PROMPTS_AS_TOOLS=1` to expose prompts as
  tools for tools-only MCP clients.

**Middleware stack**
- `TimingMiddleware`, `ErrorHandlingMiddleware`.
- `AuditMiddleware`: per-call structured logging with
  digest-redacted argument summaries. Moved outside
  `SafetyMiddleware` so tier denials are audited too.
- `SafetyMiddleware`: tier-gated tool visibility
  (readonly / mutating / destructive).
- `ReadonlyRetryMiddleware`: transparent retry of readonly tools
  on transient `libtmux.exc.LibTmuxException`; mutating tools
  never retry. Retry warnings log under `libtmux_mcp.retry`.
- `TailPreservingResponseLimitingMiddleware`: trims oversized
  output from the head so the active prompt survives.

**Bounded outputs**
- `capture_pane`, `snapshot_pane`, `show_buffer` accept
  `max_lines` (default 500) with tail-preserving truncation and
  typed `content_truncated` / `content_truncated_lines` signals.
  Pass `max_lines=None` to opt out.

**Lifespan + safety**
- FastMCP lifespan with a `tmux` presence probe that fails fast
  with `RuntimeError` if the binary is missing on `PATH`.
- `search_panes` neutralizes tmux format-string injection in the
  regex fast path; also always takes the fast path when
  `regex=False`, and returns panes in numeric `pane_id` order.
- macOS `TMUX_TMPDIR` self-kill guard: resolves the server
  socket via `tmux display-message #{socket_path}` before
  env-based reconstruction, with a basename-match fallback that
  closes the launchd divergence gap.
- Caller-identity scoping: self-protection is scoped to the
  caller's tmux socket rather than global.

**Refactors**
- `tools/pane_tools.py` split into a `pane_tools/` subpackage
  (`io`, `meta`, `layout`, `lifecycle`, `copy_mode`, `pipe`,
  `search`, `wait`) with a thin `__init__` re-export.
- `handle_tool_errors_async` decorator for Context-using tools.
- `ANNOTATIONS_SHELL` open-world shell-tool annotations hoisted
  into `_utils` with the five consumers documented inline.

**Docs**
- New pages: `tools/buffers.md`, `tools/hooks.md`,
  `tools/waits.md`, `tools/index.md`; `panes.md` documents the
  `SearchPanesResult` migration; `safety.md` covers the macOS
  `TMUX_TMPDIR` caveat, the audit log, `pipe_pane`, and
  `set_environment`.
- New topic pages: `topics/completion.md`, `topics/logging.md`,
  `topics/pagination.md`.
- Reusable Sphinx widget framework under `docs/_ext/widgets/`
  powers a `{mcp-install}` picker with nested client /
  install-method tabs and per-client tool hints. Rendering goes
  through the Jinja `highlight` filter so copybutton parity
  matches the rest of the site; non-HTML Sphinx builders degrade
  gracefully.
- Prompts and Resources promoted to top-level peers of Tools,
  surfaced as landing-page grid cards with FastMCP autodoc
  wiring.

### Breaking changes

- `search_panes` now returns
  `libtmux_mcp.models.SearchPanesResult` instead of
  `list[PaneContentMatch]`. Matches moved to `.matches`; new
  `truncated`, `truncated_panes`, `total_panes_matched`,
  `offset`, `limit` fields enable pagination.
  Migration: `for m in search_panes(...)` →
  `for m in search_panes(...).matches`.
- Minimum `fastmcp>=3.2.4` (was `>=3.1.0`). Required for
  `ReadonlyRetryMiddleware` and per-parameter input-schema
  descriptions.

Author: tony

AGENTS.md

@@ -254,14 +254,31 @@ type
 
 ### Doctests
 
-**All functions and methods MUST have working doctests.** Doctests serve as both documentation and tests.
-
-**CRITICAL RULES:**
-- Doctests MUST actually execute - never comment out function calls or similar
-- Doctests MUST NOT be converted to `.. code-block::` as a workaround (code-blocks don't run)
-- If you cannot create a working doctest, **STOP and ask for help**
-
-**`# doctest: +SKIP` is NOT permitted** - it's just another workaround that doesn't test anything. Use the fixtures properly - tmux is required to run tests anyway.
+This repo is an **MCP server**, not a general-purpose library. Most tools
+require a live tmux server to do anything meaningful, so a blanket
+doctest mandate doesn't fit the shape of the code. Scope doctests to
+functions where they actually work offline.
+
+**Where doctests SHOULD be used:**
+- Pure helper functions (parsers, formatters, digest / redaction
+  logic, small utilities) that can run with no external state.
+- Examples in module-level docstrings that illustrate a concept without
+  hitting tmux, the filesystem, or the network.
+
+**Where doctests are exempt:**
+- Any tool function that calls `_get_server`, touches a `Session`,
+  `Window`, or `Pane`, or otherwise requires tmux to be running. Use a
+  unit test with fixtures instead.
+- Functions that do I/O, spawn subprocesses, or read environment.
+
+**CRITICAL RULES for doctests that exist:**
+- They MUST actually execute — never comment out function calls or
+  similar.
+- They MUST NOT be converted to `.. code-block::` as a workaround
+  (code-blocks don't run).
+- `# doctest: +SKIP` is discouraged. If a function can't run offline,
+  write a unit test instead of a skipped doctest — a skipped test is
+  just noise.
 
 **When output varies, use ellipsis:**
 ```python

CHANGES

@@ -6,6 +6,103 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+_FastMCP alignment: new tools, prompts, and middleware (#15)_
+
+### Breaking changes
+
+- {tooliconl}`search-panes` now returns
+  {class}`~libtmux_mcp.models.SearchPanesResult` instead of
+  `list[`{class}`~libtmux_mcp.models.PaneContentMatch``]`. Matches
+  moved to `.matches`; new `truncated`, `truncated_panes`,
+  `total_panes_matched`, `offset`, `limit` fields enable pagination.
+  Migrate `for m in search_panes(...)` →
+  `for m in search_panes(...).matches`.
+- Minimum `fastmcp>=3.2.4` (was `>=3.1.0`). Required for
+  {class}`~libtmux_mcp.middleware.ReadonlyRetryMiddleware` and
+  per-parameter input-schema descriptions.
+
+### What's new
+
+**New tools**
+
+- Discovery: {tooliconl}`list-servers`.
+- Waits: {tooliconl}`wait-for-text`,
+  {tooliconl}`wait-for-content-change`, {tooliconl}`wait-for-channel`,
+  {tooliconl}`signal-channel`. All bounded, emit
+  `ctx.report_progress` / `ctx.warning`, and propagate
+  {exc}`asyncio.CancelledError` cleanly.
+- Buffers: {tooliconl}`load-buffer`, {tooliconl}`paste-buffer`,
+  {tooliconl}`show-buffer`, {tooliconl}`delete-buffer`.
+  Agent-namespaced as `libtmux_mcp_<uuid>_<name>` to prevent
+  collisions; leaked buffers GC'd on graceful shutdown.
+- Hooks (read-only): {tooliconl}`show-hook`, {tooliconl}`show-hooks`.
+- Panes / windows: {tooliconl}`snapshot-pane`, {tooliconl}`pipe-pane`,
+  {tooliconl}`display-message`, {tooliconl}`paste-text`,
+  {tooliconl}`select-pane`, {tooliconl}`swap-pane`,
+  {tooliconl}`select-window`, {tooliconl}`move-window`,
+  {tooliconl}`enter-copy-mode`, {tooliconl}`exit-copy-mode`.
+
+**Prompt recipes**
+
+- Four prompts: `run_and_wait`, `diagnose_failing_pane`,
+  `build_dev_workspace`, `interrupt_gracefully`. Set
+  `LIBTMUX_MCP_PROMPTS_AS_TOOLS=1` to expose them as tools for
+  tools-only MCP clients.
+
+**Middleware stack**
+
+- `TimingMiddleware`, `ErrorHandlingMiddleware`,
+  {class}`~libtmux_mcp.middleware.AuditMiddleware` (digest-redacted
+  argument summaries),
+  {class}`~libtmux_mcp.middleware.SafetyMiddleware` (tier-gated tool
+  visibility),
+  {class}`~libtmux_mcp.middleware.ReadonlyRetryMiddleware`
+  (transparent retry of readonly tools on transient
+  {exc}`libtmux.exc.LibTmuxException`; mutating tools never retry),
+  {class}`~libtmux_mcp.middleware.TailPreservingResponseLimitingMiddleware`
+  (trims oversized output from the head so the active prompt
+  survives).
+
+**Bounded outputs**
+
+- {tooliconl}`capture-pane`, {tooliconl}`snapshot-pane`,
+  {tooliconl}`show-buffer` accept `max_lines` (default 500) with
+  tail-preserving truncation and typed `content_truncated` /
+  `content_truncated_lines` signals. Pass `max_lines=None` to opt
+  out.
+
+**Other**
+
+- Tool input schemas carry per-parameter `description` fields
+  auto-extracted from NumPy-style docstrings.
+- Lifespan startup probe fails fast with {exc}`RuntimeError` if
+  `tmux` is missing on `PATH`.
+- {attr}`~libtmux_mcp.models.SessionInfo.active_pane_id` surfaces the
+  pane id returned by {tooliconl}`create-session`.
+
+### Fixes
+
+- {tooliconl}`search-panes` neutralizes tmux format-string injection
+  in the regex fast path.
+- macOS `TMUX_TMPDIR` self-kill guard: resolves the server socket via
+  `tmux display-message #{socket_path}` before env-based
+  reconstruction; basename-match fallback closes the launchd
+  divergence gap.
+- `build_dev_workspace` prompt uses the real tool parameter names
+  (`session_name=`, `pane_id=`, `direction=`) and no longer waits for
+  shell prompts after launching screen-grabbing programs (`vim`,
+  `watch`, `tail -f`). New `log_command` parameter replaces the
+  Linux-only `/var/log/syslog` default.
+- `ReadonlyRetryMiddleware` retry warnings log under
+  `libtmux_mcp.retry`.
+
+### Documentation
+
+- New per-tool pages: `buffers.md`, `hooks.md`, `waits.md`,
+  `tools/index.md`. `panes.md` documents the `SearchPanesResult`
+  migration. `safety.md` covers the macOS `TMUX_TMPDIR` caveat, the
+  audit log, `pipe_pane`, and `set_environment`.
+
 ## libtmux-mcp 0.1.0a1 (2026-04-13)
 
 ### What's new

conftest.py

@@ -24,7 +24,7 @@
 if t.TYPE_CHECKING:
     import pathlib
 
-pytest_plugins = ["pytester"]
+pytest_plugins = ["pytester", "sphinx.testing.fixtures"]
 
 
 @pytest.fixture(autouse=True)

docs/_ext/widgets/__init__.py

@@ -0,0 +1,64 @@
+"""Reusable widget framework for Sphinx docs.
+
+Each widget is a ``BaseWidget`` subclass in a sibling module (e.g.
+``mcp_install.py``) plus a ``<docs>/_widgets/<name>/widget.{html,js,css}``
+asset directory. Widgets autodiscover at ``setup()`` time — adding a new one
+requires no registry edits. Usage from Markdown/RST:
+
+.. code-block:: markdown
+
+   ```{mcp-install}
+   :variant: compact
+   ```
+"""
+
+from __future__ import annotations
+
+import functools
+import typing as t
+
+from ._assets import install_widget_assets
+from ._base import (
+    BaseWidget,
+    depart_widget_container,
+    visit_widget_container,
+    widget_container,
+)
+from ._directive import make_widget_directive
+from ._discovery import discover
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseWidget",
+    "__version__",
+    "setup",
+    "widget_container",
+]
+
+
+def setup(app: Sphinx) -> dict[str, t.Any]:
+    """Register every discovered widget and wire the asset pipeline."""
+    widgets = discover()
+
+    app.add_node(
+        widget_container,
+        html=(visit_widget_container, depart_widget_container),
+    )
+
+    for name, widget_cls in widgets.items():
+        app.add_directive(name, make_widget_directive(widget_cls))
+
+    app.connect(
+        "builder-inited",
+        functools.partial(install_widget_assets, widgets=widgets),
+    )
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_ext/widgets/_assets.py

@@ -0,0 +1,51 @@
+"""Copy widget assets into ``_static/widgets/<name>/`` and register them."""
+
+from __future__ import annotations
+
+import pathlib
+import typing as t
+
+from sphinx.util import logging
+from sphinx.util.fileutil import copy_asset_file
+
+from ._base import BaseWidget
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+logger = logging.getLogger(__name__)
+
+STATIC_SUBDIR = "widgets"
+
+
+def install_widget_assets(
+    app: Sphinx,
+    widgets: dict[str, type[BaseWidget]],
+) -> None:
+    """Copy each widget's ``widget.{css,js}`` into ``_static/widgets/<name>/``.
+
+    Assets are then registered via ``app.add_css_file`` / ``app.add_js_file`` so
+    every page includes them (same pattern as ``sphinx-copybutton``). This is
+    intentionally simpler than per-page inclusion — the files are small and the
+    docs are not bandwidth-constrained.
+    """
+    if app.builder.format != "html":
+        return
+
+    srcdir = pathlib.Path(app.srcdir)
+    outdir_static = pathlib.Path(app.outdir) / "_static" / STATIC_SUBDIR
+
+    for name, widget_cls in widgets.items():
+        asset_dir = widget_cls.assets_dir(srcdir)
+        dest = outdir_static / name
+
+        for filename, register in (
+            ("widget.css", app.add_css_file),
+            ("widget.js", app.add_js_file),
+        ):
+            source = asset_dir / filename
+            if not source.is_file():
+                continue
+            dest.mkdir(parents=True, exist_ok=True)
+            copy_asset_file(str(source), str(dest))
+            register(f"{STATIC_SUBDIR}/{name}/{filename}")