refactor(agents): migrate chat to hub (#1102)

[kovtcharov-amd]

Why this matters

ChatAgent — the flagship conversational agent powering gaia chat (and gaia chat --ui) under its chat, doc, and file profiles — was the last family of registry builtins still hardcoded inside the core framework wheel. It now ships as the standalone gaia-agent-chat wheel under hub/agents/python/chat/, with chat/doc/file registered as three gaia.agent entry points that the registry discovers automatically. The core wheel no longer hardcodes them, so the chat family versions independently like every other migrated agent. gaia chat resolves the agent through the registry and fails loudly with an install hint if the wheel is absent (mirroring how #1446 made gaia browse/gaia analyze resolve). All three profiles, their full+lite model tiers (via registry.build_model_tiers), and their per-profile prompt/tool wiring are preserved exactly.

Continues the #1102 Agent Hub restructure after connectors-demo (#1442) and analyst/browser (#1446). The shared FileToolsMixin (directory monitoring) stays framework-side — promoted to gaia.agents.tools.file_monitor_tools — since tool mixins are framework code (#1396).

Test plan

• python util/lint.py --all — black/isort clean (the only pylint hit, os.geteuid in lemonade_installer.py, is a pre-existing Windows-only false positive; mypy is warning-only)
• pytest tests/unit/agents/test_registry.py tests/unit/test_agents_split.py tests/unit/cli/test_cli_smoke.py — registry + split green; the 4 cli_smoke gaia-code/gaia-emr console-script hits are pre-existing shared-env pollution (verified passing on the base checkout), unrelated to chat
• pip install -e hub/agents/python/chat && pytest hub/agents/python/chat/tests/ — 7 passed (registration shapes for chat/doc/file, lazy re-exports, discovery, installed: namespacing)
• pytest across the chat-touched framework suites (chat agent, integration, system-prompt budget, browser tools, multi-device, required-connectors, registry factory, chat-UI helpers) — 182 passed with the wheel installed; all skip cleanly via importorskip in a framework-only env
• Registry discovery lists chat/doc/file as source=installed with installed:chat namespace; builder/email remain the only resident builtins
• CI: the Chat Agent Tests workflow installs the wheel and runs both the package smoke tests and the framework session/RAG/path-validation suites

[github-actions]

Code Review — refactor(agents): migrate chat to hub (#1102)

Verdict up front: Approve with suggestions. This is a clean, well-tested lift of the ChatAgent family (chat/doc/file) out of the core wheel into the standalone gaia-agent-chat package, faithfully mirroring the analyst/browser migration (#1446). No blocking issues. Two small framework-side staleness items and the doc import examples are the only follow-ups worth tracking.

Summary

ChatAgent now ships as three gaia.agent entry points discovered by the registry, the core wheel drops the hardcoded builtins, and gaia chat fails loudly with an actionable install hint when the wheel is absent. The model tiers, per-profile wiring, consumes_mcp_servers guard, and installed:chat namespacing are all preserved, and the FileToolsMixin (directory monitoring) was correctly promoted to gaia.agents.tools so framework code (DocumentQAAgent) no longer reaches into the chat package. Test migration is thorough — every chat-touching suite gained an importorskip("gaia_agent_chat") so a framework-only env skips cleanly rather than erroring.

Issues Found

🟢 Stale FRAMEWORK_PATHS entry — chat frames no longer filtered from user errors (src/gaia/agents/base/errors.py:21)

format_user_error filters framework frames out of user-facing tracebacks using these path substrings. After the move, "gaia/agents/chat" matches nothing (the dir is gone) and the new location gaia_agent_chat isn't listed — so an exception raised inside chat-agent code now surfaces as "user code" in error output. Note "gaia/agents/code" on the next line carries the identical staleness from the code migration, so this is shared #1102 debt rather than something this PR introduced. Worth repointing in the same pass:

    "gaia/agents/base",
    "gaia/agents/blender",
    "gaia_agent_chat",
    "gaia/agents/code",

(or, more robustly for the whole hub effort, also filter hub/agents/python/.)

🟢 Stale source-path reference in docstring (src/gaia/mcp/mixin.py:28)

The docstring points at src/gaia/agents/chat/agent.py, which now lives at hub/agents/python/chat/gaia_agent_chat/agent.py. Trivial, but it'll mislead the next reader who greps for it.

🟢 Doc import examples now broken (~20 files under docs/)

docs/sdk/agents/specialized.mdx, docs/spec/chat-agent.mdx, docs/playbooks/chat-agent/*, docs/sdk/sdks/rag.mdx, and others still show from gaia.agents.chat.agent import ChatAgent (and gaia.agents.chat.tools...) as runnable examples that no longer resolve. CLAUDE.md treats doc accuracy as mandatory, but this mirrors the analyst/browser/code migrations' existing doc debt, so it's reasonable to land this PR and sweep all hub-migrated import paths in one follow-up rather than block here. Flagging so it gets tracked, not as a merge gate.

Strengths

• Fail-loudly done right. The CLI ImportError → RuntimeError translation (src/gaia/cli.py) names what failed, exactly what to run (pip install gaia-agent-chat / amd-gaia[agents]), and the next step — textbook CLAUDE.md "actionable error," no silent fallback.
• Framework→chat dependency severed cleanly. Promoting FileToolsMixin to gaia.agents.tools.file_monitor_tools and repointing DocumentQAAgent means the core wheel no longer imports the chat package — the actual point of the migration, and it holds.
• The consumes_mcp_servers guard survived the move intact, with the package smoke test (test_build_chat_registration_shape) asserting it, so the feat(connectors): bind MCP connectors to specific agents (per-agent activation) #1005 activation-filter contract stays enforced from the new home.
• Test discipline. importorskip everywhere chat is touched, _register_builtin_agents() → discover() swapped where chat is now entry-point-discovered, and the reserved-id trojan test correctly re-pointed to builder now that chat is no longer reserved.

Verdict

Approve with suggestions. Nothing blocks merge. The two framework-side staleness nits are quick same-PR cleanups; the doc sweep is fair to defer as shared #1102 follow-up. Nice, faithful continuation of the hub restructure.

[github-actions]

🟡 tests/verify_path_validator.py:16 and tests/verify_shell_security.py:7 — bare imports with no guard

Every other file changed in this PR wraps gaia_agent_chat imports in pytest.importorskip or a try/except. These two standalone scripts can't use importorskip, but they get no guard at all:

# verify_path_validator.py line 16
from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig

Running either script in a framework-only environment now throws a bare ModuleNotFoundError instead of a helpful message. Before this PR, both worked out of the box.

try:
    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
except ImportError:
    raise SystemExit(
        "gaia-agent-chat is not installed — run: pip install gaia-agent-chat"
    )

Same fix applies to verify_shell_security.py:7. The rest of the migration looks correct.

[github-actions]

🟡 agent_loop.py:388 — ImportError from the missing chat wheel is swallowed silently

When gaia-agent-chat isn't installed, from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig at line 333 raises ModuleNotFoundError. The bare except Exception at line 388 catches it, logs "AgentLoop tick execution failed: No module named 'gaia_agent_chat'", and moves on — the user sees no install instruction.

cli.py wraps the same import with a try/except ImportError that raises a RuntimeError with the actionable message "Install it with pip install gaia-agent-chat". The Agent UI path should do the same:

            try:
                from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
            except ImportError as e:
                raise RuntimeError(
                    "The chat agent is not installed. "
                    'Run `pip install gaia-agent-chat` (or `pip install "amd-gaia[agents]"`), '
                    "then restart the server."
                ) from e

Same gap exists in the two lazy-import sites in _chat_helpers.py (_get_chat_response and _stream_chat_response) — those would surface as opaque 500 errors to the Agent UI instead of the helpful message the CLI shows.