[Feature] Simplify and rationalize the agent module layout

[senamakel]

Summary

Refactor the src/openhuman/agent/ area into a much smaller, clearer structure. The current folder has too many files and overlapping responsibilities, which makes onboarding, debugging, and feature work slower than it should be.

Problem

The agent/ code has grown organically and now feels fragmented:

• Logic for planning/orchestration/prompting/runtime is split across many files and subfolders.
• Boundaries are hard to understand (what is core agent vs harness vs prompt assembly vs memory glue).
• Similar concepts are represented in multiple places, increasing drift and duplicate behavior.
• Small changes often require touching several files, raising review overhead and regression risk.

This hurts contributors and maintainers, especially when adding new agent roles or evolving orchestration.

Solution (optional)

Simplify with a deliberate module map and fewer top-level concepts:

• Define a compact target architecture (e.g. core, orchestration, prompts, memory-integration, types).
• Merge thin/overlapping files where separation adds little value.
• Keep only one obvious entrypoint for building/running agents.
• Keep orchestration and prompt construction discoverable and colocated with agent core types.
• Add module docs that explain ownership and call flow in 1-2 screens.

Do this incrementally to avoid a destabilizing big-bang rewrite.

Acceptance criteria

• Smaller surface area — src/openhuman/agent/ has materially fewer files/modules, with redundant layers removed.
• Clear ownership — each remaining module has a single responsibility and documented boundaries.
• Single mental model — contributors can answer “where to add X?” (new agent role, prompt logic, orchestration hook) without ambiguity.
• No behavior regression — existing agent flows continue to work (single-agent turns, orchestration paths, prompt loading, memory integration).
• Docs updated — architecture note and inline module docs reflect the new structure.

Related

• Prior taxonomy/orchestration alignment work: [Feature] First-class agent taxonomy on Agent/AgentBuilder; colocate plan, orchestrator, and prompt factories under agent/agent #478
• Any follow-up PRs should explicitly map old file ownership to new modules in the PR description.