Watchtower DAP Windows Debugging

# Feature Specification: Watchtower DAP Windows Debugging **Feature Branch**: `001-dap-windows-debug` **Created**: 2025-10-17 **Status**: Draft **Input**: User description: "Windows-native MCP ⇄ DAP bridge enabling step-through debugging for C#, Node/TS, Python, and Dart." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Cross-Language Debugging Setup (Priority: P1) An AI Agent needs to debug a Node.js application running on Windows by setting breakpoints and stepping through code execution. **Why this priority**: This is the core functionality that addresses the primary problem - agents cannot debug programs on Windows. Without this capability, the feature provides no value. **Independent Test**: Can be fully tested by launching a Node.js application, setting a breakpoint, hitting the breakpoint, and stepping through code execution. This delivers the fundamental debugging capability. **Acceptance Scenarios**: 1. **Given** a Node.js application is running, **When** an agent sets a breakpoint at a specific line, **Then** the program pauses execution when reaching that line 2. **Given** execution is paused at a breakpoint, **When** the agent requests to step into a function, **Then** execution moves to the first line of that function --- ### User Story 2 - Multi-Language Project Debugging (Priority: P2) A developer is working on a project that uses multiple languages (Python for backend, Node/TS for frontend, C# for services) and needs to debug each component through a unified interface. **Why this priority**: Multi-language support expands the feature's utility beyond single-language scenarios, making it more valuable for real-world development workflows. **Independent Test**: Can be tested by debugging a Python service and a Node.js API in separate sessions, demonstrating that each language can be debugged independently through the same MCP interface. **Acceptance Scenarios**: 1. **Given** multiple language runtimes are available, **When** the agent debugs a Python script, **Then** breakpoints and stepping work correctly for Python-specific constructs 2. **Given** the agent is debugging a TypeScript application, **When** setting breakpoints in TypeScript files, **Then** the adapter correctly maps to compiled JavaScript when source maps are available --- ### User Story 3 - Remote Process Attachment (Priority: P3) An AI Agent needs to attach to an already running process to debug an issue that occurs in production or a long-running background service. **Why this priority**: Remote debugging capability enables debugging of running processes without restarting, which is crucial for troubleshooting live systems. **Independent Test**: Can be tested by launching a separate process, then using the MCP tools to attach to it and set breakpoints while it's running. **Acceptance Scenarios**: 1. **Given** a process is running on the same Windows machine, **When** the agent attaches to the process, **Then** breakpoints can be set and the process can be controlled 2. **Given** the agent is attached to a running process, **When** execution continues past a breakpoint, **Then** the process resumes normal operation --- ### Edge Cases - What happens when an adapter fails to initialize for a specific language? - How does system handle breakpoint placement in non-existent files or lines? - What occurs when debugging a program that crashes unexpectedly? - How does the system respond to requests to inspect variables that are out of scope? ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST expose MCP tools for setting breakpoints at specific line numbers and file paths - **FR-002**: System MUST provide step execution capabilities (step into, step over, step out) - **FR-003**: System MUST allow variable inspection and value retrieval when execution is paused - **FR-004**: System MUST enable expression evaluation in the current debug context - **FR-005**: System MUST support both launch (start new process) and attach (connect to running process) debugging modes - **FR-006**: System MUST handle at least the four target languages: C#, Node/TypeScript, Python, and Dart - **FR-007**: System MUST provide deterministic event polling for agents to receive debug state updates - **FR-008**: System MUST manage event buffers with pagination to prevent memory overflow - **FR-009**: System MUST validate breakpoint placement and provide feedback when breakpoints cannot be set - **FR-010**: System MUST redact environment variables and sensitive arguments from logging outputs ### Key Entities *(include if feature involves data)* - **Debug Session**: Represents an active debugging session with a target process, includes session ID, target information, and current state - **Breakpoint**: Represents a pause location in code, includes file path, line number, condition, and enabled/disabled state - **Variable**: Represents a variable in the debug context, includes name, type, value, and scope information - **Stack Frame**: Represents a location in the call stack, includes function name, file path, line number, and local variables - **Debug Event**: Represents a debugging event (breakpoint hit, exception, etc.), includes event type, timestamp, and associated data ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Agents can set breakpoints and hit them within 1 second (measures Time to First Break - TFFB) - **SC-002**: Individual stepping operations complete within 200ms (95th percentile - STEP_p95) - **SC-003**: Debugging sessions succeed on first attempt 95% of the time (Success Rate - SR) - **SC-004**: 90% of users report that the debugging interface meets their needs for basic debugging tasks (User Satisfaction) - **SC-005**: The system supports debugging of all four target languages without adapter failures on Windows 10/11 - **SC-006**: Event buffers handle 100+ events per second without data loss or significant latency - **SC-007**: Breakpoint verification occurs within 500ms of breakpoint setting - **SC-008**: Documentation enables successful setup and debugging within 15 minutes for new users