# Section 01: Protocol and Plugin Wiring

## Overview

This section adds the foundational wiring needed by the two new bridge tools (`scene_tree` and `node_ops`). It consists of three small, targeted changes:

1. Add two new timeout entries to `TOOL_TIMEOUTS` in the Python bridge protocol module.
2. Add an `undo_redo` variable to the GDScript server.
3. Wire the `EditorUndoRedoManager` reference from the plugin to the server.

These changes are prerequisites for sections 02-05. No new files are created -- only existing files are modified.

---

## Files to Modify

| File | Change |
|------|--------|
| `/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/bridge/protocol.py` | Add `scene_tree` and `node_ops` to `TOOL_TIMEOUTS` |
| `/Users/salvatorefarruggio/Desktop/godotiq/godot-addon/addons/godotiq/godotiq_server.gd` | Add `var undo_redo` instance variable |
| `/Users/salvatorefarruggio/Desktop/godotiq/godot-addon/addons/godotiq/godotiq_plugin.gd` | Wire `_server.undo_redo = get_undo_redo()` in `_enter_tree()` |

---

## Tests (Write First)

The protocol timeout changes are covered by extending the existing test class in `/Users/salvatorefarruggio/Desktop/godotiq/tests/test_bridge/test_protocol.py`. Add these tests to the `TestTimeouts` class:

```python
# In class TestTimeouts (tests/test_bridge/test_protocol.py):

def test_scene_tree_timeout(self) -> None:
    """scene_tree has a 5-second timeout configured."""
    assert get_timeout("scene_tree") == 5.0

def test_node_ops_timeout(self) -> None:
    """node_ops has a 10-second timeout configured."""
    assert get_timeout("node_ops") == 10.0
```

These tests verify that both new methods return their specific timeouts rather than the 5.0 default. The `scene_tree` test is technically redundant with the default (both are 5.0), but it documents the explicit intent of having the entry in `TOOL_TIMEOUTS` and will catch regressions if the default changes.

The existing `test_all_timeouts_positive` test will automatically cover the new entries once they are added to the dict.

The GDScript changes (`undo_redo` variable and plugin wiring) are not unit-testable from Python -- they are verified manually in the Godot editor and indirectly via the `node_ops` tool tests in later sections.

---

## Implementation Details

### 1. Add Timeouts to `TOOL_TIMEOUTS`

In `/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/bridge/protocol.py`, add two entries to the `TOOL_TIMEOUTS` dictionary:

```python
TOOL_TIMEOUTS: dict[str, float] = {
    "ping": 2.0,
    "screenshot": 30.0,
    "perf_snapshot": 5.0,
    "editor_context": 5.0,
    "run": 10.0,
    "stop": 5.0,
    "scene_tree": 5.0,
    "node_ops": 10.0,
}
```

The `scene_tree` tool gets 5 seconds -- it is a read-only tree walk that should complete quickly. The `node_ops` tool gets 10 seconds -- it performs batch mutations that may involve instantiating scenes and manipulating multiple nodes.

### 2. Add `undo_redo` Variable to Server

In `/Users/salvatorefarruggio/Desktop/godotiq/godot-addon/addons/godotiq/godotiq_server.gd`, add an untyped `undo_redo` variable alongside the existing `var debugger` declaration (currently at line 18):

```gdscript
var undo_redo  # untyped — set by godotiq_plugin.gd (EditorUndoRedoManager)
```

This variable will be used by the `_handle_node_ops()` handler (section 04) to create undoable actions via `EditorUndoRedoManager`. It is left untyped because GDScript `@tool` scripts loaded as resources cannot directly reference `EditorUndoRedoManager` without engine context.

### 3. Wire `undo_redo` in Plugin

In `/Users/salvatorefarruggio/Desktop/godotiq/godot-addon/addons/godotiq/godotiq_plugin.gd`, add the undo_redo wiring in `_enter_tree()` after the server and debugger are set up. The `get_undo_redo()` method is provided by `EditorPlugin` and returns the `EditorUndoRedoManager` instance.

Add this line after the existing debugger wiring (after `add_debugger_plugin(_debugger)`, currently at line 22), but before the autoload registration:

```gdscript
# 3. Wire undo/redo manager for node operations
_server.undo_redo = get_undo_redo()
```

The full `_enter_tree()` function should look like:

```gdscript
func _enter_tree() -> void:
	# 1. Create WebSocket server as child node
	_server = preload("res://addons/godotiq/godotiq_server.gd").new()
	add_child(_server)

	# 2. Create debugger plugin, wire cross-references, register it
	_debugger = preload("res://addons/godotiq/godotiq_debugger.gd").new()
	_debugger.server = _server
	_server.debugger = _debugger
	add_debugger_plugin(_debugger)

	# 3. Wire undo/redo manager for node operations
	_server.undo_redo = get_undo_redo()

	# 4. Register runtime autoload singleton
	add_autoload_singleton(AUTOLOAD_NAME, RUNTIME_PATH)
```

---

## Dependencies

- **No dependencies**: This is the first section and has no prerequisites.
- **Blocks**: Sections 02 (scene_tree GDScript), 03 (scene_tree Python), 04 (node_ops GDScript), and 05 (node_ops Python) all depend on this section being complete.

---

## Verification Checklist

1. Run the existing protocol tests plus the two new ones: `pytest tests/test_bridge/test_protocol.py -v`. All tests should pass, including `test_scene_tree_timeout`, `test_node_ops_timeout`, and `test_all_timeouts_positive`.
2. Verify `TOOL_TIMEOUTS` now has 8 entries (was 6).
3. Verify `godotiq_server.gd` has both `var debugger` and `var undo_redo` declarations.
4. Verify `godotiq_plugin.gd` `_enter_tree()` sets `_server.undo_redo = get_undo_redo()` before `add_autoload_singleton`.

---

## Implementation Notes

All three planned changes were implemented exactly as specified. 15/15 protocol tests pass.

Additionally, a pre-existing bug fix for request_id corruption in `godotiq_server.gd` was included in the commit (it was already in the working tree from a prior session). The fix adds a `request_id` field to `_pending_game_requests` entries and uses it instead of the composite key when sending responses/errors back to the Python client.
