docs: weekly architecture docs refresh (1)

[enyst]

This PR refreshes the weekly SDK architecture documentation under sdk/arch, based on HEAD of the upstream repositories.

Updated pages

• sdk/arch/events.mdx

  • Added a new section: "Event Stream Subscription Mechanism"
    • Documents PubSub subscription model and initial state emission (source: software-agent-sdk/openhands-agent-server/openhands/agent_server/pub_sub.py; event_service.subscribe_to_events)
    • Describes WebSocket endpoint /sockets/events/{conversation_id} including auth and resend_all playback (source: openhands-agent-server/openhands/agent_server/sockets.py)
    • Lists HTTP Event APIs: search, count, get, batch, send message (source: openhands-agent-server/openhands/agent_server/event_router.py)
    • Provides a real-world example: intercept headless run, inject instructions, resume (sources: observation and conversation state event classes under openhands-sdk)
    • Includes a Mermaid sequence diagram for the subscription/emit path
    • Appends Last updated timestamp and source commits

• sdk/arch/llm.mdx

  • Documented retry listener/telemetry changes introduced this week:
    • RetryListener now includes the exception: Callable[[int, int, BaseException | None], None] and LLM wraps it to call telemetry.on_error (sources: openhands-sdk/openhands/sdk/llm/utils/retry_mixin.py; openhands-sdk/openhands/sdk/llm/llm.py; openhands-sdk/openhands/sdk/llm/utils/telemetry.py)
  • Clarified Responses API detection patterns with explicit entries ("gpt-5", "codex-mini-latest") (source: openhands-sdk/openhands/sdk/llm/utils/model_features.py)
  • Appended Last updated and Source commit

Audit summary

• Compared docs against latest code in:
  • software-agent-sdk@93d405c (HEAD of main)
  • 9b57a0b (HEAD of main)
• Prioritized pages required by guidelines: events.mdx and llm.mdx needed updates; other pages (overview, agent, conversation, tool-system, workspace, agent-server, condenser, security) appear in sync with code for this cycle.

Cited sources (inline in pages)

• software-agent-sdk/openhands-agent-server/openhands/agent_server/pub_sub.py
• software-agent-sdk/openhands-agent-server/openhands/agent_server/event_service.py
• software-agent-sdk/openhands-agent-server/openhands/agent_server/sockets.py
• software-agent-sdk/openhands-agent-server/openhands/agent_server/event_router.py
• software-agent-sdk/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py
• software-agent-sdk/openhands-sdk/openhands/sdk/event/conversation_state.py
• software-agent-sdk/openhands-sdk/openhands/sdk/llm/llm.py
• software-agent-sdk/openhands-sdk/openhands/sdk/llm/utils/retry_mixin.py
• software-agent-sdk/openhands-sdk/openhands/sdk/llm/utils/telemetry.py
• software-agent-sdk/openhands-sdk/openhands/sdk/llm/utils/model_features.py

Checks

• Followed docs/.openhands/microagents/sdk-guidelines.md for structure and length; diagrams use Mermaid with consistent styling.
• Kept changes limited to architecture docs under sdk/arch.
• CI: no code blocks syncing affected by these edits; pre-commit hooks not configured in this repo, so none to run.

@enyst can click here to continue refining the PR