docs: Architecture Overview for Agent SDK (Mermaid diagrams + subsystem guide)

[enyst]

Closes #1

Summary

• Adds docs/architecture-overview.md with:
  • GitHub-compatible Mermaid flow and class diagrams
  • Subsystem descriptions (Agents/Conversation, LLM, Tool system, Tools package)
  • Key data structures and invariants
  • Linus-style review section (core judgment, insights, risks, improvements)
  • How to run locally and file pointers

Why

• We initially drafted this internally; this PR updates it against current upstream main and moves it into repo docs so contributors can quickly orient themselves.

Scope

• Documentation only. No code changes.

Validation

• Rendered locally; Mermaid blocks use simple, GitHub-compatible syntax.

Notes

• FinishTool is documented as a built-in core tool; environment-interacting tools live under openhands/tools.

Follow-ups (future PRs)

• Add tests for CodeActAgent.init_state in-place mutation and for Conversation.run iteration limit with concurrent send_message (both have TODOs in code).

Co-authored-by: openhands openhands@all-hands.dev

@enyst can click here to continue refining the PR

[xingyaoww]

@enyst i was actually wondering if we can save this prompt somewhere and create a github action that use OpenHands AI to runs this periodically and put together PRs :)

[enyst]

Yes! I was doing that here, for example:

• feat: add cron agents (architecture audit + OpenAPI drift) with manual dispatch enyst/playground#96

We could keep it for later. Although I think we also need to set up an initial version, on which the cron-agent will run. Maybe when we hash it out better.