textual-debugger 0.2.10__tar.gz → 0.2.12__tar.gz

{textual_debugger-0.2.10 → textual_debugger-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.10
+Version: 0.2.12
 Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -53,7 +53,7 @@ Requires-Dist: debugpy>=1.8.12
 Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
-Requires-Dist: mcp<2.0.0,>=1.28.0
+Requires-Dist: mcp<3.0.0,>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -115,7 +115,7 @@ It specifically supports modules
 
 - supports remote attachment to Python, Perl, Ruby, Rust, C/C++, and Go programs
 
-- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+- includes a JSON-RPC server mode, an MCP (v2) mode, and a `SKILL.md` file that enable
 programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
@@ -129,28 +129,6 @@ to have `tdb` pop open automatically at the first uncaught exception
 making it suitable for operation in non-graphical environments (mouse support is
 available in graphical environments)
 
-## Acknowledgments
-
-Thank you:
-
-- Will McGugan for the amazing `textual` module.
-`tdb` would be a pale shadow of itself had I used any other TUI framework.
-Fantastic work, Will.
-
-- Microsoft for the Debug Adapter Protocol (DAP) and releasing
-its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
-as open source.
-
-- Anthropic, for providing access to Claude Code through the
-[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
-`tdb` was made almost entirely with Claude Code.
-
-- OpenAI, for providing access to Codex through the
-[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
-
-This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
-Python debugger.
-
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -190,6 +168,10 @@ uvx --from textual-debugger tdb  my_program.py
 # show comprehensive documentation in a terminal-based Markdown viewer
 tdb --doc
 
+# show where tdb is installed, where its bundled Perl PadWalker module
+# lives, and the Help > About text
+tdb --info
+
 # debug a script (stops at first line by default)
 tdb my_program.py
 
@@ -337,7 +319,7 @@ non-standard location, or change a language's default adapter, add to
 Core debugging works identically for every language: breakpoints (incl.
 conditions and persistence), stepping, continue/pause, run-to-cursor, stack
 navigation, variable inspection, the evaluate console, syntax highlighting,
-and the JSON-RPC / MCP programmatic modes.
+and the JSON-RPC / MCP (v2) programmatic modes.
 
 Python-specific features are hidden or return "not supported for this
 language" message when debugging other languages: statement-granularity
@@ -541,6 +523,24 @@ metadata for broader primitives and stronger ownership evidence.
 `perl` ≥ 5.18 on `PATH`. It drives stock `perl5db` under the
 hood, so it works with any Perl already on the system.
 
+The [PadWalker](https://metacpan.org/pod/PadWalker) module v2.5, by Robin Houston,
+is bundled with `tdb`.  PadWalker provides a more complete view of lexical variables
+in outer/caller frames and therefore provides a richer debugging experience.
+PadWalker is an XS (compiled) module, so the bundled copy has to be built
+against the exact perl that runs your program.  `tdb` does this for you on the
+first Perl launch: if the perl in use cannot already load PadWalker (from CPAN
+or a distro package), `tdb` compiles the bundled sources, caches the result
+per interpreter under its config directory (`~/.config/tdb/padwalker/` on
+Linux/macOS, `%APPDATA%\\tdb\\padwalker\\` on Windows), and prepends that
+directory to the debuggee's `PERL5LIB`.  The build takes about a second and
+needs perl's headers (`libperl-dev` on Debian/Ubuntu, `perl-devel` on
+Fedora/RHEL) plus a C compiler; Strawberry Perl on Windows ships both.  When
+the build is not possible, `tdb` prints a one-line notice on the console and
+falls back to a read-only pad walk, so outer-frame lexicals degrade but
+debugging otherwise proceeds.  `tdb --info` reports the source directory, the
+cache directory, and whether a build exists for the `perl` on your `PATH`.
+`TDB_PADWALKER_CACHE` overrides the cache location.
+
 **Launching a script:**
 
 ```bash
@@ -637,13 +637,6 @@ export PERL5LIB=/opt/tdb-perl:$PERL5LIB
 the two files in the same relative layout shown above; `helpers.pl` is a
 sibling of the `Devel/` directory, not inside it.)
 
-**PadWalker (optional but recommended):** inspecting lexical (`my`)
-variables in the *current* frame always works. Lexicals in outer/caller
-frames need the `PadWalker` module installed on the debuggee's Perl; without
-it, tdb falls back to a read-only pad walk that can't reach fully into
-enclosing scopes, and outer-frame variable listings degrade accordingly.
-Install with `cpanm PadWalker` (or your distro's package) for full fidelity.
-
 **Pause is unavailable in attach mode.** Launch-mode sessions (`tdb
 script.pl`) support pausing a running program at any time. Remote-attach
 sessions don't. Asynchronous pause (as Python gets via `debugpy`) needs a control channel
@@ -1517,6 +1510,54 @@ available (breakpoints, stepping, variable inspection, the evaluate console). Th
 debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
 group), so its own `SIGINT` handling is undisturbed.
 
+**Examining without opening the TUI:** press `Ctrl-\` in the terminal (`Ctrl-Break` on
+Windows), or, on Unix, send `SIGUSR2` to `tdb`'s pid: `kill -USR2 <tdb pid>`.
+
+**Windows caveat:** the Ctrl-Break trigger is untested. Unlike Ctrl-C, a console
+Ctrl-Break is delivered to every process attached to the console, including the debug
+adapter and the program itself, so it may terminate the program instead of snapshotting
+it. There is no signal-based alternative on Windows.
+
+`tdb` pauses the program, writes one JSON line describing the call stack of every thread
+(plus asyncio tasks and multiprocessing children for Python, goroutines for Go, and
+the concurrency snapshot for Rust), and resumes the program. Ctrl-C behavior is
+unchanged. By default the line goes to stdout; `--examine-log DEST` sends it to a file
+instead (`-` means stdout; repeat the flag to write to several places):
+
+```bash
+tdb --run --examine-log hang.jsonl my_program.py     # file only, appended
+tdb --run --examine-log - --examine-log hang.jsonl my_program.py   # both
+```
+
+Each record looks like (abridged):
+
+```json
+{"schema":1,"seq":1,"trigger":"SIGQUIT","status":"ok",
+ "requested_at":"2026-09-07T14:02:11.482-07:00","landed_at":"2026-09-07T14:02:11.511-07:00",
+ "elapsed_s":87.3,"language":"python","program":"/home/al/work/app.py",
+ "processes":[{"pid":41213,"role":"parent","name":null,
+   "threads":[{"id":1,"name":"MainThread","frames":[
+     {"function":"wait","file":"/usr/lib/python3.13/threading.py","line":359},
+     {"function":"main","file":"/home/al/work/app.py","line":42}]}],
+   "tasks":[{"name":"worker-2","state":"PENDING","awaiting":"Lock.acquire","frames":["run (/home/al/work/app.py:18)"]}]}],
+ "errors":[]}
+```
+
+Frames are innermost first. `tasks` appears only for Python programs with live asyncio
+tasks; `goroutines` only for Go; `rust_concurrency` only for Rust. `status` is
+`"pending"` when the pause could not land within a few seconds (the program is blocked
+inside a single call) -- a second record with the same `seq` and `status: "ok"` follows
+when it does land. If you press Ctrl-C or the program exits before it lands, no
+completing record is written. `errors` lists any sub-collector that failed, so a partial
+record is explicit about what is missing. A stderr line confirms each capture and where
+it went.
+
+Narrow a long capture with `jq`, for example only threads with a frame in your own code:
+
+```bash
+jq -c '.processes[].threads[] | select(any(.frames[]; .file != null and (.file|test("/work/"))))' hang.jsonl
+```
+
 **Quitting an adopted session** adds a third choice to the usual quit dialog:
 - `d` (or `q`) -- detach and resume: the program keeps running headlessly; interrupt it
   again later the same way.
@@ -1541,7 +1582,7 @@ language.
 blocking external call or syscall, the pause can't land until that call returns --
 `tdb` prints a notice and opens the TUI once the stop actually arrives.
 
-**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--server`,
+**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--replay-tui`, `--server`,
 `--headless`, `--mcp`, `--terminal`.
 
 ### Eval Mode (`-e`/`--eval`)
@@ -1584,7 +1625,7 @@ evaluated in each child process that reaches it.
   the eval point matches that bound line, so the expression still runs.
 
 **Incompatible flags:** `--run`, `-r`, `-a`, `-k`/`-t`, `--record`,
-`--replay`, `--server`, `--headless`, `--mcp`, `--terminal`.
+`--replay`, `--replay-tui`, `--server`, `--headless`, `--mcp`, `--terminal`.
 
 ### Keybinding Schemes
 
@@ -1706,14 +1747,29 @@ written to `session.jsonl` as
 JSON-RPC commands. Works with launch mode (any language) and `-r`
 remote attach.
 
-Replay it two ways:
-
+Replay it three ways:
+
+- `tdb --replay-tui session.jsonl` opens the normal TUI on the recorded
+  program and performs every recorded action in front of you, at the
+  recorded pace: breakpoints appear in the Code View, steps and continues
+  move the cursor, Evaluate entries echo into the console with their
+  results, stack navigation and variable expansion play out in their
+  panels. The title bar shows progress (`tdb ▶ session.jsonl 3/11`) and a
+  toast announces each action (`--replay-quiet` turns those toasts off).
+  A failed action raises an error toast and replay continues. When the recording does not end with `quit`, the
+  debugger stays open at the final stop for you to carry on by hand.
+  `--replay-interval S` waits a fixed S seconds before each action
+  instead of reproducing the recorded gaps. `--replay-timeout S` bounds
+  each stop-wait (default 30 s). Exit code 0
+  iff every action succeeded. Don't type into the TUI while it is
+  replaying: stray keystrokes interleave with the recorded actions.
 - `tdb --replay session.jsonl` launches the recorded
   program headless, feeds every recorded command through the same RPC
   dispatch `tdb --server` uses, and prints a transcript (recorded time,
   command, verbatim result, interleaved program output). Exit code 0 iff
   every command succeeded. Add `--timing` to reproduce the original
-  pacing, `--replay-timeout S` to bound each stop-wait (default 30 s).
+  pacing or `--replay-interval S` for a fixed delay before each command,
+  `--replay-timeout S` to bound each stop-wait (default 30 s).
 - Against a live server: start `tdb --server prog.py`, then feed line 2
   onward of the file to `POST /rpc` . Each line is a valid request body:
 
@@ -1730,9 +1786,10 @@ lists), breakpoint enable/disable toggles, variable expansions when the
 adapter reports no `evaluateName` (currently the Perl adapter), and
 File > Open program switches.
 
-## MCP Integration
+## MCP v2 Integration
 
-tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+tdb ships a Model Context Protocol (MCP), version 2,
+server (`tdb-mcp`) that exposes
 the debugger as a curated set of tools an AI agent can call. The MCP
 server is a third in-process consumer of the same dispatch handlers the
 TUI and the HTTP server use so an agent gets the same lock semantics,
@@ -1830,7 +1887,7 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
-           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text]
+           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text] [--info]
            [program] [args ...]
 ```
 
@@ -1857,6 +1914,14 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--server` | Enable JSON-RPC server alongside TUI |
 | `--headless` | JSON-RPC server only, no TUI |
 | `--server-port PORT` | Server port (default: 8150) |
+| `--record FILE` | Record this TUI session's debugging actions to FILE (JSON-RPC lines) |
+| `--replay FILE` | Replay a recording headless, printing a transcript (no program argument) |
+| `--replay-tui FILE` | Replay a recording inside the TUI at the recorded pace, so you can watch it |
+| `--replay-quiet` | With `--replay-tui`: no per-action toasts (errors and the final summary still show) |
+| `--timing` | With `--replay`: reproduce the recorded pacing (`--replay-tui` always does) |
+| `--replay-interval S` | With `--replay`/`--replay-tui`: fixed S-second delay before each action instead of the recorded gaps |
+| `--replay-timeout S` | With `--replay`/`--replay-tui`: per-action stop-wait timeout (default 30) |
+| `--examine-log DEST` | With --run: write each Ctrl-\ / SIGUSR2 stack snapshot to DEST (- = stdout; repeatable) |
 
 ## Configuration
 
@@ -1917,6 +1982,28 @@ fires as expected.
 
 MIT
 
+## Acknowledgments
+
+Thank you:
+
+- Will McGugan for the amazing `textual` module.
+`tdb` would be a pale shadow of itself had I used any other TUI framework.
+Fantastic work, Will.
+
+- Microsoft for the Debug Adapter Protocol (DAP) and releasing
+its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
+as open source.
+
+- Anthropic, for providing access to Claude Code through the
+[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
+`tdb` was made almost entirely with Claude Code.
+
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
+Python debugger.
+
 
 ## Known Problems
 

{textual_debugger-0.2.10/src/tdb → textual_debugger-0.2.12}/README.md

@@ -47,7 +47,7 @@ It specifically supports modules
 
 - supports remote attachment to Python, Perl, Ruby, Rust, C/C++, and Go programs
 
-- includes a JSON-RPC server mode, an MCP mode, and a `SKILL.md` file that enable
+- includes a JSON-RPC server mode, an MCP (v2) mode, and a `SKILL.md` file that enable
 programmatic debug control, making it suitable for
 automated, headless debugging workflows and AI-assisted debugging
 
@@ -61,28 +61,6 @@ to have `tdb` pop open automatically at the first uncaught exception
 making it suitable for operation in non-graphical environments (mouse support is
 available in graphical environments)
 
-## Acknowledgments
-
-Thank you:
-
-- Will McGugan for the amazing `textual` module.
-`tdb` would be a pale shadow of itself had I used any other TUI framework.
-Fantastic work, Will.
-
-- Microsoft for the Debug Adapter Protocol (DAP) and releasing
-its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
-as open source.
-
-- Anthropic, for providing access to Claude Code through the
-[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
-`tdb` was made almost entirely with Claude Code.
-
-- OpenAI, for providing access to Codex through the
-[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
-
-This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
-Python debugger.
-
 ## Gallery
 <p align="center">
   <img src="https://github.com/AlDanial/tdb/blob/main/gallery/async_breakpoint.png" alt="at breakpoint" width="300">
@@ -122,6 +100,10 @@ uvx --from textual-debugger tdb  my_program.py
 # show comprehensive documentation in a terminal-based Markdown viewer
 tdb --doc
 
+# show where tdb is installed, where its bundled Perl PadWalker module
+# lives, and the Help > About text
+tdb --info
+
 # debug a script (stops at first line by default)
 tdb my_program.py
 
@@ -269,7 +251,7 @@ non-standard location, or change a language's default adapter, add to
 Core debugging works identically for every language: breakpoints (incl.
 conditions and persistence), stepping, continue/pause, run-to-cursor, stack
 navigation, variable inspection, the evaluate console, syntax highlighting,
-and the JSON-RPC / MCP programmatic modes.
+and the JSON-RPC / MCP (v2) programmatic modes.
 
 Python-specific features are hidden or return "not supported for this
 language" message when debugging other languages: statement-granularity
@@ -473,6 +455,24 @@ metadata for broader primitives and stronger ownership evidence.
 `perl` ≥ 5.18 on `PATH`. It drives stock `perl5db` under the
 hood, so it works with any Perl already on the system.
 
+The [PadWalker](https://metacpan.org/pod/PadWalker) module v2.5, by Robin Houston,
+is bundled with `tdb`.  PadWalker provides a more complete view of lexical variables
+in outer/caller frames and therefore provides a richer debugging experience.
+PadWalker is an XS (compiled) module, so the bundled copy has to be built
+against the exact perl that runs your program.  `tdb` does this for you on the
+first Perl launch: if the perl in use cannot already load PadWalker (from CPAN
+or a distro package), `tdb` compiles the bundled sources, caches the result
+per interpreter under its config directory (`~/.config/tdb/padwalker/` on
+Linux/macOS, `%APPDATA%\\tdb\\padwalker\\` on Windows), and prepends that
+directory to the debuggee's `PERL5LIB`.  The build takes about a second and
+needs perl's headers (`libperl-dev` on Debian/Ubuntu, `perl-devel` on
+Fedora/RHEL) plus a C compiler; Strawberry Perl on Windows ships both.  When
+the build is not possible, `tdb` prints a one-line notice on the console and
+falls back to a read-only pad walk, so outer-frame lexicals degrade but
+debugging otherwise proceeds.  `tdb --info` reports the source directory, the
+cache directory, and whether a build exists for the `perl` on your `PATH`.
+`TDB_PADWALKER_CACHE` overrides the cache location.
+
 **Launching a script:**
 
 ```bash
@@ -569,13 +569,6 @@ export PERL5LIB=/opt/tdb-perl:$PERL5LIB
 the two files in the same relative layout shown above; `helpers.pl` is a
 sibling of the `Devel/` directory, not inside it.)
 
-**PadWalker (optional but recommended):** inspecting lexical (`my`)
-variables in the *current* frame always works. Lexicals in outer/caller
-frames need the `PadWalker` module installed on the debuggee's Perl; without
-it, tdb falls back to a read-only pad walk that can't reach fully into
-enclosing scopes, and outer-frame variable listings degrade accordingly.
-Install with `cpanm PadWalker` (or your distro's package) for full fidelity.
-
 **Pause is unavailable in attach mode.** Launch-mode sessions (`tdb
 script.pl`) support pausing a running program at any time. Remote-attach
 sessions don't. Asynchronous pause (as Python gets via `debugpy`) needs a control channel
@@ -1449,6 +1442,54 @@ available (breakpoints, stepping, variable inspection, the evaluate console). Th
 debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
 group), so its own `SIGINT` handling is undisturbed.
 
+**Examining without opening the TUI:** press `Ctrl-\` in the terminal (`Ctrl-Break` on
+Windows), or, on Unix, send `SIGUSR2` to `tdb`'s pid: `kill -USR2 <tdb pid>`.
+
+**Windows caveat:** the Ctrl-Break trigger is untested. Unlike Ctrl-C, a console
+Ctrl-Break is delivered to every process attached to the console, including the debug
+adapter and the program itself, so it may terminate the program instead of snapshotting
+it. There is no signal-based alternative on Windows.
+
+`tdb` pauses the program, writes one JSON line describing the call stack of every thread
+(plus asyncio tasks and multiprocessing children for Python, goroutines for Go, and
+the concurrency snapshot for Rust), and resumes the program. Ctrl-C behavior is
+unchanged. By default the line goes to stdout; `--examine-log DEST` sends it to a file
+instead (`-` means stdout; repeat the flag to write to several places):
+
+```bash
+tdb --run --examine-log hang.jsonl my_program.py     # file only, appended
+tdb --run --examine-log - --examine-log hang.jsonl my_program.py   # both
+```
+
+Each record looks like (abridged):
+
+```json
+{"schema":1,"seq":1,"trigger":"SIGQUIT","status":"ok",
+ "requested_at":"2026-09-07T14:02:11.482-07:00","landed_at":"2026-09-07T14:02:11.511-07:00",
+ "elapsed_s":87.3,"language":"python","program":"/home/al/work/app.py",
+ "processes":[{"pid":41213,"role":"parent","name":null,
+   "threads":[{"id":1,"name":"MainThread","frames":[
+     {"function":"wait","file":"/usr/lib/python3.13/threading.py","line":359},
+     {"function":"main","file":"/home/al/work/app.py","line":42}]}],
+   "tasks":[{"name":"worker-2","state":"PENDING","awaiting":"Lock.acquire","frames":["run (/home/al/work/app.py:18)"]}]}],
+ "errors":[]}
+```
+
+Frames are innermost first. `tasks` appears only for Python programs with live asyncio
+tasks; `goroutines` only for Go; `rust_concurrency` only for Rust. `status` is
+`"pending"` when the pause could not land within a few seconds (the program is blocked
+inside a single call) -- a second record with the same `seq` and `status: "ok"` follows
+when it does land. If you press Ctrl-C or the program exits before it lands, no
+completing record is written. `errors` lists any sub-collector that failed, so a partial
+record is explicit about what is missing. A stderr line confirms each capture and where
+it went.
+
+Narrow a long capture with `jq`, for example only threads with a frame in your own code:
+
+```bash
+jq -c '.processes[].threads[] | select(any(.frames[]; .file != null and (.file|test("/work/"))))' hang.jsonl
+```
+
 **Quitting an adopted session** adds a third choice to the usual quit dialog:
 - `d` (or `q`) -- detach and resume: the program keeps running headlessly; interrupt it
   again later the same way.
@@ -1473,7 +1514,7 @@ language.
 blocking external call or syscall, the pause can't land until that call returns --
 `tdb` prints a notice and opens the TUI once the stop actually arrives.
 
-**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--server`,
+**Incompatible flags:** `-r`, `-k`/`-t`, `--record`, `--replay`, `--replay-tui`, `--server`,
 `--headless`, `--mcp`, `--terminal`.
 
 ### Eval Mode (`-e`/`--eval`)
@@ -1516,7 +1557,7 @@ evaluated in each child process that reaches it.
   the eval point matches that bound line, so the expression still runs.
 
 **Incompatible flags:** `--run`, `-r`, `-a`, `-k`/`-t`, `--record`,
-`--replay`, `--server`, `--headless`, `--mcp`, `--terminal`.
+`--replay`, `--replay-tui`, `--server`, `--headless`, `--mcp`, `--terminal`.
 
 ### Keybinding Schemes
 
@@ -1638,14 +1679,29 @@ written to `session.jsonl` as
 JSON-RPC commands. Works with launch mode (any language) and `-r`
 remote attach.
 
-Replay it two ways:
-
+Replay it three ways:
+
+- `tdb --replay-tui session.jsonl` opens the normal TUI on the recorded
+  program and performs every recorded action in front of you, at the
+  recorded pace: breakpoints appear in the Code View, steps and continues
+  move the cursor, Evaluate entries echo into the console with their
+  results, stack navigation and variable expansion play out in their
+  panels. The title bar shows progress (`tdb ▶ session.jsonl 3/11`) and a
+  toast announces each action (`--replay-quiet` turns those toasts off).
+  A failed action raises an error toast and replay continues. When the recording does not end with `quit`, the
+  debugger stays open at the final stop for you to carry on by hand.
+  `--replay-interval S` waits a fixed S seconds before each action
+  instead of reproducing the recorded gaps. `--replay-timeout S` bounds
+  each stop-wait (default 30 s). Exit code 0
+  iff every action succeeded. Don't type into the TUI while it is
+  replaying: stray keystrokes interleave with the recorded actions.
 - `tdb --replay session.jsonl` launches the recorded
   program headless, feeds every recorded command through the same RPC
   dispatch `tdb --server` uses, and prints a transcript (recorded time,
   command, verbatim result, interleaved program output). Exit code 0 iff
   every command succeeded. Add `--timing` to reproduce the original
-  pacing, `--replay-timeout S` to bound each stop-wait (default 30 s).
+  pacing or `--replay-interval S` for a fixed delay before each command,
+  `--replay-timeout S` to bound each stop-wait (default 30 s).
 - Against a live server: start `tdb --server prog.py`, then feed line 2
   onward of the file to `POST /rpc` . Each line is a valid request body:
 
@@ -1662,9 +1718,10 @@ lists), breakpoint enable/disable toggles, variable expansions when the
 adapter reports no `evaluateName` (currently the Perl adapter), and
 File > Open program switches.
 
-## MCP Integration
+## MCP v2 Integration
 
-tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
+tdb ships a Model Context Protocol (MCP), version 2,
+server (`tdb-mcp`) that exposes
 the debugger as a curated set of tools an AI agent can call. The MCP
 server is a third in-process consumer of the same dispatch handlers the
 TUI and the HTTP server use so an agent gets the same lock semantics,
@@ -1762,7 +1819,7 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
-           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text]
+           [--server] [--headless] [-k FILE:LINE|LINE] [--server-port SERVER_PORT] [-d] [--doc-text] [--info]
            [program] [args ...]
 ```
 
@@ -1789,6 +1846,14 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--server` | Enable JSON-RPC server alongside TUI |
 | `--headless` | JSON-RPC server only, no TUI |
 | `--server-port PORT` | Server port (default: 8150) |
+| `--record FILE` | Record this TUI session's debugging actions to FILE (JSON-RPC lines) |
+| `--replay FILE` | Replay a recording headless, printing a transcript (no program argument) |
+| `--replay-tui FILE` | Replay a recording inside the TUI at the recorded pace, so you can watch it |
+| `--replay-quiet` | With `--replay-tui`: no per-action toasts (errors and the final summary still show) |
+| `--timing` | With `--replay`: reproduce the recorded pacing (`--replay-tui` always does) |
+| `--replay-interval S` | With `--replay`/`--replay-tui`: fixed S-second delay before each action instead of the recorded gaps |
+| `--replay-timeout S` | With `--replay`/`--replay-tui`: per-action stop-wait timeout (default 30) |
+| `--examine-log DEST` | With --run: write each Ctrl-\ / SIGUSR2 stack snapshot to DEST (- = stdout; repeatable) |
 
 ## Configuration
 
@@ -1849,6 +1914,28 @@ fires as expected.
 
 MIT
 
+## Acknowledgments
+
+Thank you:
+
+- Will McGugan for the amazing `textual` module.
+`tdb` would be a pale shadow of itself had I used any other TUI framework.
+Fantastic work, Will.
+
+- Microsoft for the Debug Adapter Protocol (DAP) and releasing
+its implementation in `debugpy` and the Python Debugger extension for Visual Studio Code
+as open source.
+
+- Anthropic, for providing access to Claude Code through the
+[Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) program.
+`tdb` was made almost entirely with Claude Code.
+
+- OpenAI, for providing access to Codex through the
+[Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+
+This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
+Python debugger.
+
 
 ## Known Problems
 

{textual_debugger-0.2.10 → textual_debugger-0.2.12}/pyproject.toml

@@ -27,7 +27,7 @@
       "pygments>=2.17.0",
       "fastapi>=0.115.0",
       "uvicorn>=0.30.0",
-      "mcp>=1.28.0,<2.0.0",
+      "mcp>=2.0.0,<3.0.0",
 ]
 
   # extras needed to run the examples and tests
@@ -60,7 +60,7 @@
   include = ["tdb", "tdb.*"]
 
   [tool.setuptools.package-data]
-  tdb = ["README.md", "adapters/perl/helpers.pl", "adapters/perl/Devel/TdbRemote.pm", "adapters/perl/Devel/TdbCompile.pm", "adapters/bash/tdb_harness.sh", "adapters/powershell/tdb_launch.ps1", "rust_concurrency/probes/gdb_script.py", "rust_concurrency/probes/lldb_script.py"]
+  tdb = ["README.md", "adapters/perl/helpers.pl", "adapters/perl/padwalker_src/PadWalker.pm", "adapters/perl/padwalker_src/PadWalker.xs", "adapters/perl/padwalker_src/Makefile.PL", "adapters/perl/Devel/TdbRemote.pm", "adapters/perl/Devel/TdbCompile.pm", "adapters/bash/tdb_harness.sh", "adapters/powershell/tdb_launch.ps1", "rust_concurrency/probes/gdb_script.py", "rust_concurrency/probes/lldb_script.py"]
 
   [tool.pytest.ini_options]
   testpaths = ["tests"]