feat: decision recording and state machine visualization (#513)

[cybr-wisp]

Description

Right now there's no way to see what decisions an agent considered at each step -> you only see what it did, not what it could have done. This PR adds that visibility.

The core idea: after the policy picks an action, we now record a DecisionEvent that captures the chosen action, the alternatives that were available but not taken, and the current state machine state. This goes into both the agent's belief and SharedMemory so other agents (like a future critic from #512) can subscribe to it.

On top of that, there's a StateMachineViewer that reads these decision events and generates a standalone HTML page showing the state machine graph with taken transitions (solid green), skipped alternatives (dashed gray), and a step-by-step decision history table.

What changed:

• New DecisionEvent in events.py with chosen, alternatives, and state fields
• BaseAgent.async_run now emits a decision event after each action selection
• New sherpa_ai/visualization/ package with the StateMachineViewer
• 11 unit tests covering event creation, belief integration, graph extraction, and HTML rendering

Usage:

from sherpa_ai.visualization import StateMachineViewer
viewer = StateMachineViewer(belief=agent.belief)
viewer.render("trajectory.html")

All 11 new tests pass, existing state machine and shared memory tests unaffected.

Type of change

• New feature (non-breaking change that adds functionality)

Related issues

Closes #513

Checklists

Development

• The Pull Request is small and focused on one topic
• Lint rules pass locally (make format && make lint)
• The code changed/added as part of this pull request has been covered with tests
• All tests related to the changed code pass in development (make test)
• The changes generate no new warnings (or explain any new warnings and why they're ok)
• Commit messages are detailed
• Changed code is self-explanatory and/or I added comments
• I updated the documentation (docstrings, /docs)

Code review

• This pull request has a descriptive title and information useful to a reviewer
• I have performed a self-review of my code
• Issue from task tracker has a link to this pull request

[cybr-wisp]

Fixed the one failing test: test_chat_based_policy_with_agent expected 4 internal events but the new decision recording adds 2 DecisionEvents (one per action selection step), so updated the assertion to 6. CI should be green now.