feat(supervisor): multi-agent registry, composition UI, and supervisor runtime

[sami-marreed]

Feature

Closes #101

Summary

Adds a multi-agent registry to the manage UI (create/list/delete agents, single or supervisor kind), a supervisor composition screen for adding internal or A2A sub-agents, and wires the supervisor into the live chat runtime end-to-end.

Backend registry

• GET/POST /api/agents, DELETE /api/agents/{id} — list/create/delete agents (agents_routes.py)

Manage UI

• Dashboard: create/delete agents, "Supervisor" tag, per-agent Chat link
• Composition screen: Sub-agents panel (add internal agent or A2A endpoint), plan-approval toggle, persisted via a new PATCH /api/manage/config/draft/supervisor

Supervisor runtime

• Per-request X-Agent-ID resolution in /stream with a built-graph cache, invalidated on draft-save/publish
• DynamicAgentGraph takes a per-agent supervisor_agents/supervisor_enabled override instead of only reading the global settings.supervisor.enabled YAML toggle
• Root-cause routing fix: TaskAnalyzer.should_use_supervisor_mode only ever checked the global setting, so a per-agent supervisor never actually routed into the CugaSupervisor node at runtime even though the graph was built correctly. Added a state.supervisor_mode override (same pattern as lite_mode) that event_stream sets when the resolved agent is a supervisor.
• Plan-approval HITL gate reusing the existing interrupt()/ActionResponse path (create_agent_approval_action, already had frontend support in the chat card renderer). Required adding AgentState.supervisor_metadata, which the resume flow depends on but which didn't exist on the outer state.
• Fixed a silent bug where hyphenated agent ids (e.g. crm-agent, the normal case for any UI-created agent) produced delegate_to_crm-agent, an invalid Python identifier that parses as subtraction — breaking both delegation itself and the plan-approval gate's code-scan matcher.

Chat UI

• /chat/:agentId route, an agent switcher in the chat header, X-Agent-ID threaded through postStream and the conversation endpoints (previously hardcoded to cuga-default)

CLI

• cuga start manager --seed-supervisor-demo preloads a CRM/email/filesystem sub-agent trio + supervisor (draft + published) and provisions their tools, for local testing without manual setup

Test infra

• tests/unit/conftest.py and src/cuga/sdk_core/tests/conftest.py: autouse fixture that isolates DB-touching tests to a temp DBS_DIR instead of the shared local cuga.db a running dev server also uses (several tests call reset_config_db(), which previously could delete/corrupt a live server's database)

Testing

• Tested locally; unit tests pass (tests/unit/, src/cuga/sdk_core/tests/, src/cuga/backend/cuga_graph/nodes/cuga_agent_core/tests/) — no regressions vs. the pre-existing baseline (verified via git stash -u diffing)
• ruff check clean on all touched files
• Frontend tsc/webpack build clean (same pre-existing baseline errors, no new ones)
• Live-verified end-to-end with a real LLM (Groq) against an isolated throwaway DB: supervisor routing, delegation, execution-output streaming, and the hyphenated-agent-id fix
• Plan-approval pause → approve → resume round-trip — reconstructed from reading the LangGraph control flow and fixed real gaps found along the way, but not exercised against a live UI click-through. Please test before relying on it.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 064e1479-8d5e-435a-9c2b-c528cc8aab76

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/101-supervisor-multi-agent-ui

---

_{Comment @coderabbitai help to get the list of available commands.}