[Audit v2 #351] Pydantic-validate WebSocket event payloads

[dsarno]

Summary

Closes the audit-v2 #7 finding from #343: WebSocket event payloads are now Pydantic-validated before they touch typed Session fields.

_handle_event previously did event_data.get(...) blind assignment — HandshakeMessage and CommandResponse were validated, but the three plugin-emitted state events (scene_changed, play_state_changed, readiness_changed) weren't. A malformed plugin event (or a hijacked WS via the surface #345 / #346 covered) put non-string values straight into Session.current_scene / play_state / readiness, which then shipped to MCP clients verbatim through Session.to_dict().

Fix

• New Pydantic models in src/godot_ai/protocol/envelope.py: SceneChangedEvent, PlayStateChangedEvent, ReadinessChangedEvent. Each carries one typed string field; defaults match the old .get(default) shape so a missing key still falls through to the same safe value the caller had been assigning.
• _handle_event runs each known event payload through model_validate() inside a try block. On ValidationError the event is dropped with a structured warning log naming the event type + session prefix — the typed Session field stays at its current value rather than being corrupted.
• Unknown event types remain silently ignored (forward-compat for future plugin versions).

Diff is small: +140 / −10 across the three files.

Test plan

• ruff check src/ tests/ — clean
• ruff format --check on touched files — clean
• pytest -q — 872 passed (5 new in TestEventValidation)
• script/ci-check-gdscript — All GDScript files OK
• New regression tests (tests/integration/test_websocket.py::TestEventValidation):
  • test_scene_changed_with_non_string_payload_is_dropped — sends {"current_scene": 12345}, asserts the typed field is unchanged + the warning was logged
  • test_play_state_changed_with_non_string_payload_is_dropped — sends a list payload
  • test_readiness_changed_with_non_string_payload_is_dropped — sends a nested dict
  • test_unknown_event_type_is_silently_ignored — forward-compat: unknown event names don't raise or mutate state
  • test_valid_event_after_malformed_one_still_applies — recovery: a valid event after a dropped one still updates the typed field on the same connection
• Existing TestEvents (3 tests covering the happy path) still passes
• Live editor test_run skipped — pure Python transport-layer change, no GDScript or handler edits

Deviations from "Fix shape"

None. The issue called for "add SceneChangedEvent, PlayStateChangedEvent, ReadinessChangedEvent Pydantic models in protocol/envelope.py; validate in _handle_event." That's the diff.

Cross-references

Closes #351
Umbrella: #343 (next reliability sweep — adjacent to #345 / #346 / #349 transport-hardening landings)

https://claude.ai/code/session_01ERwAhFK6CEZLRigwK1iC2k

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR addresses audit-v2 finding #7 (#351) by ensuring plugin-emitted WebSocket state event payloads are Pydantic-validated before mutating typed Session fields, preventing malformed event data from being propagated to MCP clients via Session.to_dict().

Changes:

• Added Pydantic models for scene_changed, play_state_changed, and readiness_changed event payloads in protocol/envelope.py.
• Updated GodotWebSocketServer._handle_event() to validate known event payloads with model_validate(), dropping malformed events with a warning log on ValidationError.
• Added integration tests covering malformed payload dropping, forward-compatible ignoring of unknown event types, and recovery (valid event after malformed).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/godot_ai/protocol/envelope.py	Introduces typed Pydantic models for plugin state event payloads with safe defaults.
src/godot_ai/transport/websocket.py	Validates known event payloads before mutating Session state; logs and drops malformed payloads.
tests/integration/test_websocket.py	Adds regression tests ensuring malformed events are dropped, unknown events are ignored, and recovery works.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[dsarno]

Post-PR shepherding complete — ready for merge

All four required signals green on SHA 5f37ea5:

• ✅ CI: 15/15 checks succeeded (Python 3.11+3.13 / Linux+macOS+Windows, Release smoke ×3 OS, Godot tests ×3 OS, Game capture smoke ×3 OS, plus Prepare/Agent/Upload/Cleanup)
• ✅ Copilot review: 0 comments generated (3/3 files reviewed)
• ✅ /simplify (3 sub-agents — reuse, quality, efficiency): no actionable findings in scope. The only non-blocking efficiency note (logger.warning rate-limit under attack) is bounded in the realistic case by the plugin's _check_state_changes running in _process() (≤60Hz) and was deliberately deferred as out-of-scope per CLAUDE.md ("Don't add features… beyond what the task requires"). Filing as a follow-up issue if log spam becomes observed.
• ✅ /review: clean. Defaults preserve old event_data.get(default) semantics, try/except placement keeps unknown-event forward-compat working, validation parallels the existing HandshakeMessage / CommandResponse patterns. Codecov reports 100% coverage on modified lines.

No follow-up commits needed. Awaiting maintainer merge.

cc @dsarno

---

Generated by Claude Code