refactor(agents): migrate connectors-demo to hub (#1102)

[kovtcharov-amd]

Why this matters

ConnectorsDemoAgent was the last registry builtin still living in src/gaia/agents/. It now ships as the standalone gaia-agent-connectors-demo wheel under hub/agents/python/, discovered via the gaia.agent entry point — so the core framework wheel no longer hardcodes it, and it versions independently like the other migrated agents. This is the first of the chat-family core wave for #1102; it proves the full end-to-end pattern (hub package + dedicated CI workflow + registry-tolerant framework tests) on the smallest agent before chat/analyst/browser/docqa/email follow.

Its namespaced id moves builtin:connectors-demo → installed:connectors-demo to match its installed source; the factory still stamps that id so the per-agent connector-activation filter (#1005) keeps matching grants.

Test plan

• python util/lint.py --agents — clean (connectors-demo now optional)
• pytest tests/unit/agents/test_registry.py tests/unit/test_agent_required_connectors.py tests/unit/connectors/test_formatting.py — green (framework-only, no builtin)
• pip install -e hub/agents/python/connectors-demo && pytest hub/agents/python/connectors-demo/tests/ — 20 passed (incl. entry-point discovery + namespaced-id match)
• black / isort / pylint -E — clean
• CI: new Connectors Demo Agent Tests workflow installs the wheel and runs its tests

[github-actions]

Summary

Clean, faithful migration that moves connectors-demo out of the core wheel and into the standalone gaia-agent-connectors-demo hub package, mirroring the established code/emr pattern. No security concerns, no breaking changes to end users (the agent still resolves under the same connectors-demo id via entry-point discovery). The one thing worth the author's attention: the new build_registration() re-wraps the factory and re-sets the namespaced id that the registry already applies for every entry-point agent — harmless (idempotent), but the accompanying comment is factually wrong and this PR is the explicit reference for the chat/analyst/browser/docqa/email wave that follows, so a misleading comment here will propagate.

Hygiene is thorough: removed from _RESERVED_BUILTIN_IDS and setup.py packages, the deleted built-in registration block replaced with a pointer comment, builtin: → installed: updated everywhere (incl. test_formatting.py), doc links repointed, and a dedicated CI workflow wired into test_gaia_cli.yml exactly like test_code_agent.yml.

Issues Found

🟡 Redundant factory wrap + incorrect comment (gaia_agent_connectors_demo/__init__.py:245-248, also :268)

The registry already does both of these for every entry-point agent. _load_entry_point_registration (src/gaia/agents/registry.py:915-923) runs:

namespaced_id = f"installed:{registration.id}"
registration = dataclasses.replace(
    registration,
    namespaced_agent_id=namespaced_id,
    source="installed",
    factory=_wrap_factory_with_namespaced_id(registration.factory, namespaced_id),
)

So the explicit _wrap_factory_with_namespaced_id(_factory, ...) becomes an idempotent double-wrap, and namespaced_agent_id="installed:connectors-demo" in the AgentRegistration is overwritten by dataclasses.replace. The sibling emr agent relies on exactly this and does not wrap (hub/agents/python/emr/gaia_agent_emr/__init__.py).

The comment "the registry's create_agent does not inject it for entry-point agents" is the real problem — it's wrong (create_agent → reg.factory → the registry-applied wrap does inject it), and it directly contradicts how emr works. Recommend dropping the explicit wrap, passing factory=_factory directly, and removing the comment (or correcting it to note the registry handles namespacing). Functionally fine to merge as-is; this is about not seeding the wrong pattern into the agents that copy this one next.

🟢 Now-dead skip test (tests/unit/agents/test_email_agent.py:286)

test_connectors_demo_required_connections_are_proper_objects calls reg._register_builtin_agents() then reg.get("connectors-demo"), which now returns None → permanent pytest.skip. The assertion never runs. The hub package's test_required_connections_surface_in_registration (which uses reg.discover()) already covers this. Recommend deleting the dead test, or switch it to reg.discover() if you want the coverage to stay in the core suite.

🟢 Stale path in docstring (tests/unit/connectors/test_formatting.py:7)

References "copy-pasting the body back into connectors_demo/agent.py" — that path no longer exists under src/. Trivial; repoint to hub/agents/python/connectors-demo/... or drop the parenthetical.

Strengths

• Accurate mirror of the code/emr hub layout — lazy __getattr__ re-export keeps registry discovery cheap, and pyproject.toml / gaia-agent.yaml match the sibling packages (deps, entry-point group, min_gaia_version).
• Genuinely complete cleanup: reserved-id set, setup.py packages list, the builtin: → installed: id flip across runtime and tests, and doc links all moved together — no half-migrated references left in src//tests//docs/.
• CI workflow is consistent with test_code_agent.yml (draft gating, path filters, install order) and correctly added to the test-summary needs list so a failure actually blocks.

Verdict

Approve with suggestions. No blocking issues. Worth fixing the misleading comment + redundant wrap before this becomes the template for the rest of the #1102 chat-family wave; the two 🟢 test nits are optional cleanup.