Added Debugging functionality #22
Conversation
Implements a debug capture mechanism to record events during agent execution. This includes adding new data models for debug events and responses, creating API endpoints for toggling debug mode, retrieving debug information, and clearing debug events. The captured events provide insights into the communication flow between the agent, the LLM, tools, and the MCP. It introduces a session ID to track events related to a single request. This enhances debugging and troubleshooting capabilities.
Improves the debug capture functionality by adding color identifiers to important attributes for better readability in the UI. Adds a fullscreen mode for debug events to display complete data without truncation, improving the debugging experience. Tools are now disabled by default to prevent unexpected behavior, and can be enabled through the UI
Removes an unnecessary print statement from the tool state setting logic. This improves code cleanliness and avoids unnecessary output during tool state management.
There was a problem hiding this comment.
Pull Request Overview
This PR adds a full-featured debugging system, including models, capture infrastructure, API endpoints, and UI integration for viewing and toggling debug events.
- Introduces
DebugEvent,DebugRequest,DebugResponseinsrc/api/models.py - Implements singleton
DebugCapturewith safe serialization insrc/core/debug_capture.py - Adds
/api/debug,/api/debug/toggle, andDELETE /api/debugroutes and session-ID tracking insrc/api/routes.py - Integrates debug capture into LLM, MCP, and tools layers and adds a debug panel and fullscreen view in the UI (
src/ui/index.html,src/ui/chat.ts)
Reviewed Changes
Copilot reviewed 16 out of 17 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/api/models.py | Added Pydantic models for debug events and toggle |
| src/api/routes.py | Added routes for retrieving, toggling, and clearing debug info; set session IDs |
| src/core/debug_capture.py | Implemented DebugCapture, safe_serialize, and event types |
| src/core/init.py | Added get_debug_capture helper |
| src/tools/init.py | Changed default tool enabled state to False |
| src/core/mcp/session.py | Hooked MCP calls/results into debug capture |
| src/core/llm/client.py | Hooked LLM requests/responses into debug capture |
| src/core/llm/chat.py | Hooked tool calls/results/errors into debug capture |
| src/ui/index.html | Added debug panel and fullscreen overlay markup |
| src/ui/chat.ts | Integrated debug panel toggles, fetching, and rendering |
| tests/test_ui_tools_configuration.py | Added unit tests for tool-item CSS class logic |
| tests/test_ui_frontend.py | Added CSS existence tests for tool highlighting |
| tests/test_debug_capture.py | Comprehensive tests for DebugCapture |
| tests/test_debug_api.py | Tests for debug API endpoints |
| test_fullscreen.py | Script to generate debug events (not pytest-style) |
| test_color_scheme.py | Script demonstrating color scheme (not pytest-style) |
Comments suppressed due to low confidence (1)
src/core/mcp/session.py:71
- The new MCP debug capture calls (
capture_mcp_callandcapture_mcp_result) are not covered by existing tests. Consider adding unit tests to verify these hooks are invoked and data is serialized as expected.
if debug_capture:
| except Exception as e: | ||
| raise HTTPException(status_code=500, detail=f"Error toggling tool: {str(e)}") | ||
|
|
||
| @router.get("/debug", response_model=DebugResponse) |
There was a problem hiding this comment.
The debug endpoints are currently unprotected, allowing any client to view and clear debug data. Add Depends(get_api_key) to the /debug, /debug/toggle, and DELETE /debug routes to enforce authentication.
| @router.get("/debug", response_model=DebugResponse) | |
| @router.get("/debug", response_model=DebugResponse, dependencies=[Depends(get_api_key)]) |
| sortedTools.forEach(tool => { | ||
| const toolItem = document.createElement('div'); | ||
| toolItem.className = 'tool-item'; | ||
| toolItem.className = `tool-item ${tool.enabled ? 'enabled' : ''}`; |
There was a problem hiding this comment.
When enabled is false this produces "tool-item " (with a trailing space), which may not match selectors expecting exactly "tool-item". Consider using a conditional assignment to explicitly set either "tool-item" or "tool-item enabled", or call .trim() on the resulting string.
| toolItem.className = `tool-item ${tool.enabled ? 'enabled' : ''}`; | |
| toolItem.className = tool.enabled ? 'tool-item enabled' : 'tool-item'; |
| <span>Tools Configuration</span> | ||
| </div> | ||
| <div class="debug-toggle-container"> | ||
| <button class="debug-panel-toggle" id="debugPanelToggle" title="Toggle Debug Panel"> |
There was a problem hiding this comment.
The debug panel toggle button relies on a title attribute for context but lacks an explicit aria-label or role. Adding aria-label="Toggle Debug Panel" and role="button" will improve screen reader compatibility and keyboard navigation.
| <button class="debug-panel-toggle" id="debugPanelToggle" title="Toggle Debug Panel"> | |
| <button class="debug-panel-toggle" id="debugPanelToggle" title="Toggle Debug Panel" aria-label="Toggle Debug Panel" role="button"> |
| @@ -0,0 +1,101 @@ | |||
| #!/usr/bin/env python3 | |||
There was a problem hiding this comment.
The test_fullscreen.py script in the project root is not structured as pytest tests and will be auto-collected without assertions. Move it into the tests/ directory and convert it into proper pytest functions with assertions.
| @@ -0,0 +1,63 @@ | |||
| #!/usr/bin/env python3 | |||
There was a problem hiding this comment.
test_color_scheme.py is also placed at the root and contains only print statements. To be included in CI, convert it into pytest tests under tests/ with proper assertions or rename it to avoid pytest collection.
This pull request introduces a comprehensive debugging system to track and manage events across various components of the application. It includes changes to enable debug capture, serialize debug data safely, and integrate debugging features into the API, core logic, and UI. The most important changes are grouped into three themes: debugging infrastructure, API updates, and UI enhancements.
Debugging System Enhancements:
New Debug Models:
DebugEvent,DebugRequest, andDebugResponsemodels insrc/api/models.pyto represent and manage debug-related data, including event type, message, data, timestamp, and session ID.Debug Capture Implementation:
DebugCaptureclass insrc/core/debug_capture.pyto manage debug events, including methods for capturing tool calls, tool results, LLM requests/responses, and MCP interactions. This includes safe serialization of debug data with color-coded metadata for frontend display.API Routes for Debugging:
src/api/routes.pyfor retrieving debug info, toggling debug mode, and clearing debug events. These endpoints enable interaction with the debugging system via HTTP requests.Integration with Core Components:
LLM and MCP Debug Integration:
DebugCaptureinto LLM (src/core/llm/chat.py,src/core/llm/client.py) and MCP sessions (src/core/mcp/session.py) to capture requests, responses, and tool interactions. [1] [2] [3]Tool State Updates:
src/tools/__init__.pyto align with debugging requirements.UI Updates for Debugging:
src/ui/chat.tsto display debug events, toggle debug mode, and clear debug data. This includes a debug panel overlay and fullscreen view for detailed event inspection.