Add bounded logical Z80 disassembly to shared MCP

2026-09-17 23:11:08 +03:00
parent 113d468c48
commit 958ad0ae0f
13 changed files with 103 additions and 16 deletions
@@ -280,13 +280,13 @@ Quick wins:
 ## Прочий backlog

 - [ ] **Довести MCP C-уровня до полного безопасного контракта.** Первый
-      stdio-адаптер с 27 инструментами использует общую sdbg-сессию и
+      stdio-адаптер с 28 инструментами использует общую sdbg-сессию и
      owner ID личных точек. Полный план и матрица всех 30 raw-возможностей —
      [mcp-convergence-plan.md](mcp-convergence-plan.md).
      control lease для DAP/MCP и cleanup точек по истечении heartbeat
      проверены живым прогоном. Привязка RPC к session/build/generation и
      экранные API, одиночный `press_key` и читающий список C-точек уже
-      добавлены. Далее очередь
+      добавлены; logical Z80 disassembly также проверен. Далее очередь
      строкового ввода, управляемые поля портов и мышь, затем доказанные
      watchpoints, запись typed values, disassemble_src и batch-загрузка
      точек. Raw `mame_mcp.py` с `-plugin mamebridge` не подключать к тому же
@@ -125,7 +125,7 @@ stdio MCP-адаптер C-уровня. Эксклюзивное владени
  проверяет сигнатуру entry и запускает session server. Закрытие DAP
  завершает только созданные им server/MAME, удаляет временный каталог и
  свой Unix socket (с проверкой inode, чтобы не удалить новый сеанс).
- `sdbg_mcp.py` предоставляет 27 инструментов через официальный MCP SDK
+- `sdbg_mcp.py` предоставляет 28 инструментов через официальный MCP SDK
  2.x поверх того же session server: статус, C-позиция, регистры, logical
  memory, переменные, события/логи, личные точки и команды исполнения.
  MCP-точки имеют owner ID и не могут удалить точки VS Code; при обычном
@@ -136,7 +136,7 @@ stdio MCP-адаптер C-уровня. Эксклюзивное владени
  шага после клавиши.
  Повторный запуск на том же фиксированном socket после прежнего stale-файла
  прошёл; после Stop путь удалён.
-  В автономном режиме доступны 29 инструментов: официальный MCP-клиент
+  В автономном режиме доступны 30 инструментов: официальный MCP-клиент
  запустил `hello`, ввёл `x` через публичный `press_key` во время `getchar()`
  и остановился на следующей C-строке. Остальные raw-возможности ввода
  перечислены в [матрице](mcp-capability-matrix.md).
@@ -295,6 +295,7 @@ commit `b0c4527c2edb1ee177fd09b3c412b65b385bf35b`:
 | Автономный MCP, 2026-09-17 | `start_session` ответил за 5–7 мс, затем официальный MCP-клиент дождался DSS→`hello.exe`→`main`; DAP attach увидел тот же PC, disconnect не завершил MAME. Повторный start отклонён, stop удалил socket и процесс MAME. Codex/Claude UI ещё не проверены |
 | Публичный MCP `press_key`, 2026-09-17 | В автономном видимом MAME официальный MCP-клиент поставил C-точку перед `getchar()`, продолжил `hello`, ввёл `x` через `press_key` и остановился на следующей строке 63. В автономном режиме доступны 28 инструментов; строковый ввод и мышь остаются в плане |
 | Список C-точек MCP, 2026-09-17 | В автономном видимом MAME MCP увидел собственную точку перед `getchar()` с owner и адресом; `list_breakpoints` также отдаёт guard-условие банка из bridge, если оно есть. Всего 29 автономных инструментов; вручную созданные debugger-точки пока не перечисляются |
+| Logical Z80 disassembly MCP, 2026-09-17 | Через официальный MCP-клиент в видимом MAME прочитаны инструкции `main` с `0x8224` (`call $852C`); байты памяти до/после совпали. Адрес/длина ограничены, возвращаются bank_pages и generation. Всего 30 автономных инструментов; raw program disassembly ещё не поддержано |
 | F10 через `getchar()`, 2026-09-15 | Асинхронный `next` ответил за 21,49 мс; при ручном `x` в окне MAME `hello.c:62` → `:63`, возврат `DE.low=0x78`; обе клавиатуры включены в изолированном cfg |
 | VS Code TaskProvider Build, 2026-09-15 | Одиннадцать Node-проверок: выбор Makefile рядом с пакетом/в `build/`, команда make с Python shim, SDCC matcher, успешный и неуспешный код задачи, pyenv вне workspace; реальный make в `tests/hello` прошёл, VS Code показал Build → MAME/DSS → `main` |
 | Ошибочная debug-сборка, 2026-09-15 | Изолированный `fault.c` вернул код 2 от make, `file:1: error 20` сохранился, Python traceback удалён; MAME не участвует |
@@ -536,7 +536,7 @@ console_log и загрузка набора точек. Возвращать bu
 в арбитраж, а не обходят его.

 Первый stdio MCP-адаптер уже работает через общий session server и отдаёт
-27 проверенных C-инструментов (29 при автономном start/stop). У личных MCP-точек owner ID; удаление чужой
+28 проверенных C-инструментов (30 при автономном start/stop). У личных MCP-точек owner ID; удаление чужой
 DAP-точки отклоняется. Совместный живой прогон подтвердил чтение состояния,
 точки и последующее срабатывание DAP-точки. Добавлен control lease для
 команд CPU и ввода; передача MCP→DAP и cleanup точки владельца без heartbeat
@@ -25,7 +25,7 @@
 | `resume` | `continue_execution` | Проверено с control lease и DAP-событиями |
 | `pause` | `pause_execution` | Проверено с control lease |
 | `status` | `session_status`, `where` | Проверено; C-статус содержит session/build/generation |
-| `disassemble` | — | Нужен явный logical/raw адрес и банк; строковый debugger pass-through не используется |
+| `disassemble` | `disassemble_logical` | Проверено на `hello`: 1..256 байт текущей logical Z80 памяти при stop, ответ содержит bank_pages/generation. Raw program 0..0x3ffff вне текущего окна ещё не дизассемблируется |
 | `screenshot` | `screenshot` | Проверено на выполняющемся `hello`; только каталог сессии, до 8 МиБ, при stop кадр помечается stale |
 | `read_screen_pixels` | `read_screen_pixels` | Проверено; до 8192 pen16 пикселей, кадр/время/stale в ответе |
 | `list_ports` | `list_ports` | Проверено; структурированные tag/маска/имя, предел 512 портов и 4096 полей |
@@ -44,7 +44,8 @@
 с `--waitkey --emulated-key --screen-mcp-python` проверяет экран работающего
 `hello` во время `getchar()` и последующий ввод. Автономный
 `run_managed_mcp_probe.py` через официальный MCP-клиент проверяет
-`list_breakpoints`, `press_key("x")` и остановку на строке после `getchar()`.
+`disassemble_logical` в `main`, `list_breakpoints`, `press_key("x")` и
+остановку на строке после `getchar()`.
 `run_raw_mcp_hello_probe.py`
 проверяет отдельный raw plugin на том же приложении. Несколько процессов MAME
 с MCP одновременно не проверялись.
@@ -11,8 +11,8 @@
 `MAME.HT/plugins/mamebridge` вместе с `src/mame_mcp.py` публикует 30
 raw-инструментов. Удалённый на этапе А `src/mame_bridge.lua` использовал тот
 же Python frontend, но обрабатывал только 16 команд и не отвечал при hard-stop.
-`toolchain/sdbg_mcp.py` публикует 27 C-инструментов через общую с DAP сессию
-(29 в автономном режиме с командами start/stop).
+`toolchain/sdbg_mcp.py` публикует 28 C-инструментов через общую с DAP сессию
+(30 в автономном режиме с командами start/stop).
 **Цель — покрыть возможности всех 30 raw-инструментов в C-сессии, а не
 механически скопировать имена и небезопасную семантику.** Полный raw MCP
 остаётся отдельным режимом для задач без C-пакета и других машин MAME.
@@ -152,6 +152,12 @@ C-строку. Очередь строки, другие имена физич
 владельцев, адреса и полученные от MAME условия банковской страницы;
 удалять чужие точки он не позволяет. Живой MCP-прогон увидел личную точку
 перед `getchar()`. Точки, вручную созданные в родном debugger, пока вне списка.
+Дизассемблирование текущего logical Z80 окна добавлено как
+`disassemble_logical`: фиксированная команда MAME с числовыми аргументами,
+пределом 256 байт и изолированным временным файлом; ответ включает
+`bank_pages` и generation. Живой MCP-прогон получил инструкции `main` с
+адреса `0x8224`; байты до и после операции совпали. Raw program вне
+текущего отображения остаётся открытым.

 ## Г. Сделать запуск пригодным для Codex и Claude без VS Code

@@ -74,7 +74,8 @@ MCP-сервером MAME и удаляет socket. Закрытие самог
 непосредственно из UI Codex и Claude ещё не проверено.

 Доступные инструменты: `session_status`, `where`, `read_registers`,
-`read_memory`, `read_program_memory`, `list_ports`, `list_shares`, `read_share`, `read_vram`,
+`read_memory`, `read_program_memory`, `disassemble_logical`, `list_ports`,
+`list_shares`, `read_share`, `read_vram`,
 `read_screen_pixels`, `screenshot`, `press_key`, `list_variables`, `read_variable`, `recent_events`,
 `mame_console_tail`, `set_line_breakpoint`, `set_function_breakpoint`,
 `list_breakpoints`, `clear_breakpoint`, `clear_my_breakpoints`,
@@ -86,7 +87,7 @@ MCP-сервером MAME и удаляет socket. Закрытие самог
 `recent_events` с курсором `last`. Логи `SDBG_LOG` приходят как события
 `output`; журнал ограничен 1024 событиями и сообщает `first`/`last`/`lost`.

-Число 27 в attach-режиме (29 в автономном с `start_session`/`stop_session`)
+Число 28 в attach-режиме (30 в автономном с `start_session`/`stop_session`)
 не означает полного переноса более нового `-plugin mamebridge`:
 его `src/mame_mcp.py` публикует 30 raw-инструментов, ориентированных на
 машину MAME. Здесь инструменты сгруппированы по операциям C-сессии, а
@@ -98,7 +99,7 @@ MCP-сервером MAME и удаляет socket. Закрытие самог
 | `setmem`, raw `debugger_command`, watchpoints | Проверка прав, банка, диапазона и согласование с DAP-точками; произвольная debugger-команда может нарушить состояние сессии |
 | VRAM/shares, screen pixels, screenshot | Реализованы через общий `sdbgbridge`; точный tag, пределы 4096 байт/8192 пикселя, PNG только в каталоге сессии |
 | Клавиатура, мышь, type/press | `list_ports` и одиночный `press_key` уже перенесены; набор строки, произвольные поля портов и мышь требуют отдельного контракта ввода |
-| Raw disassembly | Связать адрес/банк с проверенной C-картой; не выдавать физический адрес за logical |
+| Raw disassembly | Текущее окно logical Z80 уже доступно через `disassemble_logical`; адреса raw program вне отображённого банка требуют отдельного безопасного режима |

 Это следующий этап, а не запрет на функции raw MCP. Нельзя просто загрузить
 `mamebridge` рядом с `sdbgbridge`: два независимых обработчика начнут менять
@@ -120,6 +121,14 @@ generation и страницы банков; диапазон не может п
 и битовые маски; результат ограничен 512 портами/4096 полями и помечает
 `truncated`, если достигнут предел. Оба инструмента проверены в живом MAME.

+`disassemble_logical` принимает числовой адрес (десятичный или `0xHEX`) и
+длину 1..256 байт в текущем logical Z80 пространстве, только при stop.
+Сервер сверяет загруженный C-код, вызывает фиксированную читающую команду
+MAME `dasm` во временном каталоге сессии и возвращает текст, generation и
+текущие `bank_pages`. Это не произвольная debugger-команда. Дизассемблирование
+raw program вне текущих банков пока не поддержано. На живом `hello` ответ
+начинался с адреса `8224`, соответствующего `main`.
+
 `list_shares` возвращает точные tag/размеры. `read_share` требует полный tag,
 `read_vram` выбирает единственный VRAM share; обе операции читают до 4096
 байт без Z80 bank mapping. `read_screen_pixels` возвращает pen16-значения
@@ -175,7 +175,7 @@ launcher задаёт этому процессу `SDL_NO_SIGNAL_HANDLERS=1`, е
 фиксированный `"socket": "/tmp/sprinter-sdbg-hello.sock"` и подключите
 `toolchain/sdbg_mcp.py` после остановки в `main`. MCP использует тот же
 session server; его личные точки не заменяют точки VS Code. Порядок запуска,
-27 доступных инструментов и ограничения совместного управления описаны в
+28 доступных инструментов и ограничения совместного управления описаны в
 [руководстве по MCP](sdbg-mcp.md).

 Команда палитры `Sprinter: Build Active Project` собирает приложение по