Boss Agent Consolidation and Frontend Integration Plan

Purpose

Unify the multiple "Boss Agent" implementations (Claude-first ADK, legacy Gemini-first backend, Pub/Sub orchestrator) into a single production-grade service that the command-center UI and all 32 cells can rely on. This plan outlines the target architecture, migration path, and delivery steps to align APIs, routing, and capabilities.

Target End-State Architecture

• Single Boss Agent service
• Runs the Claude-first ADK runtime as the canonical implementation.
• Hosts a unified REST surface with:
  • /agents/{id}/execute (UI compatibility; forwards to routing pipeline).
  • /process (direct invocation for cells/automations).
  • /status and /health (ops readiness + registry diagnostics).
• Maintains the full cell/agent registry (32 cells + MOA/MOE/Coding MOA and any external employees) with capability tags and URLs.

• Provides actionful responses (structured actions + metadata) and supports text + audio transcript inputs.

• REWOO orchestrator compatibility

• Treat the REWOO-based orchestrator as a planning/execution module inside the unified Boss Agent rather than a separate deployment. It reuses the same registry, A2A protocol, and model selection/fallback policy.
• Expose REWOO flows through the same REST paths (/agents/{id}/execute → REWOO plan/work/observe pipeline) so the frontend and cells do not need bespoke endpoints.

• Keep Pub/Sub triggers optional: REWOO tasks arriving on topics pass through the bridge worker and then into the shared routing pipeline.

• Adapter/gateway layer (if needed during transition)

• Lightweight shim that maps legacy /api/v1/chat callers to /agents/{id}/execute.

• Pub/Sub bridge that translates orchestrator topic messages into REST calls on the consolidated Boss Agent.

• Shared service integrations

• Anthropic Vertex (primary model), Gemini (fallback/consensus), Firestore (for chat memory when required), Pub/Sub (async flows), and registry-backed cell URLs.
• Observability via centralized logging/metrics; registry health checks invoked by /status.

Key Capabilities to Preserve/Combine

• Routing intelligence: explicit cell references, keyword/capability mapping, consensus/MOA routing for complex tasks.
• Registry completeness: keep the full configured registry from the Claude-first ADK; augment with any missing external employees or specialized services.
• Transcript handling: accept text or audio-derived transcripts; return structured actions compatible with downstream automations.
• Health + coverage checks: ping registry entries; expose readiness signals for frontend and ops.

Frontend Alignment

• UI calls {AGENTS_BASE_URL}/agents/{id}/execute; ensure Boss Agent exposes this route and maps {id} to registry entries (cells, MOA/MOE, coding MOA, external employees as needed).
• Provide a routing map in config (agent id → registry key) so the UI and Boss share consistent identifiers.
• Mock fallback should be disabled in environments where the consolidated Boss Agent URL is configured to avoid silent misrouting.
• Wiring verification for the command-center UI
• Update environment configs to set AGENTS_BASE_URL to the consolidated Boss Agent per environment (dev/stage/prod) and remove legacy URLs.
• Add an automated UI smoke test that hits /agents/{id}/execute for at least one real cell (and a REWOO-enabled path) to confirm non-mocked responses.
• Instrument the Boss Agent to log caller Origin/Referer for /agents/{id}/execute so we can confirm the UI is reaching the right backend and not the shim.
• Ship a lightweight adapter in the UI (or edge proxy) that returns a clear error banner if the Boss Agent URL is missing/unreachable, rather than silently falling back to mocks.

Migration Plan

1. Select canonical runtime: adopt the Claude-first ADK as baseline; freeze changes to legacy Gemini-first backend and Pub/Sub orchestrator except for bridge shims.
2. API unification: - Add /agents/{id}/execute handler that delegates to existing routing logic. - Keep /process for backward compatibility; ensure both paths flow through the same routing pipeline.
3. Registry consolidation: - Merge full registry (32 cells + MOA/MOE/Coding MOA) with any additional external employee agents. - Standardize capability tags and URLs; add health-check metadata for /status.
4. Model strategy: - Default to Anthropic Vertex (Claude); configure Gemini as always-available fallback with automatic failover so operational capacity is maintained even if the primary provider degrades. - Document model selection rules (e.g., coding tasks → Claude, data-heavy analysis → Gemini) and define fail-open policies: if the primary call fails or breaches latency/error thresholds, route the same prompt to Gemini and return a flagged fallback response with telemetry. - Add periodic synthetic probes that exercise both Claude and Gemini to ensure credentials/quotas stay warm and failover remains healthy.
5. Persistence + memory: - Use Firestore only when conversational memory is required; decouple core routing from storage.
6. Pub/Sub bridge: - Implement a lightweight worker that reads legacy boss-agent-sub and POSTs to /process on the consolidated service; publish responses back if consumers still expect Pub/Sub.
7. REWOO orchestrator enablement: - Embed REWOO plan/work/observe stages inside the consolidated Boss Agent as a selectable routing mode (e.g., strategy=rewoo), so requests can opt-in without a separate binary. - Reuse the unified registry and A2A protocol for REWOO layer agents; emit evidence to the same observability stack and fallback models under the shared policy.
8. Deprecation: - Mark legacy /api/v1/chat and standalone Pub/Sub orchestrator as deprecated; provide cutover dates and observability to detect residual traffic.

Delivery Steps

• Milestone 1: API and registry
• Implement /agents/{id}/execute and shared routing pipeline.
• Import and validate the full registry; add health-checking to /status.
• Milestone 2: Bridges
• Add the REST shim for /api/v1/chat callers.
• Deploy the Pub/Sub bridge worker; confirm topic wiring.
• Milestone 3: REWOO enablement
• Wire the REWOO planning/execution module into the shared routing pipeline and expose it via /agents/{id}/execute.
• Confirm REWOO layer agents call cells through the registry/A2A protocol and honor the shared Claude/Gemini fallback policy.
• Milestone 4: Frontend wiring
• Set {AGENTS_BASE_URL} to the consolidated Boss Agent in each environment.
• Remove or disable UI mock fallbacks; add UI-level error surfacing if the boss is unreachable.
• Milestone 5: Observability & hardening
• Add structured logging for routing decisions and registry health.
• Configure alerts on /health and registry ping failures.
• Milestone 6: Decommission
• Monitor legacy endpoints; once idle, remove legacy deployments and Pub/Sub topics.

Risks and Mitigations

• Naming confusion: Multiple “Boss Agent” binaries. Mitigation: publish a canonical service name/URL and mark legacy binaries as deprecated in docs and deployment manifests.
• Registry drift: Services added in one stack but not another. Mitigation: single source of truth registry file with CI checks and /status validation.
• Endpoint mismatch: UI vs backend paths. Mitigation: mandatory /agents/{id}/execute plus shims for /api/v1/chat until callers are updated.
• Model divergence: Different defaults yield different outputs. Mitigation: documented model-selection policy and a fallback strategy with telemetry on model usage.
• Transition downtime: Cutovers may break if shims misroute. Mitigation: canary deployment with mirrored traffic and alerting on error spikes.

Success Criteria

• Command-center UI calls one Boss Agent URL and receives non-mocked responses.
• All 32 cells + MOA/MOE/Coding MOA are invokable via /agents/{id}/execute and registry health checks pass.
• Legacy endpoints show zero traffic; Pub/Sub bridge confirms no pending messages before shutdown.
• Routing logs show correct capability matches and model-selection decisions.