feat(api-tox): v2.2.0 Phase 1.1 — auto-rollback on error regression (#34)

* feat(api-tox): v2.2.0 Phase 1.1 — auto-rollback on error regression

First feature of the v2.2.0→v3.0 reliability phase (see
docs/ROADMAP.md). Wraps each LLM tool batch with a baseline-and-diff
check against td_get_errors plus a TD ui.undo.startBlock so the
whole batch is one undo entry. If the batch introduces new critical
errors (compile-style: Python syntax, expression-parse, GLSL
compile, Script DAT load), ui.undo.undo() rolls it back atomically
and a hint is appended to the last tool_result so the LLM sees the
regression on its next API call.

Pure-read batches skip the wrap (saves two td_get_errors calls);
batches containing td_exec_python / td_emergency_stabilize /
td_patch_apply stand down because their side effects aren't
undo-reversible (half-rolling-back is worse than not rolling back).

Disable via env var TDPILOT_DISABLE_AUTO_ROLLBACK=1. No version
bump — Phase 1 ships as v2.2.0 when the whole phase is in.

Implementation:

- NEW td_component/tdpilot_api_rollback.py — pure-Python predicate
  (is_critical_error), diff (diff_errors), batch classifier
  (batch_should_be_guarded), and the AutoRollbackGuard context
  manager. Two cook-thread handlers (handle_auto_rollback_begin /
  handle_auto_rollback_end) registered in TOOL_TO_HANDLER but NOT
  in TOOL_SCHEMAS — the LLM never sees them as callable tools.

- tdpilot_api_agent.py — new rollback_guard_factory ctor kwarg;
  _loop wraps the per-batch for-loop with the guard. Hint goes into
  the last tool_result's content (preserves the alternating
  user/assistant constraint) and also surfaces via on_text for the
  chat UI.

- tdpilot_api_runtime.py — _build_rollback_guard_factory reads
  TDPILOT_DISABLE_AUTO_ROLLBACK and returns None when disabled, in
  which case Agent._loop is a literal no-op around the guard.

- tdpilot_api_schema_map.py — INTERNAL_ONLY_TOOL_NAMES frozenset
  registered next to TOOL_TO_HANDLER; the schema-vs-handler parity
  pin tests in test_tdpilot_api_batch.py + test_tdpilot_api_tracing.py
  subtract this set so the parity invariant stays meaningful.

- tdpilot_api_extension.py — registers tdpilot_api_rollback as a
  handler module so the dispatcher finds the two internal handlers.

- build_tdpilot_api_tox.py — adds tdpilot_api_rollback to
  _SOURCE_FILES (auto-rolls into _API_TOX_SOURCE_FILES via the
  derivation in lines 1-50ish).

Tests:

- 60 new tests in tests/test_tdpilot_api_rollback.py covering the
  predicate (20+ pattern cases), diff, batch classifier, env-var
  gate, the guard's state machine (with a recorded mock dispatcher
  covering clean / regression / baseline-failure / undo-block-failure
  / exception-mid-batch / exec_python-standdown paths), the hint
  formatter, and the internal handlers' outside-TD failure mode.

- Two pre-existing parity-pin tests updated to honour the
  INTERNAL_ONLY_TOOL_NAMES exclusion.

Local sweep:
- pytest: 1760 passed (1700 prior + 60 new).
- ruff format / check: clean.
- check_versions: in sync at v2.1.5 (no bump on this PR).
- check_tox_freshness (MCP server tox): fresh — that tox not touched.
- check_tox_api_freshness (chat-pipe tox): EXPECTED FAIL until the
  user rebuilds the .tox inside TouchDesigner. See the rebuild
  recipe in AGENTS.md / feedback_td_tox_rebuild_recipe.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: rebuild tdpilot_API.tox for v2.2.0 Phase 1.1 (auto-rollback)

* ci(api-tox): sync SOURCE_FILES list to include tdpilot_api_rollback.py

Paired-list maintenance: build_tdpilot_api_tox.py:_API_TOX_SOURCE_FILES
and scripts/check_tox_api_freshness.py:SOURCE_FILES must contain the
same paths — the build script writes the hash, the check script
verifies it. Adding tdpilot_api_rollback.py to one but not the other
produced a stable mismatch (built hash a9a4..., check-computed
hash da67...) even on a freshly-rebuilt .tox.

This is a known footgun (the comment on line 28-32 of the check
script flags it explicitly); future Phase 1+ features adding new
source files will hit the same trap until both lists are
consolidated behind a single source of truth.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dreamrec

CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## Unreleased (v2.2.0 — Phase 1 in progress)
+
+**v2.2.0 will be the first release of the v2.2.0→v3.0 roadmap (see
+`docs/ROADMAP.md`).** Phase 1 ("Reliability foundation") ships across
+multiple PRs; v2.2.0 cuts when the whole phase is in. Until then,
+"Unreleased" tracks the in-progress work.
+
+### Added — Feature 1.1: Auto-rollback on error regression (chat-pipe / `tdpilot_API.tox`)
+
+Each LLM tool batch is now wrapped with a baseline-and-diff check
+against `td_get_errors`, plus a TD `ui.undo.startBlock` so the whole
+batch becomes one undo entry. If new *critical* errors appear after
+the batch (compile-style only — Python syntax, expression-parse,
+GLSL compile, Script DAT load), the batch is rolled back atomically
+via `ui.undo.undo()` and a hint is appended to the last
+`tool_result` so the LLM sees the regression on its next API call.
+The same hint surfaces to the chat UI via `on_text`.
+
+**Implementation:**
+
+- New `td_component/tdpilot_api_rollback.py`: pure-Python predicate
+  (`is_critical_error`), diff (`diff_errors`), batch classifier
+  (`batch_should_be_guarded`), and the `AutoRollbackGuard` context
+  manager. Two cook-thread handlers (`handle_auto_rollback_begin` /
+  `handle_auto_rollback_end`) registered in `TOOL_TO_HANDLER` but
+  NOT in `TOOL_SCHEMAS` — the LLM never sees them as callable
+  tools; only the guard invokes them internally.
+- `td_component/tdpilot_api_agent.py`: new `rollback_guard_factory`
+  constructor kwarg; `_loop` wraps the per-batch `for tu in
+  tool_uses` block with the guard via a context-manager protocol.
+- `td_component/tdpilot_api_runtime.py`: `_build_rollback_guard_factory`
+  honours the `TDPILOT_DISABLE_AUTO_ROLLBACK=1` env var; returns
+  `None` (no-op) when disabled.
+- Coverage in `tests/test_tdpilot_api_rollback.py` — 60 tests across
+  the predicate, diff, batch classifier, env-var gate, the guard's
+  state machine (with a recorded mock dispatcher), the hint
+  formatter, and the internal handlers' outside-TD failure mode.
+
+**Standdowns (auto-rollback skips the wrap):**
+
+- Pure-read batches (nothing in `MUTATION_TOOL_NAMES`) — saves two
+  `td_get_errors` calls per batch.
+- Batches containing any tool whose side effects `ui.undo` can't
+  revert (`td_exec_python`, `td_emergency_stabilize`, `td_patch_apply`).
+  Half-rolling-back is worse than not rolling back.
+- Baseline-capture failure (dispatcher raised) — degrades to no-guard
+  silently rather than breaking the user's turn.
+
+**Opt-out:** set `TDPILOT_DISABLE_AUTO_ROLLBACK=1` in the TD process
+environment.
+
+**Files baked into the API .tox** (rebuild required after pulling
+this change):
+
+- `td_component/tdpilot_api_rollback.py` (new)
+- `td_component/tdpilot_api_agent.py` (modified)
+- `td_component/tdpilot_api_runtime.py` (modified)
+- `td_component/tdpilot_api_extension.py` (modified — adds the
+  rollback module to the dispatcher's handler-module list)
+- `td_component/tdpilot_api_schema_map.py` (modified — registers
+  the two internal handlers in `TOOL_TO_HANDLER`)
+- `td_component/build_tdpilot_api_tox.py` (modified — adds
+  `tdpilot_api_rollback` to `_SOURCE_FILES`)
+
+Phase 1.2 (cycle detection) and the rest of Phase 1 follow in
+subsequent PRs.
+
 ## 2.1.5 - 2026-05-10
 
 **Patch: Codex P2 follow-up on v2.1.4 (PR #29).** A cosmetic-but-real

scripts/check_tox_api_freshness.py

@@ -56,6 +56,10 @@
     "td_component/tdpilot_api_introspect.py",
     "td_component/tdpilot_api_batch.py",
     "td_component/tdpilot_api_recovery.py",
+    # v2.2.0 Phase 1.1 — auto-rollback on error regression. Pure module
+    # exporting AutoRollbackGuard + two ui.undo-touching internal
+    # handlers; baked into the API .tox.
+    "td_component/tdpilot_api_rollback.py",
     "td_component/tdpilot_api_tracing.py",
     "td_component/tdpilot_api_compaction.py",
     "td_component/tdpilot_api_chat.html",

td_component/.tox-api-source-hash.json

@@ -1,6 +1,6 @@
 {
-  "tox_source_hash": "6ab876c51d853a1dd4ed40d2c2bb2d09dfee8ae6d260eeffb5a832db3239bea7",
-  "built_at": "2026-05-10T09:45:13.132660+00:00",
+  "tox_source_hash": "a9a4765ad22188ae30d92d8998c86b9516fce727ab0d3ac711be792a4c791424",
+  "built_at": "2026-05-11T13:50:16.731643+00:00",
   "source_files": [
     "td_component/tdpilot_api_agent.py",
     "td_component/tdpilot_api_dispatcher.py",
@@ -25,6 +25,7 @@
     "td_component/tdpilot_api_introspect.py",
     "td_component/tdpilot_api_batch.py",
     "td_component/tdpilot_api_recovery.py",
+    "td_component/tdpilot_api_rollback.py",
     "td_component/tdpilot_api_tracing.py",
     "td_component/tdpilot_api_compaction.py",
     "td_component/tdpilot_api_chat.html",

td_component/build_tdpilot_api_tox.py

@@ -207,6 +207,12 @@ def _load_legacy_module():
     ("tdpilot_api_introspect", "textDAT", "td_component/tdpilot_api_introspect.py"),
     ("tdpilot_api_batch", "textDAT", "td_component/tdpilot_api_batch.py"),
     ("tdpilot_api_recovery", "textDAT", "td_component/tdpilot_api_recovery.py"),
+    # Phase 1.1 (v2.2.0) — auto-rollback on error regression. Pure module
+    # except for two ``ui.undo``-touching handlers exposed only via
+    # TOOL_TO_HANDLER (not TOOL_SCHEMAS) so the LLM never calls them
+    # directly; the AutoRollbackGuard invokes them internally around
+    # each tool-batch in tdpilot_api_agent._loop.
+    ("tdpilot_api_rollback", "textDAT", "td_component/tdpilot_api_rollback.py"),
     ("tdpilot_api_tracing", "textDAT", "td_component/tdpilot_api_tracing.py"),
     ("tdpilot_api_compaction", "textDAT", "td_component/tdpilot_api_compaction.py"),
     ("tdpilot_api_chat_html", "textDAT", "td_component/tdpilot_api_chat.html"),

td_component/tdpilot_API.tox

@@ -264,6 +264,13 @@ def __init__(
         # Treat all keys as optional — DeepSeek's compat layer may omit
         # some fields depending on the model version.
         on_usage: Callable[[dict], None] = _noop,
+        # Phase 1.1 (v2.2.0) — auto-rollback on error regression.
+        # Factory takes ``(dispatcher, tool_names)`` and returns a
+        # context manager (e.g. ``AutoRollbackGuard``) used to wrap each
+        # tool batch in ``_loop``. ``None`` disables the feature entirely
+        # — the loop runs unwrapped, identical to pre-v2.2.0 behaviour.
+        # Wired by AgentRuntime so it can honour ``TDPILOT_DISABLE_AUTO_ROLLBACK``.
+        rollback_guard_factory: Callable[..., Any] | None = None,
     ) -> None:
         if not api_key:
             raise AgentError("api_key is required")
@@ -310,6 +317,7 @@ def __init__(
         self.on_turn_done = on_turn_done
         self.on_error = on_error
         self.on_usage = on_usage
+        self.rollback_guard_factory = rollback_guard_factory
 
         self.messages: list[dict] = []
         self._stop_flag = threading.Event()
@@ -532,32 +540,94 @@ def _loop(self) -> str | None:
                 return text_blob
 
             # Execute tools, collect results, send back as a user turn.
-            results_block = []
-            for tu in tool_uses:
-                tool_id = tu.get("id", "")
-                tool_name = tu.get("name", "")
-                tool_args = tu.get("input", {}) or {}
-                self.on_tool_call(tool_name, tool_args)
+            # Phase 1.1 (v2.2.0) — auto-rollback wrap: capture baseline
+            # errors + open a TD undo block before the batch; after the
+            # batch, recheck errors and either close the block (clean
+            # path) or roll it back (regression path). The factory may
+            # return None or a no-op guard if disabled via env var; the
+            # ``with`` block is always safe to enter.
+            tool_names_in_batch = [tu.get("name", "") for tu in tool_uses]
+            rollback_guard = None
+            if self.rollback_guard_factory is not None:
                 try:
-                    result = self.dispatcher(tool_name, tool_args)
-                    # F-12: the explicit `_tool_error` sentinel is the
-                    # only failure signal post-v2.0. Internal handlers
-                    # that emit `{"error": "..."}` get auto-stamped
-                    # with `_tool_error: True` by `recovery.attach_hint()`
-                    # inside the dispatcher pipeline.
-                    is_error = is_tool_error_result(result)
-                except Exception as exc:  # noqa: BLE001
-                    result = {"_tool_error": True, "error": f"{type(exc).__name__}: {exc}"}
-                    is_error = True
-                self.on_tool_result(tool_name, result, is_error)
-                results_block.append(
-                    {
-                        "type": "tool_result",
-                        "tool_use_id": tool_id,
-                        "content": _stringify(result),
-                        "is_error": is_error,
-                    }
-                )
+                    rollback_guard = self.rollback_guard_factory(
+                        self.dispatcher,
+                        tool_names_in_batch,
+                    )
+                except Exception as exc:  # noqa: BLE001 — factory must never break a turn
+                    print(f"[tdpilot_API/agent] rollback_guard_factory raised: {exc}")
+                    rollback_guard = None
+
+            results_block: list[dict] = []
+            try:
+                if rollback_guard is not None:
+                    rollback_guard.__enter__()
+                for tu in tool_uses:
+                    tool_id = tu.get("id", "")
+                    tool_name = tu.get("name", "")
+                    tool_args = tu.get("input", {}) or {}
+                    self.on_tool_call(tool_name, tool_args)
+                    try:
+                        result = self.dispatcher(tool_name, tool_args)
+                        # F-12: the explicit `_tool_error` sentinel is the
+                        # only failure signal post-v2.0. Internal handlers
+                        # that emit `{"error": "..."}` get auto-stamped
+                        # with `_tool_error: True` by `recovery.attach_hint()`
+                        # inside the dispatcher pipeline.
+                        is_error = is_tool_error_result(result)
+                    except Exception as exc:  # noqa: BLE001
+                        result = {
+                            "_tool_error": True,
+                            "error": f"{type(exc).__name__}: {exc}",
+                        }
+                        is_error = True
+                    self.on_tool_result(tool_name, result, is_error)
+                    results_block.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": tool_id,
+                            "content": _stringify(result),
+                            "is_error": is_error,
+                        }
+                    )
+            finally:
+                if rollback_guard is not None:
+                    # __exit__ runs the post-batch check + decides rollback;
+                    # we always want this to fire even if the batch raised.
+                    try:
+                        rollback_guard.__exit__(None, None, None)
+                    except Exception as exc:  # noqa: BLE001
+                        print(f"[tdpilot_API/agent] rollback_guard.__exit__ raised: {exc}")
+
+            # Phase 1.1 — if the guard fired a rollback, append a hint to
+            # the LAST tool_result so the LLM sees the regression context
+            # on its next API call. The hint goes in the tool_result's
+            # content (which can be a list of blocks) — keeps the
+            # alternating user/assistant constraint intact and pairs the
+            # hint with the failing batch's results.
+            if (
+                rollback_guard is not None
+                and getattr(rollback_guard, "rollback_fired", False)
+                and getattr(rollback_guard, "hint_text", "")
+                and results_block
+            ):
+                hint = rollback_guard.hint_text
+                last = results_block[-1]
+                existing = last.get("content")
+                if isinstance(existing, str):
+                    last["content"] = existing + "\n\n" + hint
+                elif isinstance(existing, list):
+                    last["content"] = list(existing) + [{"type": "text", "text": hint}]
+                else:
+                    last["content"] = hint
+                # Surface to the chat UI too — same callback the agent's
+                # natural-language text uses, so the user sees a yellow
+                # inline notice in the assistant bubble.
+                try:
+                    self.on_text(hint)
+                except Exception:  # noqa: BLE001
+                    pass
+
             self.messages.append({"role": "user", "content": results_block})
 
             if stop_reason == "end_turn":

td_component/tdpilot_api_agent.py

@@ -271,6 +271,11 @@ def _build_runtime(self) -> None:
                 ("tdpilot_api_introspect", "introspect"),
                 ("tdpilot_api_batch", "tool_batch"),
                 ("tdpilot_api_tracing", "tracing"),
+                # Phase 1.1 — auto_rollback_begin / auto_rollback_end live
+                # here. Registered in TOOL_TO_HANDLER but NOT in
+                # TOOL_SCHEMAS, so the LLM can't call them — only the
+                # AutoRollbackGuard invokes them around each tool batch.
+                ("tdpilot_api_rollback", "rollback"),
             ):
                 dat = self.owner.op(mod_name)
                 if dat is not None: